termio(M) 06 January 1993 termio(M) Name termio - general terminal interface Description All asynchronous communications ports use the same general interface, no matter what hardware is involved. The remainder of this section discusses the common features of this interface. Please refer to termios(M) for details of POSIX-specific extensions to termio. When a terminal file is opened, it normally causes the process to wait until a connection is established. In practice, users' programs seldom open these files; they are opened by getty(M) and become a user's stan- dard input, output, and error files. (To do this, getty(M) opens the terminal for read/write access, then FDUPs it twice.) The very first terminal file opened by the process group leader of a terminal file not already associated with a process group becomes the ``control terminal'' for that process group. The control terminal plays a special role in han- dling quit and interrupt signals, as discussed below. The control termi- nal is inherited by a child process during a fork(S). A process can break this association by changing its process group using setpgrp(S). A terminal associated with one of these files ordinarily operates in full duplex mode. Characters can be entered 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. When the input limit is reached, all the saved characters are thrown away without notice. Normally, terminal input is processed in units of lines. A line is de- limited by a newline (ASCII LF) character, an end-of-file (ASCII EOT) character, or an end-of-line (ASCII EOL) character. This means that a program attempting to read will be suspended until an entire line has been entered. Also, no matter how many characters are requested in the read call, one line will be returned at most. It is not, however, neces- sary to read a whole line at once; any number of characters, even one, may be requested in a read without losing information. Erase and kill processing is normally performed during input. By default, a <Ctrl>h or <Bksp> erases the last character typed, but it will not erase beyond the beginning of the line. By default, a <Ctrl>u kills (deletes) the entire input line, and optionally outputs a newline charac- ter. Both these characters operate on a keystroke basis, independent of any backspacing or tabbing that may have been done. Both 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 (see stty(C)). Certain characters have special functions on input. These functions and their default character values are summarized as follows: INTR (Rubout or ASCII DEL) Generates an interrupt signal which is sent to all processes with the associated control 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 signal(S). QUIT (<Ctrl>\ or ASCII FS) Generates a quit signal. Its treatment is identical to the interrupt signal except that, unless a receiving process has made other arrangements, it will not only be ter- minated, but a core image file (core) will be created in the current working directory. SWTCH (ASCII NUL) Is used by the shell layers facility, shl(C), to change the current layer to the control layer. ERASE (<Ctrl>h) Erases the preceding character. It will not erase beyond the start of a line, as delimited by an NL, EOF, or EOL character. KILL (<Ctrl>u) Deletes the entire line, as delimited by a NL, EOF, or EOL character. 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 charac- ters 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 cannot be changed or escaped. EOL (ASCII NUL) Is an additional line delimiter, like NL. It is not normally used. STOP (<Ctrl>s or ASCII DC3) Temporarily suspends 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) Resumes output which has been suspended by a STOP character. While output is not suspended, START charac- ters are ignored and not read. The START/STOP characters cannot be changed or escaped within termio (but see termios(M) for further information). The character values for INTR, QUIT, SWTCH, ERASE, KILL, EOF, and EOL may be changed to suit individual tastes. The ERASE, KILL, and EOF charac- ters may be escaped by a preceding backslash (\) character, in which case no special function is carried out. When the carrier signal from the dataset drops, a ``hangup'' signal is sent to all processes that have this terminal as the control terminal. Unless other arrangements have been made, this signal causes the pro- cesses to terminate. If the hangup signal is ignored, any subsequent read returns with an end-of-file indication. Thus, programs that read a ter- minal and test for an end-of-file can terminate appropriately when hung up on. When one or more characters are written, they are transmitted to the ter- minal as soon as the previously typed characters have been entered. Input characters are echoed by putting them in the output queue as they arrive. If a process produces characters more rapidly than they can be typed, it will be suspended when its output queue exceeds a given limit. When the queue has drained down to the given threshold, the program is resumed. ioctl commands Several ioctl(S) system calls apply to terminal files. The primary calls use the termio structure, defined in the file /usr/include/sys/termio.h: #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; /* line discipline modes */ char c_line; /* line discipline */ unsigned char c_cc[NCC]; /* control chars */ }; Primary ioctl(S) system calls have the form: ioctl (fildes, command, arg) struct termio *arg; Commands using this form are: TCGETA Get the parameters associated with the terminal and store them in the termio structure referenced by arg. TCSETA Set the parameters associated with the terminal from the struc- ture referenced by arg. The change is immediate. TCSETAW Wait for the output to drain before setting the new parameters. This form should be used when changing parameters that will affect output. TCSETAF Wait for the output to drain, then flush the input queue and set the new parameters. Additional ioctl(S) calls have the form: ioctl (fildes, command, arg) int arg; Commands using this form are: TCSBRK Wait for the output to drain. If arg is 0, then send a break (zero bits for 0.25 seconds). TCXONC Start/stop control. If arg is 0, suspend output; if 1, restart suspended output; if 2, block; if 3, unblock. TCFLSH If arg is 0, flush the input queue; if 1, flush the output queue; if 2, flush both the input and output queues. Special control characters The special control characters (used to interrupt processes, erase char- acters, and switch jobs) are defined by the array ccc field of the ter- mio structure. The relative positions and initial values for each func- tion are as follows: _________________________________________________________________________ Position Name Initial value _________________________________________________________________________ 0 VINTR DEL 1 VQUIT FS 2 VERASE <Ctrl>h 3 VKILL <Ctrl>u 4 VEOF/VMIN EOT 5 VEOL/VTIME NUL 6 VEOL2 EOL 7 VSWTCH NUL Input modes The ciflag field specifies the treatment of input. The initial value of this field is 0 (all bits clear). The following input mode flags may be set: IGNBRK 0000001 Ignores break condition BRKINT 0000002 Signals interrupt on break IGNPAR 0000004 Ignores characters with parity errors PARMRK 0000010 Marks parity errors INPCK 0000020 Enables input parity check ISTRIP 0000040 Strips high bit from character INLCR 0000100 Maps NL to CR on input IGNCR 0000200 Ignores CR ICRNL 0000400 Maps CR to NL on input IUCLC 0001000 Maps uppercase to lowercase on input IXON 0002000 Enables start/stop output control IXANY 0004000 Enables any character to restart output IXOFF 0010000 Enables start/stop input control IGNBRK Ignore the break condition (a character framing error with data all zeros). It is not put on the input queue and is therefore not read by any process. BRKINT Cause the break condition to generate an interrupt signal and flush both the input and output queues. IGNPAR Ignore characters with other framing and parity errors. PARMRK If set, read a character with a framing or parity error which is not ignored as the 3-character sequence: 0377, 0, X, where X is the data of the character received in error. To avoid ambiguity in this case, if ISTRIP is not set, read a valid character of 0377 as 0377, 0377. If not set, read a framing or parity error which is not ignored as the character NUL (0). INPCK If set, input parity checking is enabled. If not set, disable input parity checking. This allows output parity generation without input parity errors. ISTRIP If set, strip valid input characters to 7 bits. If not set, process all 8 bits. INLCR Translate a received NL character into a CR character. IGNCR Ignore (do not read) a received CR character. ICRNL Translate a received CR character into a NL character. IUCLC Translate a received uppercase alphabetic character into the corresponding lowercase character. IXON If set, enable start/stop output control. A received STOP character suspends output and a received START character res- tarts output. If not set, ignore (do not read) all start/stop characters. IXANY Causes any input character to restart output which has been suspended. IXOFF If set, enable start/stop input control. Transmit START char- acters when the input queue is nearly empty and STOP characters when nearly full. Output modes The coflag field specifies the treatment of output. The initial value of this field is 0 (all bits clear). The following output mode flags may be set: OPOST 0000001 Postprocesses output OLCUC 0000002 Maps lowercase to uppercase on output ONLCR 0000004 Maps NL to CR-NL on output OCRNL 0000010 Maps CR to NL on output ONOCR 0000020 No CR output at column 0 ONLRET 0000040 NL performs CR function OFILL 0000100 Uses fill characters for delay OFDEL 0000200 Fills is DEL, else NUL NLDLY 0000400 Selects newline delays: NL0 0 NL1 0000400 CRDLY 0003000 Selects carriage return delays: CR0 0 CR1 0001000 CR2 0002000 CR3 0003000 TABDLY 0014000 Selects horizontal tab delays: TAB0 0 TAB1 0004000 TAB2 0010000 TAB3 0014000 Expands tabs to spaces BSDLY 0020000 Selects backspace delays: BS0 0 BS1 0020000 VTDLY 0040000 Selects vertical tab delays: VT0 0 VT1 0040000 FFDLY 0100000 Selects form feed delays: FF0 0 FF1 0100000 OPOST If set, output characters are post-processed as indicated by the remaining flags. If not set, characters are transmitted without change. OLCUC Transmit a lowercase alphabetic character as the corresponding uppercase character. This function is often used in conjunction with IUCLC. ONLCR Transmit the NL character as the CR NL character pair. OCRNL Transmit the CR character as the NL character. ONOCR Do not transmit the CR character when it is in column 0 (first position). ONLRET If set, use the NL character to perform the carriage return function; the column pointer is set to 0, and the delays speci- fied for CR will be used. If not set, use the NL character to perform the linefeed func- tion; the column pointer will remain unchanged. Also set the column pointer to 0 if the CR character is actually transmit- ted. The delay bits specify how long transmission stops to allow for mechani- cal or other movement when certain characters are sent to the terminal. No delay is implemented if none of the bits has been set. Note that actual delays depend on line speed and system load. The following delay modes are defined: OFILL Transmit fill characters to implement a delay instead of a real timed delay. This is useful for high baud rate terminals which need only a minimal delay. OFDEL If set, DEL is the fill character; if not set, it is NUL. NLDLY Use to turn off the newline delay bits. NL1 Select a newline delay of about 0.10 seconds. If ONLRET is set, use carriage return delays instead of newline delays. CRDLY Use to turn off the carriage return delay bits. CR1 Select a carriage return delay dependent on the current column position. If OFILL is set, transmit 2 fill characters. CR2 Select a carriage return delay of about 0.10 seconds. If OFILL is set, transmit 4 fill characters. CR3 Select a carriage return delay of about 0.15 seconds. TABDLY Use to turn off the horizontal tab delay bits. TAB1 Select a horizontal tab delay which is dependent on the current column position. If OFILL is set, 2 fill characters will be transmitted for any delay. TAB2 Select a horizontal tab delay of about 0.10 seconds. If OFILL is set, 2 fill characters will be transmitted for any delay. TAB3 Specify that tabs are to be expanded into spaces. BSDLY Use to turn off the backspace delay bits. BS1 Select a backspace delay of about 0.05 seconds. If OFILL is set, 1 fill character will be transmitted. VTDLY Use to turn off the vertical tab delay bits. VT1 Select a vertical tab delay of about 2 seconds. FFDLY Use to turn off the form feed delay bits. FF1 Select a form feed delay of about 2 seconds. Hardware control modes The ccflag field describes the hardware control of the terminal. The initial value of this field is B9600, CS8, CREAD, HUPCL. The following hardware control modes may be set: 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 EXTA 0000016 External A B38400 0000017 38400 baud EXTB 0000017 External B CSIZE 0000060 Character size: CS5 0 5 bits CS6 0000020 6 bits CS7 0000040 7 bits CS8 0000060 8 bits CSTOPB 0000100 Sends two stop bits if set, else one CREAD 0000200 Enables receiver PARENB 0000400 Parity enable PARODD 0001000 Odd parity if set, else even HUPCL 0002000 Hangs up on last close CLOCAL 0004000 Local line if set, else dial-up LOBLK 0010000 Block layer output CTSFLOW 0020000 Enables CTS handshaking on a serial line RTSFLOW 0040000 Enables RTS handshaking on a serial line CRTSFL 0100000 Enables bidirectional hardware flow control - included for backward compatibility ORTSFL 0100000 Enables unidirectional or bidirectional hardware flow control depending on the settings of CTSFLOW and RTSFLOW CBAUD Use to turn off the baud rate bits. B0 Zero baud rate; used to hang up a connection. If B0 is speci- fied, Data Terminal Ready (DTR) will not be asserted. Without DTR, the line is disconnected if it is connected through a modem. For any particular hardware, impossible speed changes are ignored. B50 B75 B100 B134 B150 B200 B300 B600 B1200 B1800 B2400 B4800 B9600 B19200 EXTA B38400 EXTB Use to specify the baud rate. CSIZE Use to turn off the character size bits. CS5 CS6 CS7 CS8 Use to specify the character size in bits for both transmission and reception. This size does not include the parity bit, if any. CSTOPB If set, use 2 stop bits; if not set, use 1 stop bit. For exam- ple, at 110 baud, 2 stops bits are required. CREAD If set, enable the receiver; if not set, the receiver is dis- abled and no characters will be received. PARENB Enable parity generation and detection, and add a parity bit to each character. PARODD If set, select odd parity if PARENB is also set; if not set, select even parity if PARENB is also set. HUPCL Disconnect the line when the last process with the line open either closes it or terminates; that is, Data Terminal Ready (DTR) will not be asserted. CLOCAL Assume the line to be a local, direct connection with no modem control. Data Terminal Ready (DTR) and Request To Send (RTS) are asserted, but incoming modem signals are ignored. If CLOCAL is not set, modem control is assumed. This means that DTR and RTS are asserted. Also, Carrier Detect (CD) must be asserted before communications can proceed. LOBLK If set, block the output of a shell layer when it is not the current layer; if not set, multiplex the output generated by the shell layer onto the current layer. CTSFLOW Enable CTS handshaking. RTSFLOW Enable RTS handshaking. CTSFLOW and RTSFLOW correspond to the stty(C) settings ctsflow and rtsflow. The RS-232 serial interface provides the RTS and CTS signal lines to allow handshaking between Data Terminal Equipment (DTE; devices such as terminals, printers, and computers) and Data Circuit terminating Equip- ment (sometimes referred to as Data Communications Equipment or DCE; almost always a modem). (There are exceptions to these definitions; for example, DCE serial ports and DTE modems exist.) Communication using bidirectional flow control in hardware is more efficient and reliable than using software flow control (IXON/IXOFF). There is also no problem with sending binary data over a link which uses RTS/CTS based handshak- ing. Unidirectional flow control works in the following manner: + The DTE asserts the RTS (Request To Send) line when it is ready to send data to the DCE. + The DTE drops RTS when there is no more data in its output buffer. + The DCE asserts the CTS (Clear To Send) line when it is ready to receive data from the DTE. + The DCE drops CTS if it needs to stop the DTE sending data. In this way, the DCE controls the flow of data from the DTE but not the other way around. The implicit assumption is that the DTE is faster than the DCE. With the high-speed modems now available, bidirectional flow control is used in preference; this avoids the possibility of characters being lost due to the modem causing the input buffer on the serial port to overflow. Using bidirectional flow control, the DTE asserts RTS when it is ready to receive data (reversing its role from the unidirectional case), and drops RTS when its input buffer becomes too full. As for the unidirectional case, the DCE asserts CTS when it is ready to receive data, and drops CTS when its input buffer is too full. In each case, the sending equipment stops transmitting whenever it sees the incoming control line drop. CRTSFL Changes the meaning of RTS (with RTSFLOW and CTSFLOW not set) to allow bidirectional flow control. CRTSFL is included for backward compatibility; ORTSFL should be used in preference. ORTSFL Old RTSFLOW; depending on the settings of RTSFLOW and CTSFLOW, ORTSFL determines the type of flow control. The hardware flow control modes which may be obtained by combining the flags ORTSFL, RTSFLOW, and CTSFLOW are shown in the following table: _________________________________________________________________________ Flag combination Flow control mode _________________________________________________________________________ ORTSFL | RTSFLOW | CTSFLOW Enable unidirectional flow control (ORTSFL | RTSFLOW) & ~CTSFLOW Assert RTS when ready to send (ORTSFL | CTSFLOW) & ~RTSFLOW No effect ORTSFL & ~(RTSFLOW | CTSFLOW) Enable bidirectional flow control (RTSFLOW | CTSFLOW) & ~ORTSFL Enable bidirectional flow control RTSFLOW & ~(CTSFLOW | ORTSFL) No effect CTSFLOW & ~(RTSFLOW | ORTSFL) Stop transmission when CTS drops ~(ORTSFL | RTSFLOW | CTSFLOW) Disable hardware flow control Older serial devices requiring unidirectional flow control should use the stty settings ortsfl rtsflow ctsflow. Bidirectional flow control is achieved using the stty settings: ortsfl -rtsflow -ctsflow, or -ortsfl rtsflow ctsflow. These settings are the ones most likely to work with high-speed modems and other modern serial devices. (The settings supercede the older stty settings crtsfl -rtsflow -ctsflow.) In both the unidirectional and bidirectional cases, you should also specify -clocal -ixon -ixoff to stty. These settings specify that the line has modem control, and that software flow control is disabled. Software flow control (IXON and IXOFF) should be disabled when using hardware flow control (ORTSFL, RTSFLOW and CTSFLOW). The reverse also applies; disable hardware flow control when using software flow control. Set all flags explicitly on or off when selecting the flow control mode using stty. For example, to set bidirectional flow control, you would enter: stty ortsfl -ctsflow -rtsflow -ixon -ixoff. The use of the settings CTSFLOW, RTFLOW, CRTSFL, or ORTSFL is strictly hardware dependent, and should only be used between devices capable of supporting RTS/CTS signaling. The RS-232 line must also be wired correctly for RTS/CTS handshaking. The EIA 232D standard has the following pin connections for linking DTE to DCE: _________________________________________________________________________ DTE DCE _________________________________________________________________________ 1 to 1 Shield 2 to 2 Transmit Data TXD 3 to 3 Receive Data RXD 4 to 4 Request to Send RTS 5 to 5 Clear to Send CTS 6 to 6 Data Set Ready DSR 7 to 7 Signal earth return 8 to 8 Carrier Detect CD 20 to 20 Data Terminal Ready DTR 22 to 22 Ring Indicator RI, sometimes used by modems For direct connection linking DTE to DTE back-to-back, the pin connec- tions (null-modem) are: _________________________________________________________________________ DTE DTE _________________________________________________________________________ 1 to 1 2 to 3 3 to 2 4 to 5 5 to 4 6 and 8 to 20 7 to 7 20 to 6 and 8 Line discipline modes The line discipline used by the serial driver is chosen by the setting of the cline field. The basic line discipline used by standard terminal drivers is line discipline 0 (zero). The clflag field of the argument structure is used by the line discip- line to control terminal functions. The initial value of this field is 0 (all bits clear). Line discipline 0 provides the following modes: ISIG 0000001 Enable signals ICANON 0000002 Canonical input (erase and kill processing) XCASE 0000004 Canonical upper/lower presentation ECHO 0000010 Enables echo ECHOE 0000020 Echoes erase character as BS-SP-BS ECHOK 0000040 Echoes NL after kill character ECHONL 0000100 Echoes NL NOFLSH 0000200 Disables flush after interrupt or quit XCLUDE 0100000 Exclusive use of the line ISIG If set, check each input character against the special control characters INTR, SWTCH and QUIT. If the character matches one of these, perform the function associated with that character (generate the signal associated with that character). If not set, perform no checking. Special input functions are only available if ISIG is set. These functions may be disabled individually by changing the value of the control character to an unlikely or impossible value (for example, 0377). ICANON If set, select canonical processing (``cooked'' mode). This enables the erase and kill edit functions, and the assembly of input characters into lines delimited by NL, EOF and EOL. If not set, satisfy read requests directly from the input queue (``raw'' mode). A read will not be satisfied until at least VMIN characters have been received or the timeout value VTIME has expired and at least one character has been input. This allows fast bursts of input to be read efficiently while still allowing single character input. (See the discussion in ``VMIN and VTIME settings''.) XCASE If set with ICANON, accept an uppercase letter 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. ECHO Echo characters when they are received. With ICANON set, the echo modes ECHOE, ECHOK, and ECHONL are possible: ECHOE If ECHO is also set, echo the erase character as the ASCII sequence BS SP BS. This clears the previous character on a CRT screen. If set and ECHO is not set, echo the erase character as the ASCII sequence SP BS. ECHOK Echo the NL character after the kill character to emphasize that the line will be deleted. Note that an escape character preceding the erase or kill character removes any special func- tion. ECHONL Echo the NL character even if ECHO is not set. This is useful for terminals set to local echo (so-called half duplex). Unless escaped, the EOF character is not echoed. Because EOT is the default EOF character, this prevents terminals that respond to EOT from hanging up. NOFLSH Disable the normal flush of the input and output queues associ- ated with the quit and interrupt characters. XCLUDE Causes any subsequent attempt to open the tty device using open(S) to fail for all users except the super user. The call returns EBUSY in errno if it fails. XCLUDE is useful for programs which must have exclusive use of a communications line. It is not intended for the line to the program's controlling terminal. Clear XCLUDE before the setting program terminates, otherwise subsequent attempts to open the device will fail. VMIN and VTIME settings VMIN and VTIME set the timing characteristics for reading characters in ``raw'' mode: VMIN The minimum number of characters that should be received when the read is satisfied (that is, the characters are returned to the user). VTIME A timer of 0.10 second granularity used to time-out ``bursty'' and short-term data transmissions. The value of VTIME is measured in tenths of seconds. The four possible values for VMIN and VTIME and their interactions are: VMIN > 0, VTIME > 0 In this case, VTIME serves as an inter-character timer activated after the first character is received, and reset upon receipt of each character. VMIN and VTIME interact as follows: As soon as one character is received the inter- character timer is started. If VMIN characters are received before the inter- character timer expires the read is satisfied. If the timer expires before VMIN characters are received the characters received to that point are returned to the user. A read(S) operation will sleep until the VMIN and VTIME mechanisms are activated by the receipt of the first character; thus, at least one character must be returned. VMIN > 0, VTIME = 0 In this case, because VTIME = , the timer plays no role and only VMIN is significant. A read(S) opera- tion is not satisfied until VMIN characters are received. VMIN = 0, VTIME > 0 In this case, because VMIN = 0, VTIME no longer serves as an inter-character timer, but now serves as a read timer that is activated as soon as the read(S) operation is processed. A read(S) operation is satisfied as soon as a single character is received or the timer expires, in which case, the read(S) operation will not return any characters. VMIN = 0, VTIME = 0 In this case, return is immediate. If characters are present, they will be returned to the user. The VMIN and VTIME values are stored in the position for the EOF and EOL characters respectively. VMIN and VTIME are interpreted as EOF and EOL if ICANON is set. Default VMIN and VTIME values are stored in the /usr/include/sys/termio.h file. To change these values, unset ICANON and use stty(C) to change the VMIN and VTIME values as represented by EOF and EOL. Files /dev/tty /dev/tty* /dev/console See also fork(S), getty(M), ioctl(S), mapchan(F), mapchan(M), read(S), setgprp(S), shl(C), signal(S), stty(C), termios(M), tty(M) Standards conformance termio is conformant with: AT&T SVID Issue 2; and X/Open Portability Guide, Issue 3, 1989.