tcsetattr() — Set the attributes for a terminal

Changes the attributes associated with a terminal. New attributes are specified with a termios control structure. Programs should always issue a tcgetattr() first, modify the desired fields, and then issue a tcsetattr(). tcsetattr() should never be issued using a termios structure that was not obtained using tcgetattr(). tcsetattr() should use only a termios structure that was obtained by tcgetattr().

fd

Indicates an open file descriptor associated with a terminal.

when

Indicates a symbol, defined in the termios.h header file, specifying when to change the terminal attributes:

Symbol

Meaning

TCSANOW

The change should take place immediately.

TCSADRAIN

The change should take place after all output written to fd has been read by the master pseudoterminal. Use this value when changing terminal attributes that affect output.

TCSAFLUSH

The change should take place after all output written to fd has been sent; in addition, all input that has been received but not read should be discarded (flushed) before the change is made.

*termptr

A pointer to a termios control structure containing the desired terminal attributes.

A termios structure contains the following members:

tcflag_t c_iflag

Input modes. tcflag_t is defined in the termios.h header file. Each bit in c_iflag indicates an input attribute and is associated with a symbol defined in the termios.h include file. All symbols are bitwise distinct. Thus c_iflag is the bitwise inclusive-OR of several of these symbols. Possible symbols are:

Symbol

Meaning

BRKINT

Indicates that an interrupt should be generated if the user types a BREAK.

ICRNL

Automatically converts input carriage returns to newline (line-feed) characters before they are passed to the application that reads the input.

IGNBRK

Ignores BREAK conditions. If this bit is set to 1, applications are not informed of any BREAK condition on the terminal; the setting of BRKINT has no effect.

If IGNBRK is 0 but BRKINT is 1, BREAK flushes all input and output queues. In addition, if the terminal is the controlling terminal of a foreground process group, the BREAK condition generates a single SIGINT signal for that foreground process group.

If both IGNBRK and BRKINT are 0, a BREAK condition is taken as the single input character NULL, if PARMRK is 0, and as the three input characters \377-NULL-NULL, if PARMRK is 1.

IGNCR

Ignores input carriage returns. If this bit is set to 1, the setting of ICRNL has no effect.

If IGNCR is 0 and ICRNL is 1, input carriage returns are converted to newline characters. For z/OS® UNIX "NL" or '\n' is the EBCDIC character NL.

IGNPAR

Ignores input characters (other than BREAK) that have parity errors.

INLCR

Automatically converts input newline (line-feed) characters to carriage returns before they are passed to the application that reads the input.

INPCK

Enables input parity checking. If this bit is set to 0, it allows output parity generation without input parity errors. The enabling of input parity checking is independent of the enabling of parity checking in the control modes field. (See the description of “tcflag_t c_cflag,” which follows.) While the control modes may dictate that the hardware recognizes the parity bit, but the terminal special file does not check whether this bit is set correctly.

ISTRIP

Strips valid input bytes to 7 bits. If this bit is set to 0, the complete byte is processed.

Note: Do not set this bit for pseudoterminals, since it will make the terminal unusable. If you strip the first bit off of EBCDIC characters, you destroy all printable EBCDIC characters.

IUCLC

Map uppercase to lowercase on the received character. In locales other than the POSIX locale, the mapping is unspecified. Thus, this function only applies to the characters in the POSIX-portable character set that have lowercase equivalents, namely the characters A-Z.

Note:

This symbol is kept for historical reasons. It was part of the Legacy Feature in Single UNIX Specification, Version 2, but has been withdrawn and is not supported as part of Single UNIX Specification, Version 3.

If it is necessary to continue using this symbol in an application written for Single UNIX Specification, Version 3, define the feature test macro _UNIX03_WITHDRAWN before including any standard system headers. The macro exposes all interfaces and symbols removed in Single UNIX Specification, Version 3.

IXANY

Enable any character to restart output. If IXOFF and IXANY are set and a previous STOP character has been received, then receipt of any input character will cause the STOP condition to be removed. For pseudoterminals, data in the output queue is passed to the application during master read() processing, and slave pseudoterminal writes are allowed to proceed. The character which caused the output to restart is also processed normally as well (unless it is a STOP character).

IXOFF

Enables start/stop input control. If this bit is set to 1, the system attempts to prevent the number of bytes in the input queue from exceeding the MAX_INPUT value. It sends one or more STOP characters to the terminal device when the input queue is in danger of filling up. The character used as the STOP character is dictated by the c_cc member of the termios structure. It is intended to tell the terminal to stop sending input for a while. The system transmits one or more START characters when it appears that there is space in the input queues for more input. Again, the character used as the START character is dictated by the c_cc member. It is intended to tell the terminal that it can resume transmission of input.

Note: Do not use IXOFF while in DBCS mode. If you intersperse STOP and START characters inside DBCS data while using IXOFF, you could corrupt output data,

IXON

Enables start/stop output control. If the system receives a STOP character as input, it will suspend output on the associated terminal until a START character is received. An application reading input from the terminal does not see STOP or START characters; they are intercepted by the system, which does all the necessary processing.

If IXON is 0, any STOP or START characters read are passed on as input to an application reading from the terminal.

PARMRK

Marks characters with parity errors. If this bit is set to 1 and IGNPAR is 0, a byte with a framing or parity error is sent to the application as the characters \377 and NULL, followed by the data part of the byte that had the parity error. If ISTRIP is 0, a valid input character of \377 is sent as a pair of characters \377, \377 to avoid ambiguity.

If both PARMRK and IGNPAR are 0, a character with a framing or parity error is sent to the application as NULL.

tcflag_t c_oflag

Output modes. Each bit in c_oflag indicates an output attribute, and is associated with a symbol defined in the termios.h header file. Thus c_oflag is the bitwise inclusive-OR of a number of these symbols. Possible symbols are:

Symbol

Meaning

OPOST

Modifies lines of text in an implementation-defined way to appear appropriately on the terminal device. If this bit is set to 0, characters that an application puts out are sent without change.

OLCUC

If OPOST and OLCUC are set, then map lowercase to uppercase on the output. In locales other that the POSIX locale, the mapping is unspecified. Thus, this function only applies to the characters in the POSIX-portable character set that have uppercase equivalents, namely the characters a-z.

Note:

This symbol is kept for historical reasons. It was part of the Legacy Feature in Single UNIX Specification, Version 2, but has been withdrawn and is not supported as part of Single UNIX Specification, Version 3.

If it is necessary to continue using this symbol in an application written for Single UNIX Specification, Version 3, define the feature test macro _UNIX03_WITHDRAWN before including any standard system headers. The macro exposes all interfaces and symbols removed in Single UNIX Specification, Version 3.

ONLCR

If OPOST and ONLCR are set, the NL character is transmitted as the CR-NL character pair.

OCRNL

If OPOST and OCRNL are set, the CR character is transmitted as the NL character.

ONOCR

If OPOST and ONOCR are set, no CR character is transmitted if the current column is zero.

ONLRET

If OPOST and ONLRET are set, the NL character does the carriage return function; the column pointer is set to 0. If OPOST is set and ONLRET is not set, then the NL does the line-feed function; the column pointer is unchanged.

OFILL

Fill characters are used for delay instead of using a timed delay.

OFDEL

The fill character is DEL. If OFILL is not set, then the fill character is NUL.

NLDLY

Delay associated with newline character.

NL0

No delay.

NL1

0.10 seconds delay. If ONLRET is set, then carriage-return delays are used instead of newline delays. If OFILL is set, then two fill characters are transmitted.

CRDLY

Delay associated with carriage-return character.

CR0

No delay.

CR1

Delay dependent on column position, or if OFILL is set then two fill characters are transmitted.

CR2

0.10 seconds delay, or if OFILL is set then four fill characters are transmitted.

CR3

0.15 seconds delay.

TABDLY

Delay associated with tab character.

TAB0

No horizontal tab processing.

TAB1

Delay dependent on column position, or if OFILL is set then two fill characters are transmitted.

TAB2

0.10 seconds delay, or if OFILL is set then two fill characters are transmitted.

TAB3

Tabs are expanded into spaces.

BSDLY

Delay associated with backspace character.

BS0

No delay.

BS1

0.05 seconds delay, or if OFILL is set then one fill character is transmitted.

VTDLY

Delay associated with vertical-tab processing.

VT0

No delay.

VT1

2 seconds delay.

FFDLY

Delay associated with form-feed processing.

FF0

No delay.

FF1

2 seconds delay.

tcflag_t c_cflag

Control modes. Each bit in c_cflag indicates a control attribute and is associated with a symbol defined in the termios.h header file. Thus c_cflag is the bitwise inclusive-OR of several of these symbols. Possible symbols are:

Symbol

Meaning

CLOCAL

Ignores modem status lines. A call to open() returns immediately without waiting for a modem connection to complete. If this bit is set to 0, modem status lines are monitored and open() waits for the modem connection.

CREAD

Enables reception. If this bit is set to 0, no input characters are received from the terminal.

Using z/OS UNIX pseudoterminal support, this bit is always enabled and set to 1.

CSIZE

Is a collection of bits indicating the number of bits per byte (not counting the parity bit, if any). These bits specify byte size for both transmission and reception. Possible settings of CSIZE are given with the following symbols:

   CS5 - 5 bits per byte
   CS6 - 6 bits per byte
   CS7 - 7 bits per byte
   CS8 - 8 bits per byte

Using z/OS UNIX pseudoterminal support, all values are accepted, but CSIZE is changed to CS8. Using z/OS UNIX Outboard Communications Server (OCS) support, the specified value is used.

CSTOPB

Sends two stop bits when necessary. If CSTOPB is 0, only one stop bit is used.

Using z/OS UNIX pseudoterminal support, this bit is always 0. Using z/OS UNIX OCS support, the specified value is used.

HUPCL

Lowers the modem control lines for a port when the last process that has the port open closes the port (or the process ends). In other words, this tells the system to hang up when all relevant processes have finished using the port.

For pseudoterminals HUPCL controls what happens when the slave pseudoterminals is closed. If HUPCL is set when the last file descriptor for the slave pseudoterminal is closed, then the slave pseudoterminal cannot be re-opened. The master terminal has to be closed and re-opened before the pair can be used again.

PARENB

Enables parity generation and detection. A parity bit is added to each character on output, and expected from each character on input.

Under z/OS UNIX, if this bit is set to 1 in a request, it is ignored. It is always set to 0. Using z/OS UNIX OCS support, the specified value is used.

PARODD

Indicates odd parity (when parity is enabled). If PARODD is 0, even parity is used (when parity is enabled).

Under z/OS UNIX, if this bit is set to 1 in a request, it is ignored. It is always set to 0. Using z/OS UNIX OCS support, the specified value is used.

If the object for which the control modes are set is not an asynchronous serial connection, some bits may be ignored. For example, on a network connection, it may not be possible to set the baud rate.

tcflag_t c_lflag

Local modes. Each bit in c_lflag indicates a local attribute, and is associated with a symbol defined in the termios.h include file. Thus c_lflag is the bitwise inclusive-OR of a number of these symbols. Possible symbols are:

Symbol

Meaning

ECHO

Echoes input characters back to the terminal. If this is bit is 0, input characters are not echoed.

ECHOE

Echoes the ERASE character as an error-correcting backspace. When the user inputs an ERASE character, the terminal erases the last character in the current line from the display (if possible). The character used as the ERASE character is dictated by the c_cc member of the termios structure. ECHOE has an effect only if the ICANON bit is 1.

ECHOK

Either causes the terminal to erase the line from the display, or echoes the KILL character followed by an \n character. ECHOK has an effect only if the ICANON bit is set to 1.

ECHONL

Echoes the newline (line-feed) character ‘\n’ even if the ECHO bit is off. ECHONL has an effect only if the ICANON bit is set to 1.

ICANON

Enables canonical input processing, also called line mode. Input is not delivered to the application until an entire line has been input. The end of a line is indicated by a newline, End Of File (EOF), or EOL character (where the character used as the EOL character is directed by the c_cc member of the termios structure [described shortly]). Canonical input processing uses the ERASE character to erase a single input character, and the KILL character to erase an entire line. The MAX_CANON value specifies the maximum number of bytes in an input line in canonical mode.

If ICANON is 0, read requests take input directly from the input queue; the system does not wait for the user to enter a complete line. This is called noncanonical mode. ERASE and KILL characters are not handled by the system but passed directly to the application. See also the descriptions of MIN and TIME in the c_cc member.

IEXTEN

Enables extended implementation-defined functions. These are not defined, and IEXTEN is always set to 0.

If the ERASE, KILL or EOF character is preceded by a backslash character, the special character is placed in the input queue without doing the "special character" processing and the backslash is discarded.

ISIG

If ISIG is set to 1, signals are generated if special control characters are entered. SIGINT is generated if INTR is entered; SIGQUIT is generated if QUIT is entered; and SIGTSTP is generated if SUSP is entered and job control is supported. The special control characters are controlled by the c_cc member.

If ISIG is 0, the system does not generate signals when these special control characters are entered.

NOFLSH

If this bit is set to 1, the system does not flush the input and output queues if a signal is generated by one of the special characters described in ISIG above. If NOFLSH is set to 0, the queues are flushed if one of the special characters is found.

TOSTOP

If this bit is set to 1, a SIGTTOU signal is sent to the process group of a process that tries to write to a terminal when it is not in the terminal's foreground process group. However, if the process that tries to write to the terminal is blocking or ignoring SIGTTOU signals, the system does not raise the SIGTTOU signal.

If TOSTOP is 0, output from background processes is output to the current output stream, and no signal is raised.

XCASE

Do canonical lower and canonical upper presentation. In locales other than the POSIX locale, the effect is unspecified. XCASE set by itself makes all uppercase letters on input and output be preceded by a "\" character.

Some terminals can generate lowercase characters, but can display only uppercase characters. For these terminals, XCASE would be used by itself. Other terminals cannot generate lowercase characters either. For these terminals, XCASE would be used with IUCLC to generate lowercase characters when characters are typed without the backslash, and uppercase characters when the typed character is preceded by a backslash.

If a terminal can generate only uppercase characters, but can display either upper or lowercase, then XCASE would be used with OLCUC.

Note:

This symbol is kept for historical reasons. It was part of the Legacy Feature in Single UNIX Specification, Version 2, but has been withdrawn and is not supported as part of Single UNIX Specification, Version 3.

If it is necessary to continue using this symbol in an application written for Single UNIX Specification, Version 3, define the feature test macro _UNIX03_WITHDRAWN before including any standard system headers. The macro exposes all interfaces and symbols removed in Single UNIX Specification, Version 3.

cc_t c_cc[NCCS]

Control characters. This is an array of characters that may have special meaning for terminal handling. You can access characters in this array using subscripts that are symbols defined in the termios.h header file. For example, the STOP character is given by c_cc[VSTOP]. Possible subscript symbols are:

Symbol

Meaning

VEOF

Gives the End Of File character EOF. It is recognized only in canonical (line) mode. When this is found in input, all bytes waiting to be read are immediately passed to the application without waiting for the end of the line. The EOF character itself is discarded. If EOF occurs at the beginning of a line, the read function that tries to read that line receives an End Of File (EOF) indication. Note that EOF results in End Of File only if it is at the beginning of a line; if it is preceded by one or more characters, it indicates only End Of Line (EOL).

VEOL

Gives the End Of Line character EOL. It is recognized only in canonical (line) mode. This is an alternate character for marking the end of a line (in addition to the newline \n).

VERASE

Gives the ERASE character. It is recognized only in canonical (line) mode. It deletes the last character in the current line. It cannot delete beyond the beginning of the line.

VINTR

Gives the interrupt character INTR. It is recognized only if ISIG is set to 1 in c_lflag. If the character is received, the system sends a SIGINT signal to all the processes in the foreground process group that has this device as its controlling terminal.

VKILL

Gives the KILL character. It is recognized only in canonical (line) mode. It deletes the entire contents of the current line.

VMIN

Gives the MIN value for noncanonical mode processing.

This is the minimum number of bytes that a call to read should return in noncanonical mode; it is not used in canonical mode.

If both MIN and TIME are greater than 0, read returns when MIN characters are available or when the timer associated with TIME runs out (whichever comes first). The timer starts running as soon as a single character has been entered; if there is already a character in the queue when read is called, the timer starts running immediately.

If MIN is greater than zero and TIME is zero, read waits for MIN characters to be entered, no matter how long that takes.

If MIN is zero and TIME is greater than zero, read returns when the timer runs out or when a single character is received (whichever comes first). read returns either one character (if one is received) or zero (if the timer runs out). The timer starts running as soon as read is called. (Contrast this with the case where MIN and TIME are both greater than zero, and the timer starts only when a character is received.)

If both MIN and TIME are zero, read returns immediately from every call. It returns the number of bytes that are immediately available, up to the maximum specified in the call to read.

VQUIT

Gives the quit character QUIT. It is recognized only if ISIG is set to 1 in c_lflag. If the character is received, the system sends a SIGQUIT signal to all the processes in the foreground process group that has this device as its controlling terminal.

VSUSP

Gives the suspend character SUSP. It is recognized only if ISIG is set to 1 in c_lflag. If the character is received, the system sends a SIGTSTP signal to all the processes in the foreground process group that has this device as its controlling terminal.

VTIME

Gives the TIME value, used in noncanonical mode in connection with MIN. It expresses a time in terms of tenths of a second.

VSTOP

Gives the STOP character. You can use this to suspend output temporarily when IXON is set to 1 in c_iflag. Users can enter the STOP character to prevent output from running off the top of a display screen.

VSTART

Gives the START character. You can use this to resume suspended output when IXON is set to 1 in c_iflag.

If unsuccessful, tcsetattr() returns -1 and sets errno to one of the following values:

Error Code

Description

EBADF

fildes is not a valid open file descriptor.

EINTR

A signal interrupted tcsetattr().

EINVAL

when is not a recognized value, or some entry in the supplied termios structure had an incorrect value.

EIO

The process group of the process issuing the function is an orphaned, background process group, and the process issuing the function is not ignoring or blocking SIGTTOU.

ENOTTY

fildes is not associated with a terminal.

CELEBT09

/* CELEBT09

   The following attributes changes the terminal attributes.

 */
#define _POSIX_SOURCE
#include <termios.h>
#include <unistd.h>
#include <stdio.h>

main() {
  struct termios term1, term2;

  if (tcgetattr(STDIN_FILENO, &term1) != 0)
    perror("tcgetattr() error");
  else {
    printf("the original end-of-file character is x'%02x'\n",
           term1.c_cc[VEOF]);
    term1.c_cc[VEOF] = 'z';
    if (tcsetattr(STDIN_FILENO, TCSANOW, &term1) != 0)
      perror("tcsetattr() error");
    if (tcgetattr(STDIN_FILENO, &term1) != 0)
      perror("tcgetattr() error");
    else
      printf("the new end-of-file character is x'%02x'\n",
             term1.c_cc[VEOF]);
  }
}

Output

the original End Of File character is x'37'
the new End Of File character is x'a9'