termio(M) 19 June 1992 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. 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 FDUP's 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 handling quit and interrupt signals, as discussed below. The control terminal 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 accu- mulated 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 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, necessary 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 Ctrlh or Bksp erases the last character typed, except that it will not erase beyond the beginning of the line. By default, a Ctrlu kills (deletes) the entire input line, and optionally outputs a newline character. Both these characters operate on a keystroke basis, indepen- dent 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 (called 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 (Ctrlh) Erases the preceding character. It will not erase beyond the start of a line, as delimited by an NL, EOF, or EOL charac- ter. KILL (Ctrlu) Deletes the entire line, as delimited by a NL, EOF, or EOL character. EOF (Ctrld 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 new- line, 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 cannot be changed or escaped. EOL (ASCII NUL) Is an additional line delimiter, like NL. It is not normally used. STOP (Ctrls 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 (Ctrlq or ASCII DC1) Resumes output which has been suspended by a STOP character. While output is not suspended, START characters 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 terminal 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. Several ioctl(S) system calls apply to terminal files. The primary calls use the following structure, defined in the file <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; /* local modes */ char c_line; /* line discipline */ unsigned char c_cc[NCC]; /* control chars */ }; The special control characters are defined by the array ccc. The rela- tive positions and initial values for each function are as follows: 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 The ciflag field describes the basic terminal input control: 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 If IGNBRK is set, the break condition (a character framing error with data all zeros) is ignored, that is, not put on the input queue and therefore not read by any process. Otherwise, if BRKINT is set, the break condition will generate an interrupt signal and flush both the input and output queues. If IGNPAR is set, characters with other framing and parity errors are ignored. If PARMRK is set, a character with a framing or parity error which is not ignored is read 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, a valid character of 0377 is read as 0377, 0377. If PARMRK is not set, a framing or parity error which is not ignored is read as the character NUL (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 charac- ter. 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 uppercase alphabetic character is translated into the corresponding lowercase 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. All start/stop characters are ignored and not read. If IXANY is set, any input character will restart output which has been suspended. If IXOFF is set, the system will transmit START characters when the input queue is nearly empty and STOP characters when nearly full. The initial input control value is all bits clear. The coflag field specifies the system treatment of output: 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 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 lowercase alphabetic character is transmitted as the corresponding uppercase character. This function is often used in con- junction 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 charac- ter. 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 per- form the carriage return function and the column pointer is set to 0 and the delays specified for CR will be used. Otherwise, the NL character is assumed to perform the linefeed 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 mechani- cal 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 which 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. Newline delay lasts about 0.10 seconds. If ONLRET is set, the carriage return delays are used instead of the newline delays. If OFILL is set, 2 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 2 fill characters, and type 2 transmits 4 fill characters. Horizontal tab delay type 1 is dependent on the current column position. Type 2 is about 0.10 seconds. Type 3 specifies that tabs are to be expanded into spaces. If OFILL is set, 2 fill characters will be transmitted for any delay. Backspace delay lasts about 0.05 seconds. If OFILL is set, 1 fill char- acter will be transmitted. The actual delays depend on line speed and system load. The initial output control value is all bits clear. The ccflag 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 EXTA 0000016 External A 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, else one CREAD 0000200 Enables receiver PARENB 0000400 Parity enable PARODD 0001000 Odd parity, else even HUPCL 0002000 Hangs up on last close CLOCAL 0004000 Local line, else dial-up LOBLK 0010000 Block layer output CTSFLOW 0020000 Enables CTS protocol for a modem line RTSFLOW 0040000 Enables RTS signaling for a modem line CRTSFL 0100000 Enables bidirectional hardware flow control If CTSFLOW and RTSFLOW are set, IXON and IXANY should not be set (or vice versa) so that these two types of flow control do not interfere with each other. CTSFLOW and RTSFLOW are available for modem lines which support CTS/RTS signaling. RTSFLOW, CTSFLOW or -RTSFLOW, -CTSFLOW are the only permiss- able settings. (The RS-232 line must also be wired correctly for RTS/CTS handshaking.) The use of these settings is strictly hardware dependant and should only be used between devices capable of supporting CTS/RTS signalling. The RTS and CTS lines for the RS-232 (that is, serial) interface were originally intended as handshaking signals between a Data Terminal Equip- ment (DTE) device (computer, printer, etc,) and a Data Communications Equipment (DCE) device (almost always a modem). The RTS (Ready To Send) line is asserted by the DTE when it is ready to send data to the DCE. The DCE asserts the CTS (Clear To Send) line when it is ready to receive data. If the CTS line goes low, then the DTE should stop sending data until CTS goes high again. CRTSFL is a new (in Release 3.2 v4) ccflag. CRTSFL controls the flow of data along the modem line using hardware signals. The RTS and CTS lines can be used to transfer binary files in raw mode if required. CRTSFL enables bidirectional hardware flow control between the computer and a modem-style device or another computer. Before setting CRTSFL check that: + The RS-232C line has the connections shown in the termio(M) section of the printed manual pages. + CTSFLOW and RTSFLOW are not set. If either CTSFLOW or RTSFLOW are set, CRTSFL is disabled. Back to back connection with a device supporting RTS/CTS flow control is possible as long as the device does not send data when its incoming CTS line is low, and asserts RTS while it has room in its buffer cache for more data. The CBAUD bits specify the baud rate. The zero baud rate, B0, is used to hang up the connection. If B0 is specified, the data-terminal-ready sig- nal will not be asserted. Without this signal, the line is disconnected if it is connected through a modem. For any particular hardware, impos- sible 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, 2 stop bits are used, otherwise 1 stop bit. For example, at 110 baud, 2 stops 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 line will be disconnected when the last process with the line open closes it or terminates: that is, the data-terminal-ready signal will not be asserted. If CLOCAL is set, the line is assumed to be a local, direct connection with no modem control. The data-terminal-ready and request-to-send sig- nals are asserted, but incoming modem signals are ignored. If CLOCAL is not set, modem control is assumed. This means the data-terminal-ready and request-to-send signals are asserted. Also, the carrier-detect signal must be returned before communications can proceed. If LOBLK is set, the output of a shell layer will be blocked when it is not the current layer. Otherwise the output generated by that layer will be multiplexed onto the current layer. The initial hardware control value after open is B9600, CS8, CREAD, HUPCL. The clflag field of the argument structure is used by the line discip- line to control terminal functions. The basic line discipline (0) pro- vides the following: 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 If ISIG is set, each input character is checked against the special con- trol characters INTR, SWTCH and QUIT. If an input character matches one of these control characters, the function associated with that character is performed (that is, the signal associated with that character is gen- erated). If ISIG is not set, no checking is done. Thus, these special input functions are possible only 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). If ICANON is set, canonical processing is enabled. This enables the erase and kill edit functions, and the assembly of input characters into lines delimited by NL, EOF and EOL. If ICANON is not set, read requests are satisfied directly from the input queue. A read will not be satis- fied 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 of VMIN and VTIME below.) 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, set ICANON to off and use stty(C) to change the VMIN and VTIME values as represented by EOF and EOL. The VTIME value represents tenths of seconds. If XCASE and ICANON are set, an uppercase 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 when they are received. When ICANON is set, the following echo functions are possible. If ECHO and ECHOE are set, the erase character is echoed as ASCII BS SP BS, which will clear the last character from a CRT screen. If ECHOE is set and ECHO is not set, the erase character is echoed as ASCII SP BS. If ECHOK is set, the NL character will be echoed 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 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). 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. If NOFLSH is set, the normal flush of the input and output queues associ- ated with the quit and interrupt characters will not be done. If XCLUDE is set, any subsequent attempt to open the tty device using open(S) will fail for all users except the super-user. If the call fails, it returns EBUSY in errno. 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. XCLUDE must be cleared before the setting program terminates, otherwise subsequent attempts to open the device will fail. VMIN represents the minimum number of characters that should be received when the read is satisfied (that is, the characters are returned to the user). VTIME is a timer of 0.10 second granularity used to time-out bursty and short-term data transmissions. 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) operation 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) opera- tion 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 initial line-discipline control value is all bits clear. The primary ioctl(S) system calls have the form: ioctl (fildes, command, arg) struct termio *arg; The commands using this form are: TCGETA Gets the parameters associated with the terminal and stores them in the termio structure referenced by arg. TCSETA Sets the parameters associated with the terminal from the structure referenced by arg. The change is immediate. TCSETAW Waits for the output to drain before setting the new parame- ters. This form should be used when changing parameters that will affect output. TCSETAF Waits for the output to drain, then flushes the input queue and sets the new parameters. Additional ioctl(S) calls have the form: ioctl (fildes, command, arg) int arg The commands using this form are: TCSBRK Waits for the output to drain. If arg is 0, then sends a break (zero bits for 0.25 seconds). TCXONC Starts/stops control. If arg is 0, suspends output; if 1, restarts suspended output; if 2, block; if 3, unblock. TCFLSH If arg is 0, flushes the input queue; if 1, flushes the out- put queue; if 2, flushes both the input and output queues. 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.