FreeBSD Manual Pages
TERMIO(4) Kernel Interfaces Manual 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 sec- tion discusses the common features of this interface. Opening a Terminal Device File When a terminal file is opened, the process normally waits until a con- nection 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 sig- nal-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 ques- tion, 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 open- ing 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 termi- nal (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 back- ground process to write to its controlling terminal will typically send that process' process group a SIGTTOU signal. If the process is ignor- ing SIGTTOU, has SIGTTOU blocked, or is in the middle of process cre- ation using vfork(), the process will be allowed to write to the termi- nal and the SIGTTOU signal will not be sent. If the process is or- phaned, 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 parame- ters 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 out- put is occurring, and are only lost when the system's character input buffers become completely full, which is rare, or when the user has ac- cumulated 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 se- lected, 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 ter- minal 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 ter- minal, 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-speci- fied 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 cur- rent 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. Nei- ther 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 au- tomatically 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 assem- bled into lines, and erase and kill processing does not occur. The MIN and TIME values are used to determine how to process the characters re- ceived. 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 be- tween 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 re- set upon receipt of each character), the read is satisfied. If the timer expires before MIN characters are received, the characters re- ceived 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 ac- tivated 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 charac- ters 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 intercharac- ter 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 charac- ter - 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: o In the following explanations one may notice that the interac- tions 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. o 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 en- abled. 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 re- sumed. 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 as- sociated 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 lo- cation; see sigvec(2). QUIT (CTRL-| or ASCII FS) generates a SIGQUIT signal, which is sent to all processes in the distinguished process group as- sociated 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 oc- curred 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 out- put. It is useful with CRT terminals to prevent output from disappearing before it can be read. While output is sus- pended, 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 sus- pended, 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 char- acters mentioned above. This allows characters to be input that would otherwise get interpreted by the system (for exam- ple, 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 \ charac- ter, 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 TIOC- SSOFTCAR 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 as- serted. 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 dis- tinguished 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 er- rno 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 provid- ing the termios interface are specified by the termios structure, de- fined 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 rel- ative 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-char- acter 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 gen- eration 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 char- acter. 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 trans- lated 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 in- put 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 al- ready 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 char- acter. 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 charac- ter 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 mechan- ical or other movement when certain characters are sent to the termi- nal. 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 posi- tion, 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 posi- tion. 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 000001619200 baud B38400 000001738400 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 ex- ample, at 110 baud, two stop bits are required. If PARENB is set, parity generation and detection is enabled and a par- ity 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 discon- nected when the last process with the line open closes it or termi- nates. If CLOCAL is set, a connection does not depend on the state of the mo- dem 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 sus- pended until CTS is raised. Some hardware may not support this func- tion, 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 disci- pline to control terminal functions. The basic line discipline pro- vides 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 al- lowing 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 gener- ated 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 char- acter, and the STOP character, are echoed as ^X, where X is the charac- ter 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: o 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. o If ECHO and ECHOPRT are set, the first ERASE and WERASE charac- ter 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. o If ECHOKE is set, the kill character is echoed by erasing each character on the line from the screen (using the mechanism se- lected by ECHOE and ECHOPRT). o 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 func- tion. o 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). o 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 es- caped, 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 asso- ciated 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 re- printed 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 de- fined 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 rel- ative 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 con- trol 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 sup- ported 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 TI- OCM_RNG. Not all of these will necessarily be supported by any particular de- vice; 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 sup- ported 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 val- ues stored in that structure. The change is immedi- ate. TCSETSW The argument is a pointer to a termios structure. The current terminal parameters are set from the val- ues stored in that structure. The change occurs af- ter all characters queued for output have been trans- mitted. This form should be used when changing pa- rameters that will affect output. TCSETSF The argument is a pointer to a termios structure. The current terminal parameters are set from the val- ues stored in that structure. The change occurs af- ter all characters queued for output have been trans- mitted; 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 charac- ters 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 charac- ters 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 #in- clude <sys/ttold.h>. TIOCSCTTY The argument is an int. The system will attempt to assign the terminal as the caller's controlling ter- minal (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 ter- minal 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 distin- guished process group associated with the terminal. This call is allowed from a background process; how- ever, 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 re- turned. 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 cur- rent process must be super-user. Otherwise, the er- ror EPERM is returned. This ioctl() exists only for backward compatibility, use tcsetpgrp(), see tcgetp- grp(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 de- tect 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) 15 January 1990 TERMIO(4)
NAME | SYNOPSIS | DESCRIPTION | IOCTLS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=termio&sektion=4&manpath=SunOS+4.1.3>