diff options
Diffstat (limited to 'man/man3/termios.3')
| -rw-r--r-- | man/man3/termios.3 | 1235 |
1 files changed, 1235 insertions, 0 deletions
diff --git a/man/man3/termios.3 b/man/man3/termios.3 new file mode 100644 index 000000000..78731d21e --- /dev/null +++ b/man/man3/termios.3 @@ -0,0 +1,1235 @@ +'\" t +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de) +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" Copyright (c) 2006-2015, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1995-02-25 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" Modified 1995-09-02 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" moved to man3, aeb, 950919 +.\" Modified 2001-09-22 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" Modified 2001-12-17, aeb +.\" Modified 2004-10-31, aeb +.\" 2006-12-28, mtk: +.\" Added .SS headers to give some structure to this page; and a +.\" small amount of reordering. +.\" Added a section on canonical and noncanonical mode. +.\" Enhanced the discussion of "raw" mode for cfmakeraw(). +.\" Document CMSPAR. +.\" +.TH termios 3 (date) "Linux man-pages (unreleased)" +.SH NAME +termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow, +cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \- +get and set terminal attributes, line control, get and set baud rate +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <termios.h> +.B #include <unistd.h> +.P +.BI "int tcgetattr(int " fd ", struct termios *" termios_p ); +.BI "int tcsetattr(int " fd ", int " optional_actions , +.BI " const struct termios *" termios_p ); +.P +.BI "int tcsendbreak(int " fd ", int " duration ); +.BI "int tcdrain(int " fd ); +.BI "int tcflush(int " fd ", int " queue_selector ); +.BI "int tcflow(int " fd ", int " action ); +.P +.BI "void cfmakeraw(struct termios *" termios_p ); +.P +.BI "speed_t cfgetispeed(const struct termios *" termios_p ); +.BI "speed_t cfgetospeed(const struct termios *" termios_p ); +.P +.BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed ); +.BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed ); +.BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR cfsetspeed (), +.BR cfmakeraw (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.SH DESCRIPTION +The termios functions describe a general terminal interface that is +provided to control asynchronous communications ports. +.SS The termios structure +Many of the functions described here have a \fItermios_p\fP argument +that is a pointer to a \fItermios\fP structure. +This structure contains at least the following members: +.P +.in +4n +.EX +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]; /* special characters */ +.EE +.in +.P +The values that may be assigned to these fields are described below. +In the case of the first four bit-mask fields, +the definitions of some of the associated flags that may be set are +exposed only if a specific feature test macro (see +.BR feature_test_macros (7)) +is defined, as noted in brackets ("[]"). +.P +In the descriptions below, "not in POSIX" means that the +value is not specified in POSIX.1-2001, +and "XSI" means that the value is specified in POSIX.1-2001 +as part of the XSI extension. +.P +\fIc_iflag\fP flag constants: +.TP +.B IGNBRK +Ignore BREAK condition on input. +.TP +.B BRKINT +If \fBIGNBRK\fP is set, a BREAK is ignored. +If it is not set +but \fBBRKINT\fP is set, then a BREAK causes the input and output +queues to be flushed, and if the terminal is the controlling +terminal of a foreground process group, it will cause a +\fBSIGINT\fP to be sent to this foreground process group. +When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK +reads as a null byte (\[aq]\e0\[aq]), except when \fBPARMRK\fP is set, +in which case it reads as the sequence \e377 \e0 \e0. +.TP +.B IGNPAR +Ignore framing errors and parity errors. +.TP +.B PARMRK +If this bit is set, input bytes with parity or framing errors are +marked when passed to the program. +This bit is meaningful only when +\fBINPCK\fP is set and \fBIGNPAR\fP is not set. +The way erroneous bytes are marked is with two preceding bytes, +\e377 and \e0. +Thus, the program actually reads three bytes for one +erroneous byte received from the terminal. +If a valid byte has the value \e377, +and \fBISTRIP\fP (see below) is not set, +the program might confuse it with the prefix that marks a +parity error. +Therefore, a valid byte \e377 is passed to the program as two +bytes, \e377 \e377, in this case. +.IP +If neither \fBIGNPAR\fP nor \fBPARMRK\fP +is set, read a character with a parity error or framing error +as \e0. +.TP +.B INPCK +Enable input parity checking. +.TP +.B ISTRIP +Strip off eighth bit. +.TP +.B INLCR +Translate NL to CR on input. +.TP +.B IGNCR +Ignore carriage return on input. +.TP +.B ICRNL +Translate carriage return to newline on input (unless \fBIGNCR\fP is set). +.TP +.B IUCLC +(not in POSIX) Map uppercase characters to lowercase on input. +.TP +.B IXON +Enable XON/XOFF flow control on output. +.TP +.B IXANY +(XSI) Typing any character will restart stopped output. +(The default is to allow just the START character to restart output.) +.TP +.B IXOFF +Enable XON/XOFF flow control on input. +.TP +.B IMAXBEL +(not in POSIX) Ring bell when input queue is full. +Linux does not implement this bit, and acts as if it is always set. +.TP +.BR IUTF8 " (since Linux 2.6.4)" +(not in POSIX) Input is UTF8; +this allows character-erase to be correctly performed in cooked mode. +.P +.I c_oflag +flag constants: +.TP +.B OPOST +Enable implementation-defined output processing. +.TP +.B OLCUC +(not in POSIX) Map lowercase characters to uppercase on output. +.TP +.B ONLCR +(XSI) Map NL to CR-NL on output. +.TP +.B OCRNL +Map CR to NL on output. +.TP +.B ONOCR +Don't output CR at column 0. +.TP +.B ONLRET +The NL character is assumed to do the carriage-return function; +the kernel's idea of the current column is set to 0 +after both NL and CR. +.TP +.B OFILL +Send fill characters for a delay, rather than using a timed delay. +.TP +.B OFDEL +Fill character is ASCII DEL (0177). +If unset, fill character is ASCII NUL (\[aq]\e0\[aq]). +(Not implemented on Linux.) +.TP +.B NLDLY +Newline delay mask. +Values are \fBNL0\fP and \fBNL1\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B CRDLY +Carriage return delay mask. +Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B TABDLY +Horizontal tab delay mask. +Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP, +but see the +.B BUGS +section). +A value of TAB3, that is, XTABS, expands tabs to spaces +(with tab stops every eight columns). +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B BSDLY +Backspace delay mask. +Values are \fBBS0\fP or \fBBS1\fP. +(Has never been implemented.) +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.TP +.B VTDLY +Vertical tab delay mask. +Values are \fBVT0\fP or \fBVT1\fP. +.TP +.B FFDLY +Form feed delay mask. +Values are \fBFF0\fP or \fBFF1\fP. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.P +\fIc_cflag\fP flag constants: +.TP +.B CBAUD +(not in POSIX) Baud speed mask (4+1 bits). +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B CBAUDEX +(not in POSIX) Extra baud speed mask (1 bit), included in +.BR CBAUD . +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.IP +(POSIX says that the baud speed is stored in the +.I termios +structure without specifying where precisely, and provides +.BR cfgetispeed () +and +.BR cfsetispeed () +for getting at it. +Some systems use bits selected by +.B CBAUD +in +.IR c_cflag , +other systems use separate fields, for example, +.I sg_ispeed +and +.IR sg_ospeed .) +.TP +.B CSIZE +Character size mask. +Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP. +.TP +.B CSTOPB +Set two stop bits, rather than one. +.TP +.B CREAD +Enable receiver. +.TP +.B PARENB +Enable parity generation on output and parity checking for input. +.TP +.B PARODD +If set, then parity for input and output is odd; +otherwise even parity is used. +.TP +.B HUPCL +Lower modem control lines after last process closes the device (hang up). +.TP +.B CLOCAL +Ignore modem control lines. +.TP +.B LOBLK +(not in POSIX) Block output from a noncurrent shell layer. +For use by \fBshl\fP (shell layers). +(Not implemented on Linux.) +.TP +.B CIBAUD +(not in POSIX) Mask for input speeds. +The values for the +.B CIBAUD +bits are +the same as the values for the +.B CBAUD +bits, shifted left +.B IBSHIFT +bits. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +(Not implemented in glibc, supported on Linux via +.BR TCGET * +and +.BR TCSET * +ioctls; see +.BR ioctl_tty (2)) +.TP +.B CMSPAR +(not in POSIX) +Use "stick" (mark/space) parity (supported on certain serial +devices): if +.B PARODD +is set, the parity bit is always 1; if +.B PARODD +is not set, then the parity bit is always 0. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B CRTSCTS +(not in POSIX) Enable RTS/CTS (hardware) flow control. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.P +\fIc_lflag\fP flag constants: +.TP +.B ISIG +When any of the characters INTR, QUIT, SUSP, or DSUSP are received, +generate the corresponding signal. +.TP +.B ICANON +Enable canonical mode (described below). +.TP +.B XCASE +(not in POSIX; not supported under Linux) +If \fBICANON\fP is also set, terminal is uppercase only. +Input is converted to lowercase, except for characters preceded by \e. +On output, uppercase characters are preceded by \e and lowercase +characters are converted to uppercase. +[requires +.B _BSD_SOURCE +or +.B _SVID_SOURCE +or +.BR _XOPEN_SOURCE ] +.\" glibc is probably now wrong to allow +.\" Define +.\" .B _XOPEN_SOURCE +.\" to expose +.\" .BR XCASE . +.TP +.B ECHO +Echo input characters. +.TP +.B ECHOE +If \fBICANON\fP is also set, the ERASE character erases the preceding +input character, and WERASE erases the preceding word. +.TP +.B ECHOK +If \fBICANON\fP is also set, the KILL character erases the current line. +.TP +.B ECHONL +If \fBICANON\fP is also set, echo the NL character even if ECHO is not set. +.TP +.B ECHOCTL +(not in POSIX) If \fBECHO\fP is also set, +terminal special characters other than +TAB, NL, START, and STOP are echoed as \fB\[ha]X\fP, +where X is the character with +ASCII code 0x40 greater than the special character. +For example, character +0x08 (BS) is echoed as \fB\[ha]H\fP. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B ECHOPRT +(not in POSIX) If \fBICANON\fP and \fBECHO\fP are also set, characters +are printed as they are being erased. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B ECHOKE +(not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing +each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B DEFECHO +(not in POSIX) Echo only when a process is reading. +(Not implemented on Linux.) +.TP +.B FLUSHO +(not in POSIX; not supported under Linux) +Output is being flushed. +This flag is toggled by typing +the DISCARD character. +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B NOFLSH +Disable flushing the input and output queues when generating signals for the +INT, QUIT, and SUSP characters. +.\" Stevens lets SUSP only flush the input queue +.TP +.B TOSTOP +Send the +.B SIGTTOU +signal to the process group of a background process +which tries to write to its controlling terminal. +.TP +.B PENDIN +(not in POSIX; not supported under Linux) +All characters in the input queue are reprinted when +the next character is read. +.RB ( bash (1) +handles typeahead this way.) +[requires +.B _BSD_SOURCE +or +.BR _SVID_SOURCE ] +.TP +.B IEXTEN +Enable implementation-defined input processing. +This flag, as well as \fBICANON\fP must be enabled for the +special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted, +and for the \fBIUCLC\fP flag to be effective. +.P +The \fIc_cc\fP array defines the terminal special characters. +The symbolic indices (initial values) and meaning are: +.TP +.B VDISCARD +(not in POSIX; not supported under Linux; 017, SI, Ctrl-O) +Toggle: start/stop discarding pending output. +Recognized when +.B IEXTEN +is set, and then not passed as input. +.TP +.B VDSUSP +(not in POSIX; not supported under Linux; 031, EM, Ctrl-Y) +Delayed suspend character (DSUSP): +send +.B SIGTSTP +signal when the character is read by the user program. +Recognized when +.B IEXTEN +and +.B ISIG +are set, and the system supports +job control, and then not passed as input. +.TP +.B VEOF +(004, EOT, Ctrl-D) +End-of-file character (EOF). +More precisely: this character causes the pending tty buffer to be sent +to the waiting user program without waiting for end-of-line. +If it is the first character of the line, the +.BR read (2) +in the user program returns 0, which signifies end-of-file. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VEOL +(0, NUL) +Additional end-of-line character (EOL). +Recognized when +.B ICANON +is set. +.TP +.B VEOL2 +(not in POSIX; 0, NUL) +Yet another end-of-line character (EOL2). +Recognized when +.B ICANON +is set. +.TP +.B VERASE +(0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) +Erase character (ERASE). +This erases the previous not-yet-erased character, +but does not erase past EOF or beginning-of-line. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VINTR +(003, ETX, Ctrl-C, or also 0177, DEL, rubout) +Interrupt character (INTR). +Send a +.B SIGINT +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VKILL +(025, NAK, Ctrl-U, or Ctrl-X, or also @) +Kill character (KILL). +This erases the input since the last EOF or beginning-of-line. +Recognized when +.B ICANON +is set, and then not passed as input. +.TP +.B VLNEXT +(not in POSIX; 026, SYN, Ctrl-V) +Literal next (LNEXT). +Quotes the next input character, depriving it of +a possible special meaning. +Recognized when +.B IEXTEN +is set, and then not passed as input. +.TP +.B VMIN +Minimum number of characters for noncanonical read (MIN). +.TP +.B VQUIT +(034, FS, Ctrl-\e) +Quit character (QUIT). +Send +.B SIGQUIT +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VREPRINT +(not in POSIX; 022, DC2, Ctrl-R) +Reprint unread characters (REPRINT). +Recognized when +.B ICANON +and +.B IEXTEN +are set, and then not passed as input. +.TP +.B VSTART +(021, DC1, Ctrl-Q) +Start character (START). +Restarts output stopped by the Stop character. +Recognized when +.B IXON +is set, and then not passed as input. +.TP +.B VSTATUS +(not in POSIX; not supported under Linux; +status request: 024, DC4, Ctrl-T). +Status character (STATUS). +Display status information at terminal, +including state of foreground process and amount of CPU time it has consumed. +Also sends a +.B SIGINFO +signal (not supported on Linux) to the foreground process group. +.TP +.B VSTOP +(023, DC3, Ctrl-S) +Stop character (STOP). +Stop output until Start character typed. +Recognized when +.B IXON +is set, and then not passed as input. +.TP +.B VSUSP +(032, SUB, Ctrl-Z) +Suspend character (SUSP). +Send +.B SIGTSTP +signal. +Recognized when +.B ISIG +is set, and then not passed as input. +.TP +.B VSWTCH +(not in POSIX; not supported under Linux; 0, NUL) +Switch character (SWTCH). +Used in System V to switch shells in +.IR "shell layers" , +a predecessor to shell job control. +.TP +.B VTIME +Timeout in deciseconds for noncanonical read (TIME). +.TP +.B VWERASE +(not in POSIX; 027, ETB, Ctrl-W) +Word erase (WERASE). +Recognized when +.B ICANON +and +.B IEXTEN +are set, and then not passed as input. +.P +An individual terminal special character can be disabled by setting +the value of the corresponding +.I c_cc +element to +.BR _POSIX_VDISABLE . +.P +The above symbolic subscript values are all different, except that +.BR VTIME , +.B VMIN +may have the same value as +.BR VEOL , +.BR VEOF , +respectively. +In noncanonical mode the special character meaning is replaced +by the timeout meaning. +For an explanation of +.B VMIN +and +.BR VTIME , +see the description of +noncanonical mode below. +.SS Retrieving and changing terminal settings +.BR tcgetattr () +gets the parameters associated with the object referred by \fIfd\fP and +stores them in the \fItermios\fP structure referenced by +\fItermios_p\fP. +This function may be invoked from a background process; +however, the terminal attributes may be subsequently changed by a +foreground process. +.P +.BR tcsetattr () +sets the parameters associated with the terminal (unless support is +required from the underlying hardware that is not available) from the +\fItermios\fP structure referred to by \fItermios_p\fP. +\fIoptional_actions\fP specifies when the changes take effect: +.TP +.B TCSANOW +the change occurs immediately. +.TP +.B TCSADRAIN +the change occurs after all output written to +.I fd +has been transmitted. +This option should be used when changing +parameters that affect output. +.TP +.B TCSAFLUSH +the change occurs after all output written to the object referred by +.I fd +has been transmitted, and all input that has been received but not read +will be discarded before the change is made. +.SS Canonical and noncanonical mode +The setting of the +.B ICANON +canon flag in +.I c_lflag +determines whether the terminal is operating in canonical mode +.RB ( ICANON +set) or +noncanonical mode +.RB ( ICANON +unset). +By default, +.B ICANON +is set. +.P +In canonical mode: +.IP \[bu] 3 +Input is made available line by line. +An input line is available when one of the line delimiters +is typed (NL, EOL, EOL2; or EOF at the start of line). +Except in the case of EOF, the line delimiter is included +in the buffer returned by +.BR read (2). +.IP \[bu] +Line editing is enabled (ERASE, KILL; +and if the +.B IEXTEN +flag is set: WERASE, REPRINT, LNEXT). +A +.BR read (2) +returns at most one line of input; if the +.BR read (2) +requested fewer bytes than are available in the current line of input, +then only as many bytes as requested are read, +and the remaining characters will be available for a future +.BR read (2). +.IP \[bu] +The maximum line length is 4096 chars +(including the terminating newline character); +lines longer than 4096 chars are truncated. +After 4095 characters, input processing (e.g., +.B ISIG +and +.B ECHO* +processing) continues, but any input data after 4095 characters up to +(but not including) any terminating newline is discarded. +This ensures that the terminal can always receive +more input until at least one line can be read. +.P +In noncanonical mode input is available immediately (without +the user having to type a line-delimiter character), +no input processing is performed, +and line editing is disabled. +The read buffer will only accept 4095 chars; this provides the +necessary space for a newline char if the input mode is switched +to canonical. +The settings of MIN +.RI ( c_cc[VMIN] ) +and TIME +.RI ( c_cc[VTIME] ) +determine the circumstances in which a +.BR read (2) +completes; there are four distinct cases: +.TP +MIN == 0, TIME == 0 (polling read) +If data is available, +.BR read (2) +returns immediately, with the lesser of the number of bytes +available, or the number of bytes requested. +If no data is available, +.BR read (2) +returns 0. +.TP +MIN > 0, TIME == 0 (blocking read) +.BR read (2) +blocks until MIN bytes are available, +and returns up to the number of bytes requested. +.TP +MIN == 0, TIME > 0 (read with timeout) +TIME specifies the limit for a timer in tenths of a second. +The timer is started when +.BR read (2) +is called. +.BR read (2) +returns either when at least one byte of data is available, +or when the timer expires. +If the timer expires without any input becoming available, +.BR read (2) +returns 0. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.TP +MIN > 0, TIME > 0 (read with interbyte timeout) +TIME specifies the limit for a timer in tenths of a second. +Once an initial byte of input becomes available, +the timer is restarted after each further byte is received. +.BR read (2) +returns when any of the following conditions is met: +.RS +.IP \[bu] 3 +MIN bytes have been received. +.IP \[bu] +The interbyte timer expires. +.IP \[bu] +The number of bytes requested by +.BR read (2) +has been received. +(POSIX does not specify this termination condition, +and on some other implementations +.\" e.g., Solaris +.BR read (2) +does not return in this case.) +.RE +.IP +Because the timer is started only after the initial byte +becomes available, at least one byte will be read. +If data is already available at the time of the call to +.BR read (2), +the call behaves as though the data was received immediately after the call. +.P +POSIX +.\" POSIX.1-2008 XBD 11.1.7 +does not specify whether the setting of the +.B O_NONBLOCK +file status flag takes precedence over the MIN and TIME settings. +If +.B O_NONBLOCK +is set, a +.BR read (2) +in noncanonical mode may return immediately, +regardless of the setting of MIN or TIME. +Furthermore, if no data is available, +POSIX permits a +.BR read (2) +in noncanonical mode to return either 0, or \-1 with +.I errno +set to +.BR EAGAIN . +.SS Raw mode +.BR cfmakeraw () +sets the terminal to something like the +"raw" mode of the old Version 7 terminal driver: +input is available character by character, +echoing is disabled, and all special processing of +terminal input and output characters is disabled. +The terminal attributes are set as follows: +.P +.in +4n +.EX +termios_p\->c_iflag &= \[ti](IGNBRK | BRKINT | PARMRK | ISTRIP + | INLCR | IGNCR | ICRNL | IXON); +termios_p\->c_oflag &= \[ti]OPOST; +termios_p\->c_lflag &= \[ti](ECHO | ECHONL | ICANON | ISIG | IEXTEN); +termios_p\->c_cflag &= \[ti](CSIZE | PARENB); +termios_p\->c_cflag |= CS8; +.EE +.in +.\" +.SS Line control +.BR tcsendbreak () +transmits a continuous stream of zero-valued bits for a specific +duration, if the terminal is using asynchronous serial data +transmission. +If \fIduration\fP is zero, it transmits zero-valued bits +for at least 0.25 seconds, and not more than 0.5 seconds. +If \fIduration\fP is not zero, it sends zero-valued bits for some +implementation-defined length of time. +.P +If the terminal is not using asynchronous serial data transmission, +.BR tcsendbreak () +returns without taking any action. +.P +.BR tcdrain () +waits until all output written to the object referred to by +.I fd +has been transmitted. +.P +.BR tcflush () +discards data written to the object referred to by +.I fd +but not transmitted, or data received but not read, depending on the +value of +.IR queue_selector : +.TP +.B TCIFLUSH +flushes data received but not read. +.TP +.B TCOFLUSH +flushes data written but not transmitted. +.TP +.B TCIOFLUSH +flushes both data received but not read, and data written but not +transmitted. +.P +.BR tcflow () +suspends transmission or reception of data on the object referred to by +.IR fd , +depending on the value of +.IR action : +.TP +.B TCOOFF +suspends output. +.TP +.B TCOON +restarts suspended output. +.TP +.B TCIOFF +transmits a STOP character, which stops the terminal device from +transmitting data to the system. +.TP +.B TCION +transmits a START character, which starts the terminal device +transmitting data to the system. +.P +The default on open of a terminal file is that neither its input nor its +output is suspended. +.SS Line speed +The baud rate functions are provided for getting and setting the values +of the input and output baud rates in the \fItermios\fP structure. +The new values do not take effect +until +.BR tcsetattr () +is successfully called. +.P +Setting the speed to \fBB0\fP instructs the modem to "hang up". +The actual bit rate corresponding to \fBB38400\fP may be altered with +.BR setserial (8). +.P +The input and output baud rates are stored in the \fItermios\fP +structure. +.P +.BR cfgetospeed () +returns the output baud rate stored in the \fItermios\fP structure +pointed to by +.IR termios_p . +.P +.BR cfsetospeed () +sets the output baud rate stored in the \fItermios\fP structure pointed +to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants: +.RS +.TP +.B B0 +.TQ +.B B50 +.TQ +.B B75 +.TQ +.B B110 +.TQ +.B B134 +.TQ +.B B150 +.TQ +.B B200 +.TQ +.B B300 +.TQ +.B B600 +.TQ +.B B1200 +.TQ +.B B1800 +.TQ +.B B2400 +.TQ +.B B4800 +.TQ +.B B9600 +.TQ +.B B19200 +.TQ +.B B38400 +.TQ +.B B57600 +.TQ +.B B115200 +.TQ +.B B230400 +.TQ +.B B460800 +.TQ +.B B500000 +.TQ +.B B576000 +.TQ +.B B921600 +.TQ +.B B1000000 +.TQ +.B B1152000 +.TQ +.B B1500000 +.TQ +.B B2000000 +.RE +.P +These constants are additionally supported on the SPARC architecture: +.RS +.TP +.B B76800 +.TQ +.B B153600 +.TQ +.B B307200 +.TQ +.B B614400 +.RE +.P +These constants are additionally supported on non-SPARC architectures: +.RS +.TP +.B B2500000 +.TQ +.B B3000000 +.TQ +.B B3500000 +.TQ +.B B4000000 +.RE +.P +Due to differences between architectures, portable applications should check +if a particular +.BI B nnn +constant is defined prior to using it. +.P +The zero baud rate, +.BR B0 , +is used to terminate the connection. +If +.B B0 +is specified, the modem control lines shall no longer be asserted. +Normally, this will disconnect the line. +.B CBAUDEX +is a mask +for the speeds beyond those defined in POSIX.1 (57600 and above). +Thus, +.BR B57600 " & " CBAUDEX +is nonzero. +.P +Setting the baud rate to a value other than those defined by +.BI B nnn +constants is possible via the +.B TCSETS2 +ioctl; see +.BR ioctl_tty (2). +.P +.BR cfgetispeed () +returns the input baud rate stored in the +.I termios +structure. +.P +.BR cfsetispeed () +sets the input baud rate stored in the +.I termios +structure to +.IR speed , +which must be specified as one of the +.BI B nnn +constants listed above for +.BR cfsetospeed (). +If the input baud rate is set to the literal constant +.B 0 +(not the symbolic constant +.BR B0 ), +the input baud rate will be +equal to the output baud rate. +.P +.BR cfsetspeed () +is a 4.4BSD extension. +It takes the same arguments as +.BR cfsetispeed (), +and sets both input and output speed. +.SH RETURN VALUE +.BR cfgetispeed () +returns the input baud rate stored in the +\fItermios\fP +structure. +.P +.BR cfgetospeed () +returns the output baud rate stored in the \fItermios\fP structure. +.P +All other functions return: +.TP +.B 0 +on success. +.TP +.B \-1 +on failure and set +.I errno +to indicate the error. +.P +Note that +.BR tcsetattr () +returns success if \fIany\fP of the requested changes could be +successfully carried out. +Therefore, when making multiple changes +it may be necessary to follow this call with a further call to +.BR tcgetattr () +to check that all changes have been performed successfully. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR tcgetattr (), +.BR tcsetattr (), +.BR tcdrain (), +.BR tcflush (), +.BR tcflow (), +.BR tcsendbreak (), +.BR cfmakeraw (), +.BR cfgetispeed (), +.BR cfgetospeed (), +.BR cfsetispeed (), +.BR cfsetospeed (), +.BR cfsetspeed () +T} Thread safety MT-Safe +.TE +.\" FIXME: The markings are different from that in the glibc manual. +.\" markings in glibc manual are more detailed: +.\" +.\" tcsendbreak: MT-Unsafe race:tcattr(filedes)/bsd +.\" tcflow: MT-Unsafe race:tcattr(filedes)/bsd +.\" +.\" glibc manual says /bsd indicate the preceding marker only applies +.\" when the underlying kernel is a BSD kernel. +.\" So, it is safety in Linux kernel. +.SH STANDARDS +.TP +.BR tcgetattr () +.TQ +.BR tcsetattr () +.TQ +.BR tcsendbreak () +.TQ +.BR tcdrain () +.TQ +.BR tcflush () +.TQ +.BR tcflow () +.TQ +.BR cfgetispeed () +.TQ +.BR cfgetospeed () +.TQ +.BR cfsetispeed () +.TQ +.BR cfsetospeed () +POSIX.1-2008. +.TP +.BR cfmakeraw () +.TQ +.BR cfsetspeed () +BSD. +.SH HISTORY +.TP +.BR tcgetattr () +.TQ +.BR tcsetattr () +.TQ +.BR tcsendbreak () +.TQ +.BR tcdrain () +.TQ +.BR tcflush () +.TQ +.BR tcflow () +.TQ +.BR cfgetispeed () +.TQ +.BR cfgetospeed () +.TQ +.BR cfsetispeed () +.TQ +.BR cfsetospeed () +POSIX.1-2001. +.TP +.BR cfmakeraw () +.TQ +.BR cfsetspeed () +BSD. +.SH NOTES +UNIX\ V7 and several later systems have a list of baud rates +where after the values +.B B0 +through +.B B9600 +one finds the two constants +.BR EXTA , +.B EXTB +("External A" and "External B"). +Many systems extend the list with much higher baud rates. +.P +The effect of a nonzero \fIduration\fP with +.BR tcsendbreak () +varies. +SunOS specifies a break of +.I "duration\ *\ N" +seconds, where \fIN\fP is at least 0.25, and not more than 0.5. +Linux, AIX, DU, Tru64 send a break of +.I duration +milliseconds. +FreeBSD and NetBSD and HP-UX and MacOS ignore the value of +.IR duration . +Under Solaris and UnixWare, +.BR tcsendbreak () +with nonzero +.I duration +behaves like +.BR tcdrain (). +.\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0. +.\" libc4.7.6, libc5, glibc for unix: duration in ms. +.\" glibc for bsd: duration in us +.\" glibc for sunos4: ignore duration +.SH BUGS +.\" kernel 77e5bff1640432f28794a00800955e646dcd7455 +.\" glibc 573963e32ffac46d9891970ddebde2ac3212c5c0 +On the Alpha architecture before Linux 4.16 (and glibc before glibc 2.28), the +.B XTABS +value was different from +.B TAB3 +and it was ignored by the +.B N_TTY +line discipline code of the terminal driver as a result +(because as it wasn't part of the +.B TABDLY +mask). +.SH SEE ALSO +.BR reset (1), +.BR setterm (1), +.BR stty (1), +.BR tput (1), +.BR tset (1), +.BR tty (1), +.BR ioctl_console (2), +.BR ioctl_tty (2), +.BR cc_t (3type), +.BR speed_t (3type), +.BR tcflag_t (3type), +.BR setserial (8) |