tcsetattr -- Set Terminal Attributes

SYNOPSIS

 #include <termios.h>

 int tcsetattr(int fileDescriptor, int actions,
              struct termios *terminfo);

DESCRIPTION

tcsetattr set the attributes of a terminal device. The attributes are stored in a termios structure prior to calling the tcsetattr function. The normal sequence is to call tcgetattr to obtain the current attribute settings, modify the termios structure to contain the new settings, and then set the terminal attributes with a call to tcsetattr.

The following arguments are passed to tcsetattr:

fileDescriptor

is a file discriptor that refers to a terminal device.

action

is a symbolic constant that controls when the attributes are set. The values of action are defined in <termios.h> and may be one of the following:

TCSANOW: sets terminal attributes immediately.
TCSADRAIN: sets the terminal attributes after all output that has aleady been written to the terminal is transmitted. TCSADRAIN should be specified when setting terminal attributes that could affect output.
TCSAFLUSH: sets the terminal attributes after all output that has already been written to the terminal is transmitted. Input that has been received, but not read, is discarded.

terminfo

is the address of a termios structure. The members of termios, which is declared in <termios.h>, are flags that identify terminal modes and control characters. The tcsetattr function sets the attributes of the terminal referred to by fileDescriptor based on the information contained in this structure.

termios structure

The termios structure is declared in <termios.h> as follows:

 typedef int tcflag_t;
 typedef char cc_t;

 #define NCCS 11          /* number of special control characters */ -->

 struct termios {
    tcflag_t c_cflag;     /* control modes                        */ -->
    tcflag_t c_iflag;     /* input modes                          */ -->
    tcflag_t c_lflag;     /* local modes                          */ -->
    tcflag_t c_oflag;     /* output modes                         */ -->
    cc_t c_cc[NCCS];      /* control characters and values        */ -->
 };

Each of the members of type tcflag_t is constructed from bitmasks that are also declared in <termios.h>. The c_cc[NCCS] array contains control characters that have special meaning for terminal handling.

Refer to The POSIX.1 Standard: A Programmer's Guide, by Fred Zlotnick, for portable information about the bitmasks of the termios structure. Also refer to Assembler Callable Services for OpenEdition MVS (SC23-3020) for operating-system-specific details.

RETURN VALUE

tcsetattr returns a 0 if successful and a -1 if unsuccessful. If tcsetattr is called from a background process, with a file descriptor that refers to the controlling terminal for the process, a SIGTTOU signal may be generated. This will cause the function call to be unsuccessful, returning a -1 and setting errno to EINTR. If SIGTTOU is blocked, the function call proceeds normally.

EXAMPLE

The following example illustrates the use of tcsetattr to change the terminal attributes of a TTY device:

  #include <sys/types.h>
  #include <termios.h>
  #include <unistd.h>
  #include <stdio.h>
  #include <stdlib.h>

  #define NOTATTY 1

  main()
  {
     int ttyDevice = STDOUT_FILENO;
     struct termios termAttributes;

        /* Make sure file descriptor is for a TTY device.         */
     if ( ! isatty(ttyDevice) )
        return(NOTATTY);

        /* Get terminal attributes and then determine if terminal */
        /* start and stop is enabled. If IXON is on, turn it off  */
        /* and call tcsetattr.                                    */
     else {
        if (tcgetattr(ttyDevice, &termAttributes) != 0) {
           perror("tcgetattr error");
           return(EXIT_FAILURE);
        }
        else {
           if (termAttributes.c_iflag & IXON) {
              termAttributes.c_iflag = termAttributes.c_iflag ^ IXON;
              if (tcsetattr(ttyDevice, TCSANOW, &termAttributes) != 0) {
                 perror("tcsetattr error");
                 return(EXIT_FAILURE);
              }
              printf("IXON disabled. START and STOP characters n");
              printf("will be passed to the application.n");
              }
           else
              printf("IXON was already set to 0.n");
        }
     }
     return(EXIT_SUCCESS);
  }

RELATED FUNCTIONS

cfsetispeed, cfsetospeed,