TERMIO(4)

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. The state of the software carrier flag will effect the ability to open a line.

  Sessions

Processes are now grouped by session, then process group, then process id. Each session is associated with one “login” session (windows count as logins). A process creates a session by calling setsid(2V), which will put the process in a new session as its only member and as the session leader of that session.

  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. The terminal's process group can can be set only to process groups that are members of the terminal's session.

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.

  Orphaned Process Groups

An orphaned process group is a process group that has no parent, in a different process group, and in the same session. In other words, there is no process that can handle job control signals for the process group.

  The Controlling Terminal

A terminal may belong to a process as its controlling terminal. If a process that is a session leader, and that does not have a controlling terminal, opens a terminal file not already associated with a session, 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 session, a new session is created with a process group ID equal to the process ID of the process in question, and the terminal is assigned to that session. The process is made a member of the terminal's process group.)

If a process does not wish to acquire the terminal as a controlling terminal (as is the case with many daemons that open /dev/console), the process should or O_NOCTTY into the second argument to open(2V).

The controlling terminal is inherited by a child process during a fork(2V). A process relinquishes its control terminal when it changes its process group using setsid(2V), when it trys to change back to process group 0 via a setpgrp(2V) with arguments (mypid, 0), or when it issues a TIOCNOTTY ioctl(2) call on a file descriptor created by opening the file /dev/tty. Both of the last two cases cause a setsid(2V) to be called on the process' behalf. This is an attempt to allow old binaries (that couldn't have known about setsid(2V)) to still acquire controlling terminals. It doesn't always work, see setsid(8V) for a workaround for those cases.

When a session 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 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 (if this is 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 typically send that process' process group a SIGTTIN signal. If the process is ignoring SIGTTIN, has SIGTTIN blocked, is a member of an orphaned process group, or is in the middle of process creation using vfork(2), 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 typically send that process' process group 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 write to the terminal and the SIGTTOU signal will not be sent. If the process is orphaned, the write will return -1 and set errno to EIO, and the SIGTTOU signal will not be sent. 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. This limit is available is {MAX_CANON} characters (see pathconf(2V)). 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:

•   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.

•   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.

If IEXTEN is added to the local modes (this is the default), then all of the special characters are in effect. If IEXTEN is cleared from the local modes, then only the following POSIX.1 compatible specials are seen as specials: INTR, QUIT, ERASE, KILL, EOF, NL, EOL, SUSP, STOP, START, and CR.

  Software Carrier Mode

The software carrier mode can be enabled or disabled using the TIOCSSOFTCAR ioctl(). If the software carrier flag for a line is off, the line pays attention to the hardware carrier detect (DCD) signal. The tty device associated with the line can not be opened until DCD is asserted. If the software carrier flag is on, the line behaves as if DCD is always asserted.

The software carrier flag is usually turned on for locally connected terminals or other devices, and is off for lines with modems.

To be able to issue the TIOCGSOFTCAR and TIOCSSOFTCAR ioctl() calls, the tty line should be opened with O_NDELAY so that the open(2V) will not wait for the carrier.

  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.

A SIGHUP signal is sent to the tty if the software carrier flag is off and the hardware carrier detect drops.

  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:

    #define	NCCS	17
    struct	termios {
    	unsigned	long	c_iflag;	/* input modes */
    	unsigned	long	c_oflag;	/* output modes */
    	unsigned	long	c_cflag;	/* control modes */
    	unsigned	long	c_lflag;	/* local modes */
    	unsigned	char	c_line;		/* line discipline */
    	unsigned	char	c_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:
    0	VINTR	ETX
    1	VQUIT	FS
    2	VERASE	DEL
    3	VKILL	NAK
    4	VEOF	EOT
    5	VEOL	NUL
    6	VEOL2	NUL
    7	VSWTCH	NUL
    8	VSTART	DC1
    9	VSTOP	DC3
    10	VSUSP	EM
    12	VREPRINT	DC2
    13	VDISCARD	SI
    14	VWERASE	ETB
    15	VLNEXT	SYN

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:

    IGNBRK	0000001	Ignore break condition.
    BRKINT	0000002	Signal interrupt on break.
    IGNPAR	0000004	Ignore characters with parity errors.
    PARMRK	0000010	Mark parity errors.
    INPCK	0000020	Enable input parity check.
    ISTRIP	0000040	Strip character.
    INLCR	0000100	Map NL to CR on input.
    IGNCR	0000200	Ignore CR.
    ICRNL	0000400	Map CR to NL on input.
    IUCLC	0001000	Map upper-case to lower-case on input.
    IXON	0002000	Enable start/stop output control.
    IXANY	0004000	Enable any character to restart output.
    IXOFF	0010000	Enable start/stop input control.
    IMAXBEL	0020000	Echo 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:

    OPOST	0000001	Postprocess output.
    OLCUC	0000002	Map lower case to upper on output.
    ONLCR	0000004	Map NL to CR-NL on output.
    OCRNL	0000010	Map CR to NL on output.
    ONOCR	0000020	No CR output at column 0.
    ONLRET	0000040	NL performs CR function.
    OFILL	0000100	Use fill characters for delay.
    OFDEL	0000200	Fill is DEL, else NUL.
    NLDLY	0000400	Select new-line delays:
      NL0	0
      NL1	0000400
    CRDLY	0003000	Select carriage-return delays:
      CR0	0
      CR1	0001000
      CR2	0002000
      CR3	0003000
    TABDLY	0014000	Select horizontal-tab delays:
      TAB0	0         or tab expansion:
      TAB1	0004000
      TAB2	0010000
      XTABS	0014000	Expand tabs to spaces.
    BSDLY	0020000	Select backspace delays:
      BS0	0
      BS1	0020000
    VTDLY	0040000	Select vertical-tab delays:
      VT0	0
      VT1	0040000
    FFDLY	0100000	Select form-feed delays:
      FF0	0
      FF1	0100000

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:

    CBAUD	0000017		Baud rate:
      B0	0		Hang up
      B50	0000001		50 baud
      B75	0000002		75 baud
      B110	0000003		110 baud
      B134	0000004		134.5 baud
      B150	0000005		150 baud
      B200	0000006		200 baud
      B300	0000007		300 baud
      B600	0000010		600 baud
      B1200	0000011		1200 baud
      B1800	0000012		1800 baud
      B2400	0000013		2400 baud
      B4800	0000014		4800 baud
      B9600	0000015		9600 baud
      B19200	0000016		19200 baud
      B38400	0000017		38400 baud
    CSIZE	0000060		Character size:
      CS5	0		5 bits
      CS6	0000020		6 bits
      CS7	0000040		7 bits
      CS8	0000060		8 bits
    CSTOPB	0000100		Send two stop bits, else one.
    CREAD	0000200		Enable receiver.
    PARENB	0000400		Parity enable.
    PARODD	0001000		Odd parity, else even.
    HUPCL	0002000		Hang up on last close.
    CLOCAL	0004000		Local line, else dial-up.
    CIBAUD	03600000		Input baud rate, if different from output rate.
    CRTSCTS	020000000000		Enable RTS/CTS flow control.

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:

    ISIG	0000001	Enable signals.
    ICANON	0000002	Canonical input (erase and kill processing).
    XCASE	0000004	Canonical upper/lower presentation.
    ECHO	0000010	Enable echo.
    ECHOE	0000020	Echo erase character as BS-SP-BS.
    ECHOK	0000040	Echo NL after kill character.
    ECHONL	0000100	Echo NL.
    NOFLSH	0000200	Disable flush after interrupt or quit.
    TOSTOP	0000400	Send SIGTTOU for background output.
    ECHOCTL	0001000	Echo control characters as ^char, delete as ^?.
    ECHOPRT	0002000	Echo erase character as character erased.
    ECHOKE	0004000	BS-SP-BS erase entire line on line kill.
    FLUSHO	0020000	Output is being flushed.
    PENDIN	0040000	Retype pending input at next read or input character.
    IEXTEN	0100000	Recognize all specials (if clear, POSIX only).

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 is affected by the IEXTEN bit (see Special Characters above). 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:

•   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.

•   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.

•   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).

•   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.

•   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).

•   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:

    #define	NCC	8
    struct	termio {
    	unsigned	short	c_iflag;	/* input modes */
    	unsigned	short	c_oflag;	/* output modes */
    	unsigned	short	c_cflag;	/* control modes */
    	unsigned	short	c_lflag;	/* local modes */
    	char		c_line;		/* line discipline */
    	unsigned	char	c_cc[NCC];	/* control chars */
    };

The special control characters are defined by the array c_cc. The relative positions for each function are as follows:
    0	VINTR
    1	VQUIT
    2	VERASE
    3	VKILL
    4	VEOF
    5	VEOL
    6	VEOL2
    7	reserved

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 short	ws_row;		/* rows, in characters */
    	unsigned short	ws_col;		/* columns, in characters */
    	unsigned short	ws_xpixel;	/* horizontal size, pixels - not used */
    	unsigned short	ws_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_LE	0001	line enable
    TIOCM_DTR	0002	data terminal ready
    TIOCM_RTS	0004	request to send
    TIOCM_ST	0010	secondary transmit
    TIOCM_SR	0020	secondary receive
    TIOCM_CTS	0040	clear to send
    TIOCM_CAR	0100	carrier detect
    TIOCM_RNG	0200	ring
    TIOCM_DSR	0400	data 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). This define is available by #include <sys/termio.h>

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

TCFLSH
    The argument is an int value. If the argument is TCIFLUSH (0), flush the input queue; if TCOFLUSH (1), flush the output queue; if TCIOFLUSH (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. This ioctl() is only available by #include <sys/ttold.h> .

TIOCNXCL
    The argument is ignored. Exclusive-use mode is turned off. This ioctl() is only available by #include <sys/ttold.h>.

TIOCSCTTY
    The argument is an int. The system will attempt to assign the terminal as the caller's controlling terminal (see The Controlling Terminal above). If the caller is not the super-user and/or the argument is not 1, all of the normal permission checks apply. If the caller is the super-user and the argument is 1 the terminal will be assigned as the controlling terminal even if the terminal was currently in use as a controlling terminal by another session. getty(8) uses this method to acquire controlling terminals for login(1) because there exists a possibility that a daemon process may obtain the console before getty(8).

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. This ioctl() exists only for backward compatibility, use tcgetpgrp(3V).

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. This ioctl() exists only for backward compatibility, use tcsetpgrp(), see tcgetpgrp(3V).

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 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.

TIOCGSOFTCAR
    The argument is a pointer to an int whose value is 1 or 0, depending on whether the software carrier detect is turned on or off.

TIOCSSOFTCAR
    The argument is a pointer to an int whose value is 1 or 0. The value of the integer should be 0 to turn off software carrier, or 1 to turn it on.

SEE ALSO
csh(1), login(1), stty(1V), fork(2V), getpgrp(2V), ioctl(2), open(2V), read(2V), sigvec(2), vfork(2), tcgetpgrp(3V), tty(4), ttytab(5), getty(8), init(8), ttysoftcar(8)