| .\" Copyright (c) 1993 Michael Haardt |
| .\" (michael@moria.de) |
| .\" Fri Apr 2 11:32:09 MET DST 1993 |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; you can redistribute it and/or |
| .\" modify it under the terms of the GNU General Public License as |
| .\" published by the Free Software Foundation; either version 2 of |
| .\" the License, or (at your option) any later version. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual is distributed in the hope that it will be useful, |
| .\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| .\" GNU General Public License for more details. |
| .\" |
| .\" You should have received a copy of the GNU General Public |
| .\" License along with this manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2016-03-15 "Linux" "Linux Programmer's Manual" |
| .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 SYNOPSIS |
| .nf |
| .B #include <termios.h> |
| .br |
| .B #include <unistd.h> |
| .sp |
| .BI "int tcgetattr(int " fd ", struct termios *" termios_p ); |
| .sp |
| .BI "int tcsetattr(int " fd ", int " optional_actions , |
| .BI " const struct termios *" termios_p ); |
| .sp |
| .BI "int tcsendbreak(int " fd ", int " duration ); |
| .sp |
| .BI "int tcdrain(int " fd ); |
| .sp |
| .BI "int tcflush(int " fd ", int " queue_selector ); |
| .sp |
| .BI "int tcflow(int " fd ", int " action ); |
| .sp |
| .BI "void cfmakeraw(struct termios *" termios_p ); |
| .sp |
| .BI "speed_t cfgetispeed(const struct termios *" termios_p ); |
| .sp |
| .BI "speed_t cfgetospeed(const struct termios *" termios_p ); |
| .sp |
| .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed ); |
| .sp |
| .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed ); |
| .sp |
| .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed ); |
| .fi |
| .sp |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .sp |
| .BR cfsetspeed (), |
| .BR cfmakeraw (): |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| Glibc 2.19 and earlier: |
| _BSD_SOURCE |
| .SH DESCRIPTION |
| The termios functions describe a general terminal interface that is |
| provided to control asynchronous communications ports. |
| .SS The termios structure |
| .LP |
| 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: |
| .sp |
| .in +4n |
| .nf |
| 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 */ |
| .fi |
| .in |
| .PP |
| 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 ("[]"). |
| .PP |
| 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. |
| .PP |
| \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\\0\(aq), except when \fBPARMRK\fP is set, |
| in which case it reads as the sequence \\377 \\0 \\0. |
| .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, |
| \\377 and \\0. |
| Thus, the program actually reads three bytes for one |
| erroneous byte received from the terminal. |
| If a valid byte has the value \\377, |
| 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 \\377 is passed to the program as two |
| bytes, \\377 \\377, in this case. |
| |
| If neither \fBIGNPAR\fP nor \fBPARMRK\fP |
| is set, read a character with a parity error or framing error |
| as \\0. |
| .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. |
| .PP |
| .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 |
| Don't output 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\\0\(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). |
| 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 ] |
| .PP |
| \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 ] |
| .sp |
| (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 on Linux.) |
| .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 ] |
| .PP |
| \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 \\. |
| On output, uppercase characters are preceded by \\ 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^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^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. |
| .PP |
| 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 |
| .BR 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. |
| .LP |
| An individual terminal special character can be disabled by setting |
| the value of the corresponding |
| .I c_cc |
| element to |
| .BR _POSIX_VDISABLE . |
| .LP |
| 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 |
| .PP |
| .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. |
| .LP |
| .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: |
| .IP \fBTCSANOW\fP |
| the change occurs immediately. |
| .IP \fBTCSADRAIN\fP |
| the change occurs after all output written to |
| .I fd |
| has been transmitted. |
| This option should be used when changing |
| parameters that affect output. |
| .IP \fBTCSAFLUSH\fP |
| 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. |
| |
| In canonical mode: |
| .IP * 2 |
| 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 * 2 |
| 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 * 2 |
| 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. |
| .PP |
| 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 * 3 |
| MIN bytes have been received. |
| .IP * |
| The interbyte timer expires. |
| .IP * |
| 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. |
| .PP |
| 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 |
| .LP |
| .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: |
| .nf |
| |
| termios_p\->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP |
| | INLCR | IGNCR | ICRNL | IXON); |
| termios_p\->c_oflag &= ~OPOST; |
| termios_p\->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN); |
| termios_p\->c_cflag &= ~(CSIZE | PARENB); |
| termios_p\->c_cflag |= CS8; |
| .fi |
| .SS Line control |
| .LP |
| .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 that 0.5 seconds. |
| If \fIduration\fP is not zero, it sends zero-valued bits for some |
| implementation-defined length of time. |
| .LP |
| If the terminal is not using asynchronous serial data transmission, |
| .BR tcsendbreak () |
| returns without taking any action. |
| .LP |
| .BR tcdrain () |
| waits until all output written to the object referred to by |
| .I fd |
| has been transmitted. |
| .LP |
| .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 : |
| .IP \fBTCIFLUSH\fP |
| flushes data received but not read. |
| .IP \fBTCOFLUSH\fP |
| flushes data written but not transmitted. |
| .IP \fBTCIOFLUSH\fP |
| flushes both data received but not read, and data written but not |
| transmitted. |
| .LP |
| .BR tcflow () |
| suspends transmission or reception of data on the object referred to by |
| .IR fd , |
| depending on the value of |
| .IR action : |
| .IP \fBTCOOFF\fP |
| suspends output. |
| .IP \fBTCOON\fP |
| restarts suspended output. |
| .IP \fBTCIOFF\fP |
| transmits a STOP character, which stops the terminal device from |
| transmitting data to the system. |
| .IP \fBTCION\fP |
| transmits a START character, which starts the terminal device |
| transmitting data to the system. |
| .LP |
| 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. |
| |
| 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). |
| .LP |
| The input and output baud rates are stored in the \fItermios\fP |
| structure. |
| .LP |
| .BR cfgetospeed () |
| returns the output baud rate stored in the \fItermios\fP structure |
| pointed to by |
| .IR termios_p . |
| .LP |
| .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: |
| .nf |
| |
| .ft B |
| B0 |
| B50 |
| B75 |
| B110 |
| B134 |
| B150 |
| B200 |
| B300 |
| B600 |
| B1200 |
| B1800 |
| B2400 |
| B4800 |
| B9600 |
| B19200 |
| B38400 |
| B57600 |
| B115200 |
| B230400 |
| .ft P |
| |
| .fi |
| The zero baud rate, \fBB0\fP, |
| is used to terminate the connection. |
| If B0 is specified, the modem control lines shall no longer be asserted. |
| Normally, this will disconnect the line. |
| \fBCBAUDEX\fP is a mask |
| for the speeds beyond those defined in POSIX.1 (57600 and above). |
| Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero. |
| .LP |
| .BR cfgetispeed () |
| returns the input baud rate stored in the \fItermios\fP structure. |
| .LP |
| .BR cfsetispeed () |
| sets the input baud rate stored in the \fItermios\fP structure to |
| .IR speed , |
| which must be specified as one of the \fBBnnn\fP constants listed above for |
| .BR cfsetospeed (). |
| If the input baud rate is set to zero, the input baud rate will be |
| equal to the output baud rate. |
| .LP |
| .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 |
| .LP |
| .BR cfgetispeed () |
| returns the input baud rate stored in the |
| \fItermios\fP |
| structure. |
| .LP |
| .BR cfgetospeed () |
| returns the output baud rate stored in the \fItermios\fP structure. |
| .LP |
| All other functions return: |
| .IP 0 |
| on success. |
| .IP \-1 |
| on failure and set |
| .I errno |
| to indicate the error. |
| .LP |
| 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). |
| .nh |
| .ad l |
| .TS |
| allbox; |
| lbw36 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR tcgetattr (), |
| .BR tcsetattr (), |
| .BR tcdrain (), |
| .BR tcflush (), |
| .BR tcflow (), |
| .BR tcsendbreak (), |
| .BR cfmakeraw (), |
| .BR cfgetispeed (), |
| .BR cfgetospeed (), |
| .BR cfsetispeed (), |
| .BR cfsetospeed (), |
| .BR cfsetspeed () |
| .\" FIXME: the following markings are different from which in 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. |
| T} Thread safety MT-Safe |
| .TE |
| .ad |
| .hy |
| .SH CONFORMING TO |
| .BR tcgetattr (), |
| .BR tcsetattr (), |
| .BR tcsendbreak (), |
| .BR tcdrain (), |
| .BR tcflush (), |
| .BR tcflow (), |
| .BR cfgetispeed (), |
| .BR cfgetospeed (), |
| .BR cfsetispeed (), |
| and |
| .BR cfsetospeed () |
| are specified in POSIX.1-2001. |
| |
| .BR cfmakeraw () |
| and |
| .BR cfsetspeed () |
| are nonstandard, but available on the BSDs. |
| .SH NOTES |
| UNIX\ V7 and several later systems have a list of baud rates |
| where after the fourteen values B0, ..., B9600 one finds the |
| two constants EXTA, EXTB ("External A" and "External B"). |
| Many systems extend the list with much higher baud rates. |
| .LP |
| 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 SEE ALSO |
| .BR reset (1), |
| .BR setterm (1), |
| .BR stty (1), |
| .BR tput (1), |
| .BR tset (1), |
| .BR tty (1), |
| .BR console_ioctl (4), |
| .BR tty_ioctl (4), |
| .BR setserial (8) |