1 .\" Copyright (c) 1993 Michael Haardt
3 .\" Fri Apr 2 11:32:09 MET DST 1993
5 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
6 .\" This is free documentation; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License as
8 .\" published by the Free Software Foundation; either version 2 of
9 .\" the License, or (at your option) any later version.
11 .\" The GNU General Public License's references to "object code"
12 .\" and "executables" are to be interpreted as the output of any
13 .\" document formatting or typesetting system, including
14 .\" intermediate and printed output.
16 .\" This manual is distributed in the hope that it will be useful,
17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 .\" GNU General Public License for more details.
21 .\" You should have received a copy of the GNU General Public
22 .\" License along with this manual; if not, see
23 .\" <http://www.gnu.org/licenses/>.
26 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
27 .\" Modified 1995-02-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
28 .\" Modified 1995-09-02 by Jim Van Zandt <jrv@vanzandt.mv.com>
29 .\" moved to man3, aeb, 950919
30 .\" Modified 2001-09-22 by Michael Kerrisk <mtk.manpages@gmail.com>
31 .\" Modified 2001-12-17, aeb
32 .\" Modified 2004-10-31, aeb
34 .\" Added .SS headers to give some structure to this page; and a
35 .\" small amount of reordering.
36 .\" Added a section on canonical and noncanonical mode.
37 .\" Enhanced the discussion of "raw" mode for cfmakeraw().
40 .TH TERMIOS 3 2014-03-21 "Linux" "Linux Programmer's Manual"
42 termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow,
43 cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \-
44 get and set terminal attributes, line control, get and set baud rate
47 .B #include <termios.h>
49 .B #include <unistd.h>
51 .BI "int tcgetattr(int " fd ", struct termios *" termios_p );
53 .BI "int tcsetattr(int " fd ", int " optional_actions ,
54 .BI " const struct termios *" termios_p );
56 .BI "int tcsendbreak(int " fd ", int " duration );
58 .BI "int tcdrain(int " fd );
60 .BI "int tcflush(int " fd ", int " queue_selector );
62 .BI "int tcflow(int " fd ", int " action );
64 .BI "void cfmakeraw(struct termios *" termios_p );
66 .BI "speed_t cfgetispeed(const struct termios *" termios_p );
68 .BI "speed_t cfgetospeed(const struct termios *" termios_p );
70 .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed );
72 .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed );
74 .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed );
78 Feature Test Macro Requirements for glibc (see
79 .BR feature_test_macros (7)):
86 The termios functions describe a general terminal interface that is
87 provided to control asynchronous communications ports.
88 .SS The termios structure
90 Many of the functions described here have a \fItermios_p\fP argument
91 that is a pointer to a \fItermios\fP structure.
92 This structure contains at least the following members:
96 tcflag_t c_iflag; /* input modes */
97 tcflag_t c_oflag; /* output modes */
98 tcflag_t c_cflag; /* control modes */
99 tcflag_t c_lflag; /* local modes */
100 cc_t c_cc[NCCS]; /* special characters */
104 The values that may be assigned to these fields are described below.
105 In the case of the first four bit-mask fields,
106 the definitions of some of the associated flags that may be set are
107 exposed only if a specific feature test macro (see
108 .BR feature_test_macros (7))
109 is defined, as noted in brackets ("[]").
111 In the descriptions below, "not in POSIX" means that the
112 value is not specified in POSIX.1-2001,
113 and "XSI" means that the value is specified in POSIX.1-2001
114 as part of the XSI extension.
116 \fIc_iflag\fP flag constants:
119 Ignore BREAK condition on input.
122 If \fBIGNBRK\fP is set, a BREAK is ignored.
124 but \fBBRKINT\fP is set, then a BREAK causes the input and output
125 queues to be flushed, and if the terminal is the controlling
126 terminal of a foreground process group, it will cause a
127 \fBSIGINT\fP to be sent to this foreground process group.
128 When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK
129 reads as a null byte (\(aq\\0\(aq), except when \fBPARMRK\fP is set,
130 in which case it reads as the sequence \\377 \\0 \\0.
133 Ignore framing errors and parity errors.
136 If \fBIGNPAR\fP is not set, prefix a character with a parity error or
137 framing error with \\377 \\0.
138 If neither \fBIGNPAR\fP nor \fBPARMRK\fP
139 is set, read a character with a parity error or framing error
143 Enable input parity checking.
146 Strip off eighth bit.
149 Translate NL to CR on input.
152 Ignore carriage return on input.
155 Translate carriage return to newline on input (unless \fBIGNCR\fP is set).
158 (not in POSIX) Map uppercase characters to lowercase on input.
161 Enable XON/XOFF flow control on output.
164 (XSI) Typing any character will restart stopped output.
165 (The default is to allow just the START character to restart output.)
168 Enable XON/XOFF flow control on input.
171 (not in POSIX) Ring bell when input queue is full.
172 Linux does not implement this bit, and acts as if it is always set.
174 .BR IUTF8 " (since Linux 2.6.4)"
175 (not in POSIX) Input is UTF8;
176 this allows character-erase to be correctly performed in cooked mode.
178 \fIc_oflag\fP flag constants defined in POSIX.1:
181 Enable implementation-defined output processing.
183 The remaining \fIc_oflag\fP flag constants are defined in POSIX.1-2001,
184 unless marked otherwise.
187 (not in POSIX) Map lowercase characters to uppercase on output.
190 (XSI) Map NL to CR-NL on output.
193 Map CR to NL on output.
196 Don't output CR at column 0.
202 Send fill characters for a delay, rather than using a timed delay.
205 (not in POSIX) Fill character is ASCII DEL (0177).
206 If unset, fill character is ASCII NUL (\(aq\\0\(aq).
207 (Not implemented on Linux.)
211 Values are \fBNL0\fP and \fBNL1\fP.
220 Carriage return delay mask.
221 Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP.
230 Horizontal tab delay mask.
231 Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP).
232 A value of TAB3, that is, XTABS, expands tabs to spaces
233 (with tab stops every eight columns).
242 Backspace delay mask.
243 Values are \fBBS0\fP or \fBBS1\fP.
244 (Has never been implemented.)
253 Vertical tab delay mask.
254 Values are \fBVT0\fP or \fBVT1\fP.
257 Form feed delay mask.
258 Values are \fBFF0\fP or \fBFF1\fP.
266 \fIc_cflag\fP flag constants:
269 (not in POSIX) Baud speed mask (4+1 bits).
276 (not in POSIX) Extra baud speed mask (1 bit), included in
283 (POSIX says that the baud speed is stored in the
285 structure without specifying where precisely, and provides
290 Some systems use bits selected by
294 other systems use separate fields, for example,
301 Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP.
304 Set two stop bits, rather than one.
310 Enable parity generation on output and parity checking for input.
313 If set, then parity for input and output is odd;
314 otherwise even parity is used.
317 Lower modem control lines after last process closes the device (hang up).
320 Ignore modem control lines.
323 (not in POSIX) Block output from a noncurrent shell layer.
324 For use by \fBshl\fP (shell layers). (Not implemented on Linux.)
327 (not in POSIX) Mask for input speeds.
331 the same as the values for the
340 (Not implemented on Linux.)
344 Use "stick" (mark/space) parity (supported on certain serial
347 is set, the parity bit is always 1; if
349 is not set, then the parity bit is always 0).
356 (not in POSIX) Enable RTS/CTS (hardware) flow control.
362 \fIc_lflag\fP flag constants:
365 When any of the characters INTR, QUIT, SUSP, or DSUSP are received,
366 generate the corresponding signal.
369 Enable canonical mode (described below).
372 (not in POSIX; not supported under Linux)
373 If \fBICANON\fP is also set, terminal is uppercase only.
374 Input is converted to lowercase, except for characters preceded by \\.
375 On output, uppercase characters are preceded by \\ and lowercase
376 characters are converted to uppercase.
377 [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
378 .\" glibc is probably now wrong to allow
385 Echo input characters.
388 If \fBICANON\fP is also set, the ERASE character erases the preceding
389 input character, and WERASE erases the preceding word.
392 If \fBICANON\fP is also set, the KILL character erases the current line.
395 If \fBICANON\fP is also set, echo the NL character even if ECHO is not set.
398 (not in POSIX) If \fBECHO\fP is also set,
399 terminal special characters other than
400 TAB, NL, START, and STOP are echoed as \fB^X\fP,
401 where X is the character with
402 ASCII code 0x40 greater than the special character.
403 For example, character
404 0x08 (BS) is echoed as \fB^H\fP.
411 (not in POSIX) If \fBICANON\fP and \fBECHO\fP are also set, characters
412 are printed as they are being erased.
419 (not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing
420 each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP.
427 (not in POSIX) Echo only when a process is reading.
428 (Not implemented on Linux.)
431 (not in POSIX; not supported under Linux)
432 Output is being flushed.
433 This flag is toggled by typing
434 the DISCARD character.
441 Disable flushing the input and output queues when generating signals for the
442 INT, QUIT, and SUSP characters.
443 .\" Stevens lets SUSP only flush the input queue
448 signal to the process group of a background process
449 which tries to write to its controlling terminal.
452 (not in POSIX; not supported under Linux)
453 All characters in the input queue are reprinted when
454 the next character is read.
456 handles typeahead this way.)
463 Enable implementation-defined input processing.
464 This flag, as well as \fBICANON\fP must be enabled for the
465 special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted,
466 and for the \fBIUCLC\fP flag to be effective.
468 The \fIc_cc\fP array defines the terminal special characters.
469 The symbolic indices (initial values) and meaning are:
472 (not in POSIX; not supported under Linux; 017, SI, Ctrl-O)
473 Toggle: start/stop discarding pending output.
476 is set, and then not passed as input.
479 (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y)
480 Delayed suspend character (DSUSP):
483 signal when the character is read by the user program.
488 are set, and the system supports
489 job control, and then not passed as input.
493 End-of-file character (EOF).
494 More precisely: this character causes the pending tty buffer to be sent
495 to the waiting user program without waiting for end-of-line.
496 If it is the first character of the line, the
498 in the user program returns 0, which signifies end-of-file.
501 is set, and then not passed as input.
505 Additional end-of-line character (EOL).
511 (not in POSIX; 0, NUL)
512 Yet another end-of-line character (EOL2).
518 (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #)
519 Erase character (ERASE).
520 This erases the previous not-yet-erased character,
521 but does not erase past EOF or beginning-of-line.
524 is set, and then not passed as input.
527 (003, ETX, Ctrl-C, or also 0177, DEL, rubout)
528 Interrupt character (INTR).
534 is set, and then not passed as input.
537 (025, NAK, Ctrl-U, or Ctrl-X, or also @)
538 Kill character (KILL).
539 This erases the input since the last EOF or beginning-of-line.
542 is set, and then not passed as input.
545 (not in POSIX; 026, SYN, Ctrl-V)
546 Literal next (LNEXT).
547 Quotes the next input character, depriving it of
548 a possible special meaning.
551 is set, and then not passed as input.
554 Minimum number of characters for noncanonical read (MIN).
558 Quit character (QUIT).
564 is set, and then not passed as input.
567 (not in POSIX; 022, DC2, Ctrl-R)
568 Reprint unread characters (REPRINT).
573 are set, and then not passed as input.
577 Start character (START).
578 Restarts output stopped by the Stop character.
581 is set, and then not passed as input.
584 (not in POSIX; not supported under Linux;
585 status request: 024, DC4, Ctrl-T).
586 Status character (STATUS).
587 Display status information at terminal,
588 including state of foreground process and amount of CPU time it has consumed.
591 signal (not supported on Linux) to the foreground process group.
595 Stop character (STOP).
596 Stop output until Start character typed.
599 is set, and then not passed as input.
603 Suspend character (SUSP).
609 is set, and then not passed as input.
612 (not in POSIX; not supported under Linux; 0, NUL)
613 Switch character (SWTCH).
614 Used in System V to switch shells in
616 a predecessor to shell job control.
619 Timeout in deciseconds for noncanonical read (TIME).
622 (not in POSIX; 027, ETB, Ctrl-W)
628 are set, and then not passed as input.
630 An individual terminal special character can be disabled by setting
631 the value of the corresponding
634 .BR _POSIX_VDISABLE .
636 The above symbolic subscript values are all different, except that
639 may have the same value as
643 In noncanonical mode the special character meaning is replaced
644 by the timeout meaning.
645 For an explanation of
649 see the description of
650 noncanonical mode below.
651 .SS Retrieving and changing terminal settings
654 gets the parameters associated with the object referred by \fIfd\fP and
655 stores them in the \fItermios\fP structure referenced by
657 This function may be invoked from a background process;
658 however, the terminal attributes may be subsequently changed by a
662 sets the parameters associated with the terminal (unless support is
663 required from the underlying hardware that is not available) from the
664 \fItermios\fP structure referred to by \fItermios_p\fP.
665 \fIoptional_actions\fP specifies when the changes take effect:
667 the change occurs immediately.
669 the change occurs after all output written to
671 has been transmitted.
672 This function should be used when changing
673 parameters that affect output.
675 the change occurs after all output written to the object referred by
677 has been transmitted, and all input that has been received but not read
678 will be discarded before the change is made.
679 .SS Canonical and noncanonical mode
684 determines whether the terminal is operating in canonical mode
696 Input is made available line by line.
697 An input line is available when one of the line delimiters
698 is typed (NL, EOL, EOL2; or EOF at the start of line).
699 Except in the case of EOF, the line delimiter is included
700 in the buffer returned by
703 Line editing is enabled (ERASE, KILL;
706 flag is set: WERASE, REPRINT, LNEXT).
709 returns at most one line of input; if the
711 requested fewer bytes than are available in the current line of input,
712 then only as many bytes as requested are read,
713 and the remaining characters will be available for a future
716 In noncanonical mode input is available immediately (without
717 the user having to type a line-delimiter character),
718 no input processing is performed,
719 and line editing is disabled.
724 determine the circumstances in which a
726 completes; there are four distinct cases:
728 MIN == 0, TIME == 0 (polling read)
729 If data is available,
731 returns immediately, with the lesser of the number of bytes
732 available, or the number of bytes requested.
733 If no data is available,
737 MIN > 0, TIME == 0 (blocking read)
739 blocks until MIN bytes are available,
740 and returns up to the number of bytes requested.
742 MIN == 0, TIME > 0 (read with timeout)
743 TIME specifies the limit for a timer in tenths of a second.
744 The timer is started when
748 returns either when at least one byte of data is available,
749 or when the timer expires.
750 If the timer expires without any input becoming available,
753 If data is already available at the time of the call to
755 the call behaves as though the data was received immediately after the call.
757 MIN > 0, TIME > 0 (read with interbyte timeout)
758 TIME specifies the limit for a timer in tenths of a second.
759 Once an initial byte of input becomes available,
760 the timer is restarted after each further byte is received.
762 returns when any of the following conditions is met:
765 MIN bytes have been received.
767 The interbyte timer expires.
769 The number of bytes requested by
772 (POSIX does not specify this termination condition,
773 and on some other implementations
776 does not return in this case.)
779 Because the timer is started only after the initial byte
780 becomes available, at least one byte will be read.
781 If data is already available at the time of the call to
783 the call behaves as though the data was received immediately after the call.
786 .\" POSIX.1-2008 XBD 11.1.7
787 does not specify whether the setting of the
789 file status flag takes precedence over the MIN and TIME settings.
794 in noncanonical mode may return immediately,
795 regardless of the setting of MIN or TIME.
796 Furthermore, if no data is available,
799 in noncanonical mode to return either 0, or \-1 with
806 sets the terminal to something like the
807 "raw" mode of the old Version 7 terminal driver:
808 input is available character by character,
809 echoing is disabled, and all special processing of
810 terminal input and output characters is disabled.
811 The terminal attributes are set as follows:
814 termios_p\->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP
815 | INLCR | IGNCR | ICRNL | IXON);
816 termios_p\->c_oflag &= ~OPOST;
817 termios_p\->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN);
818 termios_p\->c_cflag &= ~(CSIZE | PARENB);
819 termios_p\->c_cflag |= CS8;
824 transmits a continuous stream of zero-valued bits for a specific
825 duration, if the terminal is using asynchronous serial data
827 If \fIduration\fP is zero, it transmits zero-valued bits
828 for at least 0.25 seconds, and not more that 0.5 seconds.
829 If \fIduration\fP is not zero, it sends zero-valued bits for some
830 implementation-defined length of time.
832 If the terminal is not using asynchronous serial data transmission,
834 returns without taking any action.
837 waits until all output written to the object referred to by
839 has been transmitted.
842 discards data written to the object referred to by
844 but not transmitted, or data received but not read, depending on the
848 flushes data received but not read.
850 flushes data written but not transmitted.
852 flushes both data received but not read, and data written but not
856 suspends transmission or reception of data on the object referred to by
858 depending on the value of
863 restarts suspended output.
865 transmits a STOP character, which stops the terminal device from
866 transmitting data to the system.
868 transmits a START character, which starts the terminal device
869 transmitting data to the system.
871 The default on open of a terminal file is that neither its input nor its
874 The baud rate functions are provided for getting and setting the values
875 of the input and output baud rates in the \fItermios\fP structure.
876 The new values do not take effect
879 is successfully called.
881 Setting the speed to \fBB0\fP instructs the modem to "hang up".
882 The actual bit rate corresponding to \fBB38400\fP may be altered with
885 The input and output baud rates are stored in the \fItermios\fP
889 returns the output baud rate stored in the \fItermios\fP structure
894 sets the output baud rate stored in the \fItermios\fP structure pointed
895 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
921 The zero baud rate, \fBB0\fP,
922 is used to terminate the connection.
923 If B0 is specified, the modem control lines shall no longer be asserted.
924 Normally, this will disconnect the line.
925 \fBCBAUDEX\fP is a mask
926 for the speeds beyond those defined in POSIX.1 (57600 and above).
927 Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero.
930 returns the input baud rate stored in the \fItermios\fP structure.
933 sets the input baud rate stored in the \fItermios\fP structure to
935 which must be specified as one of the \fBBnnn\fP constants listed above for
937 If the input baud rate is set to zero, the input baud rate will be
938 equal to the output baud rate.
941 is a 4.4BSD extension.
942 It takes the same arguments as
944 and sets both input and output speed.
948 returns the input baud rate stored in the
953 returns the output baud rate stored in the \fItermios\fP structure.
955 All other functions return:
961 to indicate the error.
965 returns success if \fIany\fP of the requested changes could be
966 successfully carried out.
967 Therefore, when making multiple changes
968 it may be necessary to follow this call with a further call to
970 to check that all changes have been performed successfully.
972 .SS Multithreading (see pthreads(7))
987 functions are thread-safe.
1000 are specified in POSIX.1-2001.
1005 are nonstandard, but available on the BSDs.
1007 UNIX V7 and several later systems have a list of baud rates
1008 where after the fourteen values B0, ..., B9600 one finds the
1009 two constants EXTA, EXTB ("External A" and "External B").
1010 Many systems extend the list with much higher baud rates.
1012 The effect of a nonzero \fIduration\fP with
1015 SunOS specifies a break of
1017 seconds, where \fIN\fP is at least 0.25, and not more than 0.5.
1018 Linux, AIX, DU, Tru64 send a break of
1021 FreeBSD and NetBSD and HP-UX and MacOS ignore the value of
1023 Under Solaris and UnixWare,
1029 .\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0.
1030 .\" libc4.7.6, libc5, glibc for unix: duration in ms.
1031 .\" glibc for bsd: duration in us
1032 .\" glibc for sunos4: ignore duration
1035 .BR console_ioctl (4),
1039 This page is part of release 3.64 of the Linux
1042 A description of the project,
1043 and information about reporting bugs,
1045 \%http://www.kernel.org/doc/man\-pages/.