NAME

termio − general terminal interface

SYNOPSIS

#include <sys/termios.h>

DESCRIPTION

Asynchronous communications ports, pseudo-terminals, and the special interface accessed by /dev/tty all use the same general interface, no matter what hardware (if any) is involved.  The remainder of this section discusses the common features of this interface. 

Opening a Terminal Device File

When a terminal file is opened, the process normally waits until a connection is established.  (In practice, users’ programs seldom open these files; they are opened by getty(8) and become a user’s standard input, output, and error files.)  If the O_NDELAY flag was set in the second argument to open(2V), the open() will complete immediately without waiting for a connection to be established. 

Process Groups

A terminal may have a distinguished process group associated with it.  This distinguished process group plays a special role in handling signal-generating input characters, as discussed below in the Special Characters section below. 

A command interpreter, such as csh(1), that supports “job control” can allocate the terminal to different jobs, or process groups, by placing related processes in a single process group and associating this process group with the terminal.  A terminal’s associated process group may be set or examined by a process with sufficient privileges. The terminal interface aids in this allocation by restricting access to the terminal by processes that are not in the current process group; see Job Access Control below. 

The Controlling Terminal

A terminal may belong to a process as its controlling terminal. If a process that is a “session process group leader”, and that does not have a controlling terminal, opens a terminal file not already associated with a process group, the terminal associated with that terminal file becomes the controlling terminal for that process, and the terminal’s distinguished process group is set to the process group of that process. (Currently, this also happens if a process that does not have a controlling terminal and is not a member of a process group opens a terminal.  In this case, if the terminal is not associated with a process group, a new process group is created with a process group ID equal to the process ID of the process in question, and the terminal is assigned to that process group.  The process is made a member of the terminal’s process group.) 

The controlling terminal is inherited by a child process during a fork(2).  A process relinquishes its control terminal when it changes its process group using setpgrp(2V) or when it issues a TIOCNOTTY ioctl(2) call on a file descriptor created by opening the file /dev/tty. 

When a session process group leader that has a controlling terminal terminates, the distinguished process group of the controlling terminal is set to zero (indicating no distinguished process group).  This allows the terminal to be acquired as a controlling terminal by a new session process group leader. 

Closing a Terminal Device File

When a terminal device file is closed, the process closing the file waits until all output is drained; all pending input is then flushed, and finally a disconnect is performed.  If HUPCL is set, the existing connection is severed (by hanging up the phone line, if appropriate). 

Job Access Control

If a process is in the (non-zero) distinguished process group of its controlling terminal, or if the terminal’s distinguished process group is zero (if either of these are true, the process is said to be a foreground process), then read(2V) operations are allowed as described below in Input Processing and Reading Characters.  If a process is not in the (non-zero) distinguished process group of its controlling terminal (if this is true, the process is said to be a background process), then any attempts to read from that terminal will send that process’ process group a SIGTTIN signal, unless the process is ignoring SIGTTIN, has SIGTTIN blocked, or is in the middle of process creation using vfork(2); in that case, the read will return −1 and set errno to EIO, and the SIGTTIN signal will not be sent.  The SIGTTIN signal will normally stop the members of that process group. 

When the TOSTOP bit is set in the c_lflag field, attempts by a background process to write to its controlling terminal will send that process’ process group a SIGTTOU signal, unless the process is ignoring SIGTTOU, has SIGTTOU blocked, or is in the middle of process creation using vfork(); in that case, the process will be allowed to write to the terminal and the SIGTTOU signal will not be sent. The SIGTTOU signal will normally stop the members of that process group.  Certain ioctl() calls that set terminal parameters are treated in this same fashion, except that TOSTOP is not checked; the effect is identical to that of terminal writes when TOSTOP is set.  See IOCTLS. 

Input Processing and Reading Characters

A terminal associated with one of these files ordinarily operates in full-duplex mode.  Characters may be typed at any time, even while output is occurring, and are only lost when the system’s character input buffers become completely full, which is rare, or when the user has accumulated the maximum allowed number of input characters that have not yet been read by some program.  Currently, this limit is 256 characters.  If the IMAXBEL mode has not been selected, all the saved characters are thrown away without notice when the input limit is reached; if the IMAXBEL mode has been selected, the driver refuses to accept any further input, and echoes a bell (ASCII BEL). 

Two general kinds of input processing are available, determined by whether the terminal device file is in canonical mode or non-canonical mode (see ICANON in the Local Modes section). 

The style of input processing can also be very different when the terminal is put in non-blocking I/O mode; see read(2V).  In this case, reads from the terminal will never block. 

It is possible to simulate terminal input using the TIOCSTI ioctl() call, which takes, as its third argument, the address of a character.  The system pretends that this character was typed on the argument terminal, which must be the process’ controlling terminal unless the process’ effective user ID is super-user. 

Canonical Mode Input Processing

In canonical mode input processing, terminal input is processed in units of lines.  A line is delimited by a NEWLINE (ASCII LF) character, an EOF (by default, an ASCII EOT) character, or one of two user-specified end-of-line characters, EOL and EOL2.  This means that a read() will not complete until an entire line has been typed or a signal has been received.  Also, no matter how many characters are requested in the read call, at most one line will be returned.  It is not, however, necessary to read a whole line at once; any number of characters may be requested in a read, even one, without losing information. 

Erase and kill processing occurs during input.  The ERASE character (by default, the character DEL) erases the last character typed in the current input line.  The WERASE character (by default, the character CTRL-W) erases the last “word” typed in the current input line (but not any preceding SPACE or TAB characters).  A “word” is defined as a sequence of non-blank characters, with TAB characters counted as blanks.  Neither ERASE nor WERASE will erase beyond the beginning of the line.  The KILL character (by default, the character CTRL-U) kills (deletes) the entire current input line, and optionally outputs a NEWLINE character.  All these characters operate on a key-stroke basis, independently of any backspacing or tabbing that may have been done. 

The REPRINT character (the character CTRL-R) prints a NEWLINE followed by all characters that have not been read.  Reprinting also occurs automatically if characters that would normally be erased from the screen are fouled by program output.  The characters are reprinted as if they were being echoed; as a consequence, if ECHO is not set, they are not printed. 

The ERASE and KILL characters may be entered literally by preceding them with the escape character (\).  In this case the escape character is not read.  The ERASE and KILL characters may be changed. 

Non-Canonical Mode Input Processing

In non-canonical mode input processing, input characters are not assembled into lines, and erase and kill processing does not occur.  The MIN and TIME values are used to determine how to process the characters received. 

MIN represents the minimum number of characters that should be received when the read is satisfied (when the characters are returned to the user).  TIME is a timer of 0.10 second granularity that is used to timeout bursty and short term data transmissions.  The four possible values for MIN and TIME and their interactions are described below. 

Case A: MIN > 0, TIME > 0

In this case TIME serves as an intercharacter timer and is activated after the first character is received. Since it is an intercharacter timer, it is reset after a character is received.  The interaction between MIN and TIME is as follows: as soon as one character is received, the intercharacter timer is started.  If MIN characters are received before the intercharacter timer expires (remember that the timer is reset upon receipt of each character), the read is satisfied.  If the timer expires before MIN characters are received, the characters received to that point are returned to the user.  Note: if MIN expires at least one character will be returned because the timer would not have been enabled unless a character was received.  In this case (MIN > 0, TIME > 0) the read will sleep until the MIN and TIME mechanisms are activated by the receipt of the first character. 

Case B: MIN > 0, TIME = 0

In this case, since the value of TIME is zero, the timer plays no role and only MIN is significant.  A pending read is not satisfied until MIN characters are received (the pending read will sleep until MIN characters are received).  A program that uses this case to read record-based terminal I/O may block indefinitely in the read operation. 

Case C: MIN = 0, TIME > 0

In this case, since MIN = 0, TIME no longer represents an intercharacter timer.  It now serves as a read timer that is activated as soon as a read() is done.  A read is satisfied as soon as a single character is received or the read timer expires.  Note: in this case if the timer expires, no character will be returned.  If the timer does not expire, the only way the read can be satisfied is if a character is received.  In this case the read will not block indefinitely waiting for a character − if no character is received within TIME∗.10 seconds after the read is initiated, the read will return with zero characters. 

Case D: MIN = 0, TIME = 0

In this case return is immediate.  The minimum of either the number of characters requested or the number of characters currently available will be returned without waiting for more characters to be input. 

Comparison of the Different Cases of MIN, TIME Interaction

Some points to note about MIN and TIME:

1.In the following explanations one may notice that the interactions of MIN and TIME are not symmetric.  For example, when MIN > 0 and TIME = 0, TIME has no effect.  However, in the opposite case where MIN = 0 and TIME > 0, both MIN and TIME play a role in that MIN is satisfied with the receipt of a single character. 

2.Also note that in case A (MIN > 0, TIME > 0), TIME represents an intercharacter timer while in case C (TIME = 0, TIME > 0) TIME represents a read timer. 

These two points highlight the dual purpose of the MIN/TIME feature.  Cases A and B, where MIN > 0, exist to handle burst mode activity (for example, file transfer programs) where a program would like to process at least MIN characters at a time.  In case A, the intercharacter timer is activated by a user as a safety measure; while in case B, it is turned off. 

Cases C and D exist to handle single character timed transfers.  These cases are readily adaptable to screen-based applications that need to know if a character is present in the input queue before refreshing the screen. In case C the read is timed; while in case D, it is not. 

Another important note is that MIN is always just a minimum.  It does not denote a record length.  That is, if a program does a read of 20 bytes, MIN is 10, and 25 characters are present, 20 characters will be returned to the user. 

Writing Characters

When one or more characters are written, they are transmitted to the terminal as soon as previously-written characters have finished typing.  Input characters are echoed as they are typed if echoing has been enabled.  If a process produces characters more rapidly than they can be typed, it will be suspended when its output queue exceeds some limit.  When the queue has drained down to some threshold, the program is resumed. 

Special Characters

Certain characters have special functions on input and/or output.  These functions and their default character values are summarized as follows:

INTR (CTRL-C or ASCII ETX) generates a SIGINT signal, which is sent to all processes in the distinguished process group associated with the terminal.  Normally, each such process is forced to terminate, but arrangements may be made either to ignore the signal or to receive a trap to an agreed-upon location; see sigvec(2). 

QUIT (CTRL-│ or ASCII FS) generates a SIGQUIT signal, which is sent to all processes in the distinguished process group associated with the terminal.  Its treatment is identical to the interrupt signal except that, unless a receiving process has made other arrangements, it will not only be terminated but a core image file (called core) will be created in the current working directory. 

ERASE (Rubout or ASCII DEL) erases the preceding character.  It will not erase beyond the start of a line, as delimited by a NL, EOF, EOL, or EOL2 character. 

WERASE (CTRL-W or ASCII ETB) erases the preceding “word”.  It will not erase beyond the start of a line, as delimited by a NL, EOF, EOL, or EOL2 character. 

KILL (CTRL-U or ASCII NAK) deletes the entire line, as delimited by a NL, EOF, EOL, or EOL2 character. 

REPRINT (CTRL-R or ASCII DC2) reprints all characters that have not been read, preceded by a NEWLINE. 

EOF (CTRL-D or ASCII EOT) may be used to generate an end-of-file from a terminal.  When received, all the characters waiting to be read are immediately passed to the program, without waiting for a NEWLINE, and the EOF is discarded.  Thus, if there are no characters waiting, which is to say the EOF occurred at the beginning of a line, zero characters will be passed back, which is the standard end-of-file indication. 

NL (ASCII LF) is the normal line delimiter.  It can not be changed; it can, however, be escaped by the LNEXT character. 

EOL

EOL2 (ASCII NUL) are additional line delimiters, like NL.  They are not normally used. 

SUSP (CTRL-Z or ASCII EM) is used by the job control facility to change the current job to return to the controlling job.  It generates a SIGTSTP signal, which stops all processes in the terminal’s process group. 

STOP (CTRL-S or ASCII DC3) can be used to temporarily suspend output.  It is useful with CRT terminals to prevent output from disappearing before it can be read.  While output is suspended, STOP characters are ignored and not read. 

START (CTRL-Q or ASCII DC1) is used to resume output that has been suspended by a STOP character.  While output is not suspended, START characters are ignored and not read. 

DISCARD (CTRL-O or ASCII SI) causes subsequent output to be discarded until another DISCARD character is typed, more input arrives, or the condition is cleared by a program. 

LNEXT (CTRL-V or ASCII SYN) causes the special meaning of the next character to be ignored; this works for all the special characters mentioned above.  This allows characters to be input that would otherwise get interpreted by the system (for example, KILL, QUIT.) 

The character values for INTR, QUIT, ERASE, WERASE, KILL, REPRINT, EOF, EOL, EOL2, SUSP, STOP, START, DISCARD, and LNEXT may be changed to suit individual tastes.  If the value of a special control character is 0, the function of that special control character will be disabled.  The ERASE, KILL, and EOF characters may be escaped by a preceding \ character, in which case no special function is done.  Any of the special characters may be preceded by the LNEXT character, in which case no special function is done. 

Modem Disconnect

If a modem disconnect is detected, and the CLOCAL flag is not set in the c_cflag field, a SIGHUP signal is sent to all processes in the distinguished process group associated with this terminal.  Unless other arrangements have been made, this signal terminates the processes.  If SIGHUP is ignored or caught, any subsequent read() returns with an end-of-file indication until the terminal is closed.  Thus, programs that read a terminal and test for end-of-file can terminate appropriately after a disconnect.  Any subsequent write() will return −1 and set errno to EIO until the terminal is closed. 

Terminal Parameters

The parameters that control the behavior of devices and modules providing the termios interface are specified by the termios structure, defined by <sys/termios.h>.  Several ioctl() system calls that fetch or change these parameters use this structure:

#defineNCCS17
structtermios {
unsignedlongc_iflag; /∗ input modes ∗/
unsignedlongc_oflag; /∗ output modes ∗/
unsignedlongc_cflag; /∗ control modes ∗/
unsignedlongc_lflag; /∗ local modes ∗/
unsignedcharc_line; /∗ line discipline ∗/
unsignedcharc_cc[NCCS]; /∗ control chars ∗/
};

The special control characters are defined by the array c_cc.  The relative positions and initial values for each function are as follows:

0VINTRETX
1VQUITFS
2VERASEDEL
3VKILLNAK
4VEOFEOT
5VEOLNUL
6VEOL2NUL
7VSWTCHNUL
8VSTARTDC1
9VSTOPDC3
10VSUSPEM
12VREPRINTDC2
13VDISCARDSI
14VWERASEETB
15VLNEXTSYN

The MIN value is stored in the VMIN element of the c_cc array, and the TIME value is stored in the VTIME element of the c_cc array.  The VMIN element is the same element as the VEOF element, and the VTIME element is the same element as the VEOL element. 

Input Modes

The c_iflag field describes the basic terminal input control:

IGNBRK0000001Ignore break condition.
BRKINT0000002Signal interrupt on break.
IGNPAR0000004Ignore characters with parity errors.
PARMRK0000010Mark parity errors.
INPCK0000020Enable input parity check.
ISTRIP0000040Strip character.
INLCR0000100Map NL to CR on input.
IGNCR0000200Ignore CR.
ICRNL0000400Map CR to NL on input.
IUCLC0001000Map upper-case to lower-case on input.
IXON0002000Enable start/stop output control.
IXANY0004000Enable any character to restart output.
IXOFF0010000Enable start/stop input control.
IMAXBEL0020000Echo BEL on input line too long.

If IGNBRK is set, a break condition (a character framing error with data all zeros) detected on input is ignored, that is, not put on the input queue and therefore not read by any process.  Otherwise, if BRKINT is set, a break condition will generate a SIGINT and flush both the input and output queues.  If neither IGNBRK nor BRKINT is set, a break condition is read as a single ASCII NUL character (´\0´). 

If IGNPAR is set, characters with framing or parity errors (other than break) are ignored.  Otherwise, if PARMRK is set, a character with a framing or parity error that is not ignored is read as the three-character sequence: ´\377´, ´\0´, X, where X is the data of the character received in error.  To avoid ambiguity in this case, if ISTRIP is not set, a valid character of ´\377´ is read as ´\377´, ´\377´.  If neither IGNPAR nor PARMRK is set, a framing or parity error (other than break) is read as a single ASCII NUL character (´\0´). 

If INPCK is set, input parity checking is enabled.  If INPCK is not set, input parity checking is disabled.  This allows output parity generation without input parity errors. 

If ISTRIP is set, valid input characters are first stripped to 7 bits, otherwise all 8 bits are processed. 

If INLCR is set, a received NL character is translated into a CR character.  If IGNCR is set, a received CR character is ignored (not read).  Otherwise if ICRNL is set, a received CR character is translated into a NL character. 

If IUCLC is set, a received upper-case alphabetic character is translated into the corresponding lower-case character. 

If IXON is set, start/stop output control is enabled.  A received STOP character will suspend output and a received START character will restart output.  The STOP and START characters will not be read, but will merely perform flow control functions.  If IXANY is set, any input character will restart output that has been suspended. 

If IXOFF is set, the system will transmit a STOP character when the input queue is nearly full, and a START character when enough input has been read that the input queue is nearly empty again. 

If IMAXBEL is set, the ASCII BEL character is echoed if the input stream overflows.  Further input will not be stored, but any input already present in the input stream will not be disturbed.  If IMAXBEL is not set, no BEL character is echoed, and all input present in the input queue is discarded if the input stream overflows. 

The initial input control value is BRKINT, ICRNL, IXON, ISTRIP. 

Output modes

The c_oflag field specifies the system treatment of output:

OPOST0000001Postprocess output.
OLCUC0000002Map lower case to upper on output.
ONLCR0000004Map NL to CR-NL on output.
OCRNL0000010Map CR to NL on output.
ONOCR0000020No CR output at column 0.
ONLRET0000040NL performs CR function.
OFILL0000100Use fill characters for delay.
OFDEL0000200Fill is DEL, else NUL.
NLDLY0000400Select new-line delays:
  NL00
  NL10000400
CRDLY0003000Select carriage-return delays:
  CR00
  CR10001000
  CR20002000
  CR30003000
TABDLY0014000Select horizontal-tab delays:
  TAB00         or tab expansion:
  TAB10004000
  TAB20010000
  XTABS0014000Expand tabs to spaces.
BSDLY0020000Select backspace delays:
  BS00
  BS10020000
VTDLY0040000Select vertical-tab delays:
  VT00
  VT10040000
FFDLY0100000Select form-feed delays:
  FF00
  FF10100000

If OPOST is set, output characters are post-processed as indicated by the remaining flags, otherwise characters are transmitted without change. 

If OLCUC is set, a lower-case alphabetic character is transmitted as the corresponding upper-case character.  This function is often used in conjunction with IUCLC. 

If ONLCR is set, the NL character is transmitted as the CR-NL character pair.  If OCRNL is set, the CR character is transmitted as the NL character.  If ONOCR is set, no CR character is transmitted when at column 0 (first position).  If ONLRET is set, the NL character is assumed to do the carriage-return function; the column pointer will be set to 0 and the delays specified for CR will be used.  Otherwise the NL character is assumed to do just the line-feed function; the column pointer will remain unchanged.  The column pointer is also set to 0 if the CR character is actually transmitted. 

The delay bits specify how long transmission stops to allow for mechanical or other movement when certain characters are sent to the terminal.  In all cases a value of 0 indicates no delay.  If OFILL is set, fill characters will be transmitted for delay instead of a timed delay.  This is useful for high baud rate terminals that need only a minimal delay.  If OFDEL is set, the fill character is DEL, otherwise NUL. 

If a form-feed or vertical-tab delay is specified, it lasts for about 2 seconds. 

New-line delay lasts about 0.10 seconds.  If ONLRET is set, the RETURN delays are used instead of the NEWLINE delays.  If OFILL is set, two fill characters will be transmitted. 

Carriage-return delay type 1 is dependent on the current column position, type 2 is about 0.10 seconds, and type 3 is about 0.15 seconds.  If OFILL is set, delay type 1 transmits two fill characters, and type 2, four fill characters. 

Horizontal-tab delay type 1 is dependent on the current column position.  Type 2 is about 0.10 seconds.  Type 3, specified by TAB3 or XTABS, specifies that TAB characters are to be expanded into SPACE characters.  If OFILL is set, two fill characters will be transmitted for any delay. 

Backspace delay lasts about 0.05 seconds.  If OFILL is set, one fill character will be transmitted. 

The actual delays depend on line speed and system load. 

The initial output control value is OPOST, ONLCR, XTABS. 

The c_cflag field describes the hardware control of the terminal:

CBAUD0000017Baud rate:
  B00Hang up
  B50000000150 baud
  B75000000275 baud
  B1100000003110 baud
  B1340000004134.5 baud
  B1500000005150 baud
  B2000000006200 baud
  B3000000007300 baud
  B6000000010600 baud
  B120000000111200 baud
  B180000000121800 baud
  B240000000132400 baud
  B480000000144800 baud
  B960000000159600 baud
  B19200000001619200 baud
  B38400000001738400 baud
CSIZE0000060Character size:
  CS505 bits
  CS600000206 bits
  CS700000407 bits
  CS800000608 bits
CSTOPB0000100Send two stop bits, else one.
CREAD0000200Enable receiver.
PARENB0000400Parity enable.
PARODD0001000Odd parity, else even.
HUPCL0002000Hang up on last close.
CLOCAL0004000Local line, else dial-up.
CRTSCTS0010000Enable RTS/CTS flow control.
CIBAUD03600000Input baud rate, if different from output rate.

The CBAUD bits specify the baud rate.  The zero baud rate, B0, is used to hang up the connection.  If B0 is specified, the modem control lines will cease to be asserted.  Normally, this will disconnect the line.  If the CIBAUD bits are not zero, they specify the input baud rate, with the CBAUD bits specifying the output baud rate; otherwise, the output and input baud rates are both specified by the CBAUD bits.  The values for the CIBAUD bits are the same as the values for the CBAUD bits, shifted left IBSHIFT bits.  For any particular hardware, impossible speed changes are ignored. 

The CSIZE bits specify the character size in bits for both transmission and reception.  This size does not include the parity bit, if any.  If CSTOPB is set, two stop bits are used, otherwise one stop bit.  For example, at 110 baud, two stop bits are required. 

If PARENB is set, parity generation and detection is enabled and a parity bit is added to each character.  If parity is enabled, the PARODD flag specifies odd parity if set, otherwise even parity is used. 

If CREAD is set, the receiver is enabled.  Otherwise no characters will be received. 

If HUPCL is set, the modem control lines for the port will be disconnected when the last process with the line open closes it or terminates. 

If CLOCAL is set, a connection does not depend on the state of the modem status lines.  Otherwise modem control is assumed. 

If CRTSCTS is set, and the terminal has modem control lines associated with it, the Request To Send (RTS) modem control line will be raised, and output will occur only if the Clear To Send (CTS) modem status line is raised.  If the CTS modem status line is lowered, output is suspended until CTS is raised.  Some hardware may not support this function, and other hardware may not permit it to be disabled; in either of these cases, the state of the CRTSCTS flag is ignored. 

The initial hardware control value after open is B9600, CS7, CREAD, PARENB. 

Local Modes

The c_lflag field of the argument structure is used by the line discipline to control terminal functions.  The basic line discipline provides the following:

ISIG0000001Enable signals.
ICANON0000002Canonical input (erase and kill processing).
XCASE0000004Canonical upper/lower presentation.
ECHO0000010Enable echo.
ECHOE0000020Echo erase character as BS-SP-BS.
ECHOK0000040Echo NL after kill character.
ECHONL0000100Echo NL.
NOFLSH0000200Disable flush after interrupt or quit.
TOSTOP0000400Send SIGTTOU for background output.
ECHOCTL0001000Echo control characters as ^char, delete as ^?.
ECHOPRT0002000Echo erase character as character erased.
ECHOKE0004000BS-SP-BS erase entire line on line kill.
FLUSHO0040000Output is being flushed.
PENDIN0100000Retype pending input at next read or input character.

If ISIG is set, each input character is checked against the special control characters INTR, QUIT, and SUSP.  If an input character matches one of these control characters, the function associated with that character is performed.  If ISIG is not set, no checking is done.  Thus these special input functions are possible only if ISIG is set. 

If ICANON is set, canonical processing is enabled.  This enables the erase, word erase, kill, and reprint edit functions, and the assembly of input characters into lines delimited by NL, EOF, EOL, and EOL2.  If ICANON is not set, read requests are satisfied directly from the input queue.  A read will not be satisfied until at least MIN characters have been received or the timeout value TIME has expired between characters.  This allows fast bursts of input to be read efficiently while still allowing single character input.  The time value represents tenths of seconds.  See the Non-canonical Mode Input Processing section for more details. 

If XCASE is set, and if ICANON is set, an upper-case letter is accepted on input by preceding it with a \ character, and is output preceded by a \ character.  In this mode, the following escape sequences are generated on output and accepted on input:

for: use:

` \´

│ \! 

~ \^

{ \(

} \)

\ \\

For example, A is input as \a, \n as \\n, and \N as \\\n. 

If ECHO is set, characters are echoed as received.  If ECHO is not set, input characters are not echoed. 

If ECHOCTL is not set, all control characters (characters with codes between 0 and 37 octal) are echoed as themselves.  If ECHOCTL is set, all control characters other than ASCII TAB, ASCII NL, the START character, and the STOP character, are echoed as ^X, where X is the character given by adding 100 octal to the control character’s code (so that the character with octal code 1 is echoed as ‘^A’), and the ASCII DEL character, with code 177 octal, is echoed as ‘^?’. 

When ICANON is set, the following echo functions are possible:

1.If ECHO and ECHOE are set, and ECHOPRT is not set, the ERASE and WERASE characters are echoed as one or more ASCII BS SP BS, which will clear the last character(s) from a CRT screen. 

2.If ECHO and ECHOPRT are set, the first ERASE and WERASE character in a sequence echoes as a backslash (\) followed by the characters being erased.  Subsequent ERASE and WERASE characters echo the characters being erased, in reverse order.  The next non-erase character types a slash (/) before it is echoed. 

3.If ECHOKE is set, the kill character is echoed by erasing each character on the line from the screen (using the mechanism selected by ECHOE and ECHOPRT). 

4.If ECHOK is set, and ECHOKE is not set, the NL character will be echoed after the kill character to emphasize that the line will be deleted.  Note: an escape character (\) or an LNEXT character preceding the erase or kill character removes any special function. 

5.If ECHONL is set, the NL character will be echoed even if ECHO is not set.  This is useful for terminals set to local echo (so-called half duplex). 

6.If ECHOCTL is not set, the EOF character is not echoed, unless it is escaped.  Because EOT is the default EOF character, this prevents terminals that respond to EOT from hanging up.  If ECHOCTL is set, the EOF character is echoed; if it is not escaped, after it is echoed, one backspace character is output if it is echoed as itself, and two backspace characters are echoed if it is echoed as ^X. 

If NOFLSH is set, the normal flush of the input and output queues associated with the INTR, QUIT, and SUSP characters will not be done. 

If TOSTOP is set, the signal SIGTTOU is sent to a process that tries to write to its controlling terminal if it is not in the distinguished process group for that terminal.  This signal normally stops the process.  Otherwise, the output generated by that process is output to the current output stream.  Processes that are blocking or ignoring SIGTTOU signals are excepted and allowed to produce output. 

If FLUSHO is set, data written to the terminal will be discarded.  This bit is set when the FLUSH character is typed.  A program can cancel the effect of typing the FLUSH character by clearing FLUSHO. 

If PENDIN is set, any input that has not yet been read will be reprinted when the next character arrives as input. 

The initial line-discipline control value is ISIG, ICANON, ECHO. 

Minimum and Timeout

The MIN and TIME values are described above under Non-canonical Mode Input Processing.  The initial value of MIN is 1, and the initial value of TIME is 0. 

Termio Structure

The System V termio structure is used by other ioctl() calls; it is defined by <sys/termio.h> as:

#defineNCC8
structtermio {
unsignedshortc_iflag; /∗ input modes ∗/
unsignedshortc_oflag; /∗ output modes ∗/
unsignedshortc_cflag; /∗ control modes ∗/
unsignedshortc_lflag; /∗ local modes ∗/
charc_line;/∗ line discipline ∗/
unsignedcharc_cc[NCC]; /∗ control chars ∗/
};

The special control characters are defined by the array c_cc.  The relative positions for each function are as follows:

0VINTR
1VQUIT
2VERASE
3VKILL
4VEOF
5VEOL
6VEOL2
7reserved

The calls that use the termio structure only affect the flags and control characters that can be stored in the termio structure; all other flags and control characters are unaffected. 

Terminal Size

The number of lines and columns on the terminal’s display (or page, in the case of printing terminals) is specified in the winsize structure, defined by <sys/termios.h>.  Several ioctl() system calls that fetch or change these parameters use this structure:

struct winsize {
unsigned shortws_row; /∗ rows, in characters ∗/
unsigned shortws_col; /∗ columns, in characters ∗/
unsigned shortws_xpixel; /∗ horizontal size, pixels - not used ∗/
unsigned shortws_ypixel; /∗ vertical size, pixels - not used ∗/
};

Modem Lines

On special files representing serial ports, the modem control lines supported by the hardware can be read and the modem status lines supported by the hardware can be changed.  The following modem control and status lines may be supported by a device; they are defined by <sys/termios.h>:

TIOCM_LE0001line enable
TIOCM_DTR0002data terminal ready
TIOCM_RTS0004request to send
TIOCM_ST0010secondary transmit
TIOCM_SR0020secondary receive
TIOCM_CTS0040clear to send
TIOCM_CAR0100carrier detect
TIOCM_RNG0200ring
TIOCM_DSR0400data set ready

TIOCM_CD is a synonym for TIOCM_CAR, and TIOCM_RI is a synonym for TIOCM_RNG. 

Not all of these will necessarily be supported by any particular device; check the manual page for the device in question. 

IOCTLS

The ioctl() calls supported by devices and STREAMS modules providing the termios interface are listed below.  Some calls may not be supported by all devices or modules. 

Unless otherwise noted for a specific ioctl() call, these functions are restricted from use by background processes.  Attempts to perform these calls will cause the process group of the process performing the call to be sent a SIGTTOU signal.  If the process is ignoring SIGTTOU, has SIGTTOU blocked, or is in the middle of process creation using vfork(), the process will be allowed to perform the call and the SIGTTOU signal will not be sent. 

TCGETS The argument is a pointer to a termios structure.  The current terminal parameters are fetched and stored into that structure.  This call is allowed from a background process; however, the information may subsequently be changed by a foreground process. 

TCSETS The argument is a pointer to a termios structure.  The current terminal parameters are set from the values stored in that structure.  The change is immediate. 

TCSETSW The argument is a pointer to a termios structure.  The current terminal parameters are set from the values stored in that structure.  The change occurs after all characters queued for output have been transmitted.  This form should be used when changing parameters that will affect output. 

TCSETSF The argument is a pointer to a termios structure.  The current terminal parameters are set from the values stored in that structure.  The change occurs after all characters queued for output have been transmitted; all characters queued for input are discarded and then the change occurs. 

TCGETA The argument is a pointer to a termio structure.  The current terminal parameters are fetched, and those parameters that can be stored in a termio structure are stored into that structure.  This call is allowed from a background process; however, the information may subsequently be changed by a foreground process. 

TCSETA The argument is a pointer to a termio structure.  Those terminal parameters that can be stored in a termio structure are set from the values stored in that structure.  The change is immediate. 

TCSETAW The argument is a pointer to a termio structure.  Those terminal parameters that can be stored in a termio structure are set from the values stored in that structure.  The change occurs after all characters queued for output have been transmitted.  This form should be used when changing parameters that will affect output. 

TCSETAF The argument is a pointer to a termio structure.  Those terminal parameters that can be stored in a termio structure are set from the values stored in that structure.  The change occurs after all characters queued for output have been transmitted; all characters queued for input are discarded and then the change occurs. 

TCSBRK The argument is an int value.  Wait for the output to drain.  If the argument is 0, then send a break (zero-valued bits for 0.25 seconds). 

TCXONC Start/stop control.  The argument is an int value.  If the argument is 0, suspend output; if 1, restart suspended output; if 2, suspend input; if 3, restart suspended input. 

TCFLSH The argument is an int value.  If the argument is 0, flush the input queue; if 1, flush the output queue; if 2, flush both the input and output queues. 

TIOCEXCL The argument is ignored.  Exclusive-use mode is turned on; no further opens are permitted until the file has been closed, or a TIOCNXCL is issued.  The default on open of a terminal file is that exclusive use mode is off. 

TIOCNXCL The argument is ignored.  Exclusive-use mode is turned off. 

TIOCGPGRP The argument is a pointer to an int.  Set the value of that int to the process group ID of the distinguished process group associated with the terminal.  This call is allowed from a background process; however, the information may subsequently be changed by a foreground process. 

TIOCSPGRP The argument is a pointer to an int.  Associate the process group whose process group ID is specified by the value of that int with the terminal.  The new process group value must be in the range of valid process group ID values, or it must be zero (“no process group”).  Otherwise, the error EINVAL is returned.  If any processes exist with a process ID or process group ID that is the same as the new process group value, then those processes must have the same real or saved user ID as the real or effective user ID of the calling process or be descendants of the calling process, or the effective user ID of the current process must be super-user.  Otherwise, the error EPERM is returned. 

TIOCOUTQ The argument is a pointer to an int.  Set the value of that int to the number of characters in the output stream that have not yet been sent to the terminal.  This call is allowed from a background process. 

TIOCSTI The argument is a pointer to a char.  Pretend that that character had been received as input. 

TIOCGWINSZ The argument is a pointer to a winsize structure.  The terminal driver’s notion of the terminal size is stored into that structure.  This call is allowed from a background process. 

TIOCSWINSZ The argument is a pointer to a winsize structure.  The terminal driver’s notion of the terminal size is set from the values specified in that structure.  If the new sizes are different from the old sizes, a SIGWINCH signal is sent to the process group of the terminal. 

TIOCMGET The argument is a pointer to an int.  The current state of the modem status lines is fetched and stored in the int pointed to by the argument.  This call is allowed from a background process. 

TIOCMBIS The argument is a pointer to an int whose value is a mask containing modem control lines to be turned on.  The control lines whose bits are set in the argument are turned on; no other control lines are affected. 

TIOCMBIC The argument is a pointer to an int whose value is a mask containing modem control lines to be turned off.  The control lines whose bits are set in the argument are turned off; no other control lines are affected. 

TIOCMSET The argument is a pointer to an int containing a new set of modem control lines.  The modem control lines are turned on or off, depending on whether the bit for that mode is set or clear. 

SEE ALSO

csh(1), stty(1V), fork(2), ioctl(2), open(2V), read(2V), setpgrp(2V), sigvec(2), vfork(2), tty(4), getty(8)

Sun Release 4.0  —  Last change: 26 February 1988