termio - general terminal interface
#include <termio.h> ioctl(int fildes, int request, struct termio *arg);
ioctl(int fildes, int request, int arg);
#include <termios.h> ioctl(int fildes, int request, struct termios *arg);
This release supports a general interface for asynchronous communications ports that is hardware-independent. The user interface to this functionality is using function calls (the preferred interface) described in termios(3C) or ioctl commands described in this section. This section also discusses the common features of the terminal subsystem which are relevant with both user interfaces.
When a terminal file is opened, it normally causes the process to wait until a connection is established. In practice, user programs seldom open terminal files; they are opened by the system and become a user's standard input, output, and error files. The first terminal file opened by the session leader that is not already associated with a session becomes the controlling terminal for that session. The controlling terminal plays a special role in handling quit and interrupt signals, as discussed below. The controlling terminal is inherited by a child process during a fork(2). A process can break this association by changing its session using setsid() (see setsid(2)).
A terminal associated with one of these files ordinarily operates in full-duplex mode. Characters may be typed at any time, even while output is occurring, and are only lost when the character input buffers of the system become completely full, which is rare. For example, the number of characters in the line discipline buffer may exceed {MAX_CANON} and IMAXBEL (see below) is not set, or the user may accumulate { MAX_INPUT} number of input characters that have not yet been read by some program. When the input limit is reached, all the characters saved in the buffer up to that point are thrown away without notice.
A control terminal will distinguish one of the process groups in the session associated with it to be the foreground process group. All other process groups in the session are designated as background process groups. This foreground process group plays a special role in handling signal-generating input characters, as discussed below. By default, when a controlling terminal is allocated, the controlling process's process group is assigned as foreground process group.
Background process groups in the controlling process's session are subject to a job control line discipline when they attempt to access their controlling terminal. Process groups can be sent signals that will cause them to stop, unless they have made other arrangements. An exception is made for members of orphaned process groups.
An orphaned process group is one where the process group (see getpgid(2)) has no members with a parent in a different process group but sharing the same controlling terminal. When a member of an orphaned process group attempts to access its controlling terminal, EIO is returned because there would be no way to restart the process if it were stopped on one of these signals.
If a member of a background process group attempts to read its controlling terminal, its process group will be sent a SIGTTIN signal, which will normally cause the members of that process group to stop. If, however, the process is ignoring or holding SIGTTIN, or is a member of an orphaned process group, the read will fail with errno set to EIO, and no signal is sent.
If a member of a background process group attempts to write its controlling terminal and the TOSTOP bit is set in the c_lflag field, its process group is sent a SIGTTOU signal, which will normally cause the members of that process group to stop. If, however, the process is ignoring or holding SIGTTOU, the write will succeed. If the process is not ignoring or holding SIGTTOU and is a member of an orphaned process group, the write will fail with errno set to EIO, and no signal will be sent.
If TOSTOP is set and a member of a background process group attempts to ioctl its controlling terminal, and that ioctl will modify terminal parameters (for example, TCSETA, TCSETAW, TCSETAF, or TIOCSPGRP), its process group will be sent a SIGTTOU signal, which will normally cause the members of that process group to stop. If, however, the process is ignoring or holding SIGTTOU, the ioctl will succeed. If the process is not ignoring or holding SIGTTOU and is a member of an orphaned process group, the write will fail with errno set to EIO, and no signal will be sent.
Normally, terminal input is processed in units of lines. A line is delimited 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 block until an entire line has been typed. Also, no matter how many characters are requested in the read call, at most one line will be returned. It is not necessary, however, to read a whole line at once; any number of characters may be requested in a read, even one, without losing information.
During input, erase and kill processing is normally done. The ERASE character (by default, the character DEL) erases the last character typed. The WERASE character (the character Control-w) erases the last "word" typed in the current input line (but not any preceding spaces or tabs). A "word" is defined as a sequence of non-blank characters, with tabs counted as blanks. Neither ERASE nor WERASE will erase beyond the beginning of the line. The KILL character (by default, the character NAK) kills (deletes) the entire input line, and optionally outputs a newline character. All these characters operate on a key stroke basis, independent of any backspacing or tabbing that may have been done. The REPRINT character (the character Control-r) prints a newline followed by all characters that have not been read. Reprinting also occurs automatically if characters that would normally be erased from the screen are fouled by program output. The characters are reprinted as if they were being echoed; consequencely, 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.
In non-canonical mode input processing, input characters are not assembled into lines, and erase and kill processing does not occur. The MIN and TIME values are used to determine how to process the characters received.
MIN represents the minimum number of characters that should be received when the read is satisfied (that is, 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
Case B: MIN > 0, TIME = 0
Case C: MIN = 0, TIME > 0
Case D: MIN = 0, TIME = 0
Some points to note about MIN and TIME :
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; in case B, the timer 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, whereas in case D, it is not.
Another important note is that MIN is always just a minimum. It does not denote a record length. For example, if a program does a read of 20 bytes, MIN is 10, and 25 characters are present, then 20 characters will be returned to the user.
When one or more characters are written, they are transmitted to the terminal as soon as previously written characters have finished typing. Input characters are echoed as they are typed if echoing has been enabled. If a process produces characters more rapidly than they can be typed, it will be suspended when its output queue exceeds some limit. When the queue is drained down to some threshold, the program is resumed.
Certain characters have special functions on input. These functions and their default character values are summarized as follows:
INTR
QUIT
ERASE
WERASE
KILL
REPRINT
EOF
NL
EOL
EOL2
SWTCH
SUSP
DSUSP
STOP
START
DISCARD
LNEXT
When a modem disconnect is detected, a SIGHUP signal is sent to the terminal's controlling process. Unless other arrangements have been made, these signals cause the process to terminate. If SIGHUP is ignored or caught, any subsequent read returns with an end-of-file indication until the terminal is closed.
If the controlling process is not in the foreground process group of the terminal, a SIGTSTP is sent to the terminal's foreground process group. Unless other arrangements have been made, these signals cause the processes to stop.
Processes in background process groups that attempt to access the controlling terminal after modem disconnect while the terminal is still allocated to the session will receive appropriate SIGTTOU and SIGTTIN signals. Unless other arrangements have been made, this signal causes the processes to stop.
The controlling terminal will remain in this state until it is reinitialized with a successful open by the controlling process, or deallocated by the controlling process.
The parameters that control the behavior of devices and modules providing the termios interface are specified by the termios structure defined by termios.h. Several ioctl(2) system calls that fetch or change these parameters use this structure that contains the following members:
tcflag_t c_iflag; /* input modes */ tcflag_t c_oflag; /* output modes */ tcflag_t c_cflag; /* control modes */ tcflag_t c_lflag; /* local modes */ cc_t c_cc[NCCS]; /* control chars */
The special control characters are defined by the array c_cc. The symbolic name NCCS is the size of the Control-character array and is also defined by <termios.h>. The relative positions, subscript names, and typical default values for each function are as follows:
|
The c_iflag field describes the basic terminal input control:
IGNBRK
BRKINT
IGNPAR
PARMRK
INPCK
ISTRIP
INLCR
IGNCR
ICRNL
IUCLC
IXON
IXANY
IXOFF
IMAXBEL
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. If IGNBRK is not set and BRKINT is set, the break condition shall flush the input and output queues and if the terminal is the controlling terminal of a foreground process group, the break condition generates a single SIGINT signal to that foreground process group. If neither IGNBRK nor BRKINT is set, a break condition is read as a single '\0' (ASCII NULL) character, or if PARMRK is set, as '\377', '\0', c, where '\377' is a single character with value 377 octal (0xff hex, 255 decimal), '\0' is a single character with value 0, and c is the errored character received.
If IGNPAR is set, a byte with framing or parity errors (other than break) is ignored.
If PARMRK is set, and IGNPAR is not set, a byte with a framing or parity error (other than break) is given to the application as the three-character sequence: '\377', '\0', c, where '\377' is a single character with value 377 octal (0xff hex, 255 decimal), '\0' is a single character with value 0, and c is the errored character received. To avoid ambiguity in this case, if ISTRIP is not set, a valid character of '\377' is given to the application as `\377.' If neither IGNPAR nor PARMRK is set, a framing or parity error (other than break) is given to the application as a single '\0' (ASCII NULL) character.
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. Note that whether input parity checking is enabled or disabled is independent of whether parity detection is enabled or disabled. If parity detection is enabled but input parity checking is disabled, the hardware to which the terminal is connected will recognize the parity bit, but the terminal special file will not check whether this is set correctly or not.
If ISTRIP is set, valid input characters are first stripped to seven bits, otherwise all eight bits are processed.
If INLCR is set, a received NL character is translated into a CR character. If IGNCR is set, a received CR character is ignored (not read). Otherwise, if ICRNL is set, a received CR character is translated into a NL character.
If IUCLC is set, a received upper case, alphabetic character is translated into the corresponding lower case character.
If IXON is set, start/stop output control is enabled. A received STOP character suspends output and a received START character restarts output. The STOP and START characters will not be read, but will merely perform flow control functions. If IXANY is set, any input character restarts output that has been suspended.
If IXOFF is set, the system transmits a STOP character when the input queue is nearly full, and a START character when enough input has been read so 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 is not stored, but any input already present in the input stream is not 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 c_oflag field specifies the system treatment of output:
OPOST
OLCUC
ONLCR
OCRNL
ONOCR
ONLRET
OFILL
OFDEL
NLDLY
CRDLY
TABDLY
TAB0
TAB1
TAB2
TAB3
XTABS
BSDLY
VTDLY
FFDLY
If OPOST is set, output characters are post-processed as indicated by the remaining flags; otherwise, characters are transmitted without change.
If OLCUC is set, a lower case alphabetic character is transmitted as the corresponding upper case character. This function is often used in conjunction with IUCLC.
If ONLCR is set, the NL character is transmitted as the CR-NL character pair. If OCRNL is set, the CR character is transmitted as the NL character. If ONOCR is set, no CR character is transmitted when at column 0 (first position). If ONRET is set, the NL character is assumed to do the carriage-return function; the column pointer is set to 0 and the delays specified for CR are used. Otherwise, the NL character is assumed to do just the line-feed function; the column pointer remains unchanged. The column pointer is also set to 0 if the CR character is actually transmitted.
The delay bits specify how long transmission stops to allow for mechanical or other movement when certain characters are sent to the terminal. In all cases, a value of 0 indicates no delay. If OFILL is set, fill characters are 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 it is NULL.
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, two fill characters are transmitted.
Carriage-return delay type 1 is dependent on the current column position, type 2 is about 0.10 seconds, and type 3 is about 0.15 seconds. If OFILL is set, delay type 1 transmits two fill characters, and type 2 transmits four 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, two fill characters are transmitted for any delay.
Backspace delay lasts about 0.05 seconds. If OFILL is set, one fill character is transmitted.
The actual delays depend on line speed and system load.
The c_cflag field describes the hardware control of the terminal:
CBAUD
B0
B50
B75
B110
B134
B150
B200
B300
B600
B1200
B1800
B2400
B4800
B9600
B19200
EXTA
B38400
EXTB
B57600
B76800
B115200
B153600
B230400
B307200
B460800
CSIZE
CS5
CS6
CS7
CS8
CSTOPB
CREAD
PARENB
PARODD
HUPCL
CLOCAL
CIBAUD
PAREXT
CRTSXOFF
CRTSCTS
CBAUDEXT
CIBAUDEXT
The CBAUD bits together with the CBAUDEXT bit specify the output baud rate. To retrieve the output speed from the termios structure pointed to by termios_p see the following code segment.
speed_t ospeed; if (termios_p->c_cflag & CBAUDEXT) ospeed = (termios_p->c_cflag & CBAUD) + CBAUD + 1; else ospeed = termios_p->c_cflag & CBAUD;
To store the output speed in the termios structure pointed to by termios_p see the following code segment.
speed_t ospeed; if (ospeed > CBAUD) { termios_p->c_cflag |= CBAUDEXT; ospeed -= (CBAUD + 1); } else termios_p->c_cflag &= ~CBAUDEXT; termios_p->c_cflag = (termios_p->c_cflag & ~CBAUD) | (ospeed & CBAUD);
The zero baud rate, B0, is used to hang up the connection. If B0 is specified, the data-terminal-ready signal is not asserted. Normally, this disconnects the line.
If the CIBAUDEXT or CIBAUD bits are not zero, they specify the input baud rate, with the CBAUDEXT and CBAUD bits specifying the output baud rate; otherwise, the output and input baud rates are both specified by the CBAUDEXT and 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. To retrieve the input speed in the termios structure pointed to by termios_p see the following code segment.
speed_t ispeed; if (termios_p->c_cflag & CIBAUDEXT) ispeed = ((termios_p->c_cflag & CIBAUD) >> IBSHIFT) + (CIBAUD >> IBSHIFT) + 1; else ispeed = (termios_p->c_cflag & CIBAUD) >> IBSHIFT;
To store the input speed in the termios structure pointed to by termios_p see the following code segment.
speed_t ispeed; if (ispeed == 0) { ispeed = termios_p->c_cflag & CBAUD; if (termios_p->c_cflag & CBAUDEXT) ispeed += (CBAUD + 1); } if ((ispeed << IBSHIFT) > CIBAUD) { termios_p->c_cflag |= CIBAUDEXT; ispeed -= ((CIBAUD >> IBSHIFT) + 1); } else termios_p->c_cflag &= ~CIBAUDEXT; termios_p->c_cflag = (termios_p->c_cflag & ~CIBAUD) | ((ispeed << IBSHIFT) & CIBAUD);
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 is used. For example, at 110 baud, two 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 are received.
If HUPCL is set, the line is disconnected when the last process with the line open closes it or terminates. That is, the data-terminal-ready signal is not asserted.
If CLOCAL is set, the line is assumed to be a local, direct connection with no modem control; otherwise, modem control is assumed.
If CRTSXOFF is set, inbound hardware flow control is enabled.
If CRTSCTS is set, outbound hardware flow control is enabled.
The four possible combinations for the state of CRTSCTS and CRTSXOFF bits and their interactions are described below.
Case A:
Case B:
Case C:
Case D:
The c_lflag field of the argument structure is used by the line discipline to control terminal functions. The basic line discipline provides the following:
ISIG
ICANON
XCASE
ECHO
ECHOE
ECHOK
ECHONL
NOFLSH
TOSTOP
ECHOCTL
ECHOPRT
ECHOKE
FLUSHO
PENDIN
IEXTEN
If ISIG is set, each input character is checked against the special control characters INTR, QUIT, SWTCH, SUSP, STATUS, and DSUSP. If an input character matches one of these control characters, the function associated with that character is performed. (Note: If SWTCH is set and the character matches, the character is simply discarded. No other action is taken.) If ISIG is not set, no checking is done. Thus, these special input functions are possible only if ISIG is set.
If ICANON is set, canonical processing is enabled. This enables the erase and kill edit functions, and the assembly of input characters into lines delimited by NL-c, EOF, EOL, and EOL . If ICANON is not set, read requests are satisfied directly from the input queue. A read is not satisfied until at least MIN characters have been received or the timeout value TIME has expired between characters. This allows fast bursts of input to be read efficiently while still allowing single character input. The time value represents tenths of seconds.
If XCASE is set and ICANON is set, an upper case letter is accepted on input if preceded by a backslash (\) character, and is output preceded by a backslash (\) character. In this mode, the following escape sequences are generated on output and accepted on input:
|
For example, input A as \a, \n as \\n, and \N as \\\n.
If ECHO is set, characters are echoed as received.
When ICANON is set, the following echo functions are possible.
If ECHOCTL and IEXTEN are set, all control characters (characters with codes between 0 and 37 octal) other than ASCII TAB, ASCII NL, the START character, and the STOP character, ASCII CR, and ASCII BS are echoed as ^ X, where X is the character given by adding 100 octal to the code of the control character (so that the character with octal code 1 is echoed as ^ A), and the ASCII DEL character, with code 177 octal, is echoed as ^ ?.
If NOFLSH is set, the normal flush of the input and output queues associated with the INTR, QUIT, and SUSP characters is not done. This bit should be set when restarting system calls that read from or write to a terminal (see sigaction(2)).
If TOSTOP and IEXTEN are set, the signal SIGTTOU is sent to a process that tries to write to its controlling terminal if it is not in the foreground 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 any.
If FLUSHO and IEXTEN are set, data written to the terminal is 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 and IEXTEN are set, any input that has not yet been read is reprinted when the next character arrives as input. PENDIN is then automatically cleared.
If IEXTEN is set, the following implementation-defined functions are enabled: special characters ( WERASE, REPRINT, DISCARD, and LNEXT) and local flags ( TOSTOP, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, and PENDIN).
The MIN and TIME values were described previously, in the subsection, Non-canonical Mode Input Processing. The initial value of MIN is 1, and the initial value of TIME is 0.
The number of lines and columns on the terminal's display is specified in the winsize structure defined by sys/termios.h and includes the following members:
unsigned short ws_row; /* rows, in characters */ unsigned short ws_col; /* columns, in characters */ unsigned short ws_xpixel; /* horizontal size, in pixels */ unsigned short ws_ypixel; /* vertical size, in pixels */
The SunOS/SVR4 termio structure is used by some ioctls; it is defined by sys/termio.h and includes the following members:
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 symbolic name NCC is the size of the Control-character array and is also defined by termio.h. The relative positions, subscript names, and typical default values for each function are as follows:
|
The MIN values is stored in the VMIN element of the c_cc array; 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; the VTIME element is the same element as the VEOL element.
The calls that use the termio structure only affect the flags and control characters that can be stored in the termio structure; all other flags and control characters are unaffected.
On special files representing serial ports, modem control lines can be read. Control lines (if the underlying hardware supports it) may also be changed. Status lines are read-only. The following modem control and status lines may be supported by a device; they are defined by sys/termios.h:
TIOCM_LE
TIOCM_DTR
TIOCM_RTS
TIOCM_ST
TIOCM_SR
TIOCM_CTS
TIOCM_CAR
TIOCM_RNG
TIOCM_DSR
TIOCM_CD is a synonym for TIOCM_CAR, and TIOCM_RI is a synonym for TIOCM_RNG. Not all of these are necessarily supported by any particular device; check the manual page for the device in question.
The software carrier mode can be enabled or disabled using the TIOCSSOFTCAR ioctl. If the software carrier flag for a line is off, the line pays attention to the hardware carrier detect (DCD) signal. The tty device associated with the line cannot be opened until DCD is asserted. If the software carrier flag is on, the line behaves as if DCD is always asserted.
The software carrier flag is usually turned on for locally connected terminals or other devices, and is off for lines with modems.
To be able to issue the TIOCGSOFTCAR and TIOCSSOFTCAR ioctl calls, the tty line should be opened with O_NDELAY so that the open(2) will not wait for the carrier.
The initial termios values upon driver open is configurable. This is accomplished by setting the "ttymodes" property in the file /kernel/drv/options.conf. Since this property is assigned during system initialization, any change to the "ttymodes" property will not take effect until the next reboot. The string value assigned to this property should be in the same format as the output of the stty(1) command with the -g option.
If this property is undefined, the following termios modes are in effect. The initial input control value is BRKINT, ICRNL, IXON, IMAXBEL. The initial output control value is OPOST, ONLCR, TAB3. The initial hardware control value is B9600, CS8, CREAD. The initial line-discipline control value is ISIG, ICANON, IEXTEN, ECHO, ECHOK, ECHOE, ECHOKE, ECHOCTL.
The ioctls supported by devices and STREAMS modules providing the termios(3C) interface are listed below. Some calls may not be supported by all devices or modules. The functionality provided by these calls is also available through the preferred function call interface specified on termios.
TCGETS
TCSETS
TCSETSW
TCSETSF
TCGETA
TCSETA
TCSETAW
TCSETAF
TCSBRK
TCXONC
TCFLSH
TIOCGPGRP
TIOCSPGRP
TIOCGSID
TIOCGWINSZ
TIOCSWINSZ
TIOCMBIS
TIOCMBIC
TIOCMGET
TIOCMSET
TIOCSPPS
TIOCGPPS
TIOCGSOFTCAR
TIOCSSOFTCAR
TIOCGPPSEV
struct timeval tv; uint32_t serial;
"tv" is the system clock timestamp when the event (pulse on the DCD pin) occurred. "serial" is the ordinal of the event, which each consecutive event being assigned the next ordinal. The first event registered gets a "serial" value of 1. The TIOCGPPSEV returns the last event registered; multiple calls will persistently return the same event until a new one is registered. In addition to time stamping and saving the event, if it is of one-second period and of consistently high accuracy, the local system clock will automatically calibrate to it.
stty(1), fork(2), getpgid(2), getsid(2), ioctl(2), setsid(2), sigaction(2), signal(3C), tcsetpgrp(3C), termios(3C), signal.h(3HEAD), streamio(7I)
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |