2 .\" Copyright (c) 1993 Michael Haardt (michael@moria.de)
3 .\" Fri Apr 2 11:32:09 MET DST 1993
4 .\" Copyright (c) 2006-2015, Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
8 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
9 .\" Modified 1995-02-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
10 .\" Modified 1995-09-02 by Jim Van Zandt <jrv@vanzandt.mv.com>
11 .\" moved to man3, aeb, 950919
12 .\" Modified 2001-09-22 by Michael Kerrisk <mtk.manpages@gmail.com>
13 .\" Modified 2001-12-17, aeb
14 .\" Modified 2004-10-31, aeb
16 .\" Added .SS headers to give some structure to this page; and a
17 .\" small amount of reordering.
18 .\" Added a section on canonical and noncanonical mode.
19 .\" Enhanced the discussion of "raw" mode for cfmakeraw().
22 .TH termios 3 (date) "Linux man-pages (unreleased)"
24 termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow,
25 cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \-
26 get and set terminal attributes, line control, get and set baud rate
29 .RI ( libc ", " \-lc )
32 .B #include <termios.h>
33 .B #include <unistd.h>
35 .BI "int tcgetattr(int " fd ", struct termios *" termios_p );
36 .BI "int tcsetattr(int " fd ", int " optional_actions ,
37 .BI " const struct termios *" termios_p );
39 .BI "int tcsendbreak(int " fd ", int " duration );
40 .BI "int tcdrain(int " fd );
41 .BI "int tcflush(int " fd ", int " queue_selector );
42 .BI "int tcflow(int " fd ", int " action );
44 .BI "void cfmakeraw(struct termios *" termios_p );
46 .BI "speed_t cfgetispeed(const struct termios *" termios_p );
47 .BI "speed_t cfgetospeed(const struct termios *" termios_p );
49 .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed );
50 .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed );
51 .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed );
55 Feature Test Macro Requirements for glibc (see
56 .BR feature_test_macros (7)):
64 Glibc 2.19 and earlier:
68 The termios functions describe a general terminal interface that is
69 provided to control asynchronous communications ports.
70 .SS The termios structure
71 Many of the functions described here have a \fItermios_p\fP argument
72 that is a pointer to a \fItermios\fP structure.
73 This structure contains at least the following members:
77 tcflag_t c_iflag; /* input modes */
78 tcflag_t c_oflag; /* output modes */
79 tcflag_t c_cflag; /* control modes */
80 tcflag_t c_lflag; /* local modes */
81 cc_t c_cc[NCCS]; /* special characters */
85 The values that may be assigned to these fields are described below.
86 In the case of the first four bit-mask fields,
87 the definitions of some of the associated flags that may be set are
88 exposed only if a specific feature test macro (see
89 .BR feature_test_macros (7))
90 is defined, as noted in brackets ("[]").
92 In the descriptions below, "not in POSIX" means that the
93 value is not specified in POSIX.1-2001,
94 and "XSI" means that the value is specified in POSIX.1-2001
95 as part of the XSI extension.
97 \fIc_iflag\fP flag constants:
100 Ignore BREAK condition on input.
103 If \fBIGNBRK\fP is set, a BREAK is ignored.
105 but \fBBRKINT\fP is set, then a BREAK causes the input and output
106 queues to be flushed, and if the terminal is the controlling
107 terminal of a foreground process group, it will cause a
108 \fBSIGINT\fP to be sent to this foreground process group.
109 When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK
110 reads as a null byte (\(aq\e0\(aq), except when \fBPARMRK\fP is set,
111 in which case it reads as the sequence \e377 \e0 \e0.
114 Ignore framing errors and parity errors.
117 If this bit is set, input bytes with parity or framing errors are
118 marked when passed to the program.
119 This bit is meaningful only when
120 \fBINPCK\fP is set and \fBIGNPAR\fP is not set.
121 The way erroneous bytes are marked is with two preceding bytes,
123 Thus, the program actually reads three bytes for one
124 erroneous byte received from the terminal.
125 If a valid byte has the value \e377,
126 and \fBISTRIP\fP (see below) is not set,
127 the program might confuse it with the prefix that marks a
129 Therefore, a valid byte \e377 is passed to the program as two
130 bytes, \e377 \e377, in this case.
132 If neither \fBIGNPAR\fP nor \fBPARMRK\fP
133 is set, read a character with a parity error or framing error
137 Enable input parity checking.
140 Strip off eighth bit.
143 Translate NL to CR on input.
146 Ignore carriage return on input.
149 Translate carriage return to newline on input (unless \fBIGNCR\fP is set).
152 (not in POSIX) Map uppercase characters to lowercase on input.
155 Enable XON/XOFF flow control on output.
158 (XSI) Typing any character will restart stopped output.
159 (The default is to allow just the START character to restart output.)
162 Enable XON/XOFF flow control on input.
165 (not in POSIX) Ring bell when input queue is full.
166 Linux does not implement this bit, and acts as if it is always set.
168 .BR IUTF8 " (since Linux 2.6.4)"
169 (not in POSIX) Input is UTF8;
170 this allows character-erase to be correctly performed in cooked mode.
176 Enable implementation-defined output processing.
179 (not in POSIX) Map lowercase characters to uppercase on output.
182 (XSI) Map NL to CR-NL on output.
185 Map CR to NL on output.
188 Don't output CR at column 0.
191 The NL character is assumed to do the carriage-return function;
192 the kernel's idea of the current column is set to 0
193 after both NL and CR.
196 Send fill characters for a delay, rather than using a timed delay.
199 Fill character is ASCII DEL (0177).
200 If unset, fill character is ASCII NUL (\(aq\e0\(aq).
201 (Not implemented on Linux.)
205 Values are \fBNL0\fP and \fBNL1\fP.
214 Carriage return delay mask.
215 Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP.
224 Horizontal tab delay mask.
225 Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP,
229 A value of TAB3, that is, XTABS, expands tabs to spaces
230 (with tab stops every eight columns).
239 Backspace delay mask.
240 Values are \fBBS0\fP or \fBBS1\fP.
241 (Has never been implemented.)
250 Vertical tab delay mask.
251 Values are \fBVT0\fP or \fBVT1\fP.
254 Form feed delay mask.
255 Values are \fBFF0\fP or \fBFF1\fP.
263 \fIc_cflag\fP flag constants:
266 (not in POSIX) Baud speed mask (4+1 bits).
273 (not in POSIX) Extra baud speed mask (1 bit), included in
280 (POSIX says that the baud speed is stored in the
282 structure without specifying where precisely, and provides
287 Some systems use bits selected by
291 other systems use separate fields, for example,
298 Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP.
301 Set two stop bits, rather than one.
307 Enable parity generation on output and parity checking for input.
310 If set, then parity for input and output is odd;
311 otherwise even parity is used.
314 Lower modem control lines after last process closes the device (hang up).
317 Ignore modem control lines.
320 (not in POSIX) Block output from a noncurrent shell layer.
321 For use by \fBshl\fP (shell layers).
322 (Not implemented on Linux.)
325 (not in POSIX) Mask for input speeds.
329 the same as the values for the
338 (Not implemented in glibc, supported on Linux via
347 Use "stick" (mark/space) parity (supported on certain serial
350 is set, the parity bit is always 1; if
352 is not set, then the parity bit is always 0.
359 (not in POSIX) Enable RTS/CTS (hardware) flow control.
365 \fIc_lflag\fP flag constants:
368 When any of the characters INTR, QUIT, SUSP, or DSUSP are received,
369 generate the corresponding signal.
372 Enable canonical mode (described below).
375 (not in POSIX; not supported under Linux)
376 If \fBICANON\fP is also set, terminal is uppercase only.
377 Input is converted to lowercase, except for characters preceded by \e.
378 On output, uppercase characters are preceded by \e and lowercase
379 characters are converted to uppercase.
386 .\" glibc is probably now wrong to allow
393 Echo input characters.
396 If \fBICANON\fP is also set, the ERASE character erases the preceding
397 input character, and WERASE erases the preceding word.
400 If \fBICANON\fP is also set, the KILL character erases the current line.
403 If \fBICANON\fP is also set, echo the NL character even if ECHO is not set.
406 (not in POSIX) If \fBECHO\fP is also set,
407 terminal special characters other than
408 TAB, NL, START, and STOP are echoed as \fB\(haX\fP,
409 where X is the character with
410 ASCII code 0x40 greater than the special character.
411 For example, character
412 0x08 (BS) is echoed as \fB\(haH\fP.
419 (not in POSIX) If \fBICANON\fP and \fBECHO\fP are also set, characters
420 are printed as they are being erased.
427 (not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing
428 each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP.
435 (not in POSIX) Echo only when a process is reading.
436 (Not implemented on Linux.)
439 (not in POSIX; not supported under Linux)
440 Output is being flushed.
441 This flag is toggled by typing
442 the DISCARD character.
449 Disable flushing the input and output queues when generating signals for the
450 INT, QUIT, and SUSP characters.
451 .\" Stevens lets SUSP only flush the input queue
456 signal to the process group of a background process
457 which tries to write to its controlling terminal.
460 (not in POSIX; not supported under Linux)
461 All characters in the input queue are reprinted when
462 the next character is read.
464 handles typeahead this way.)
471 Enable implementation-defined input processing.
472 This flag, as well as \fBICANON\fP must be enabled for the
473 special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted,
474 and for the \fBIUCLC\fP flag to be effective.
476 The \fIc_cc\fP array defines the terminal special characters.
477 The symbolic indices (initial values) and meaning are:
480 (not in POSIX; not supported under Linux; 017, SI, Ctrl-O)
481 Toggle: start/stop discarding pending output.
484 is set, and then not passed as input.
487 (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y)
488 Delayed suspend character (DSUSP):
491 signal when the character is read by the user program.
496 are set, and the system supports
497 job control, and then not passed as input.
501 End-of-file character (EOF).
502 More precisely: this character causes the pending tty buffer to be sent
503 to the waiting user program without waiting for end-of-line.
504 If it is the first character of the line, the
506 in the user program returns 0, which signifies end-of-file.
509 is set, and then not passed as input.
513 Additional end-of-line character (EOL).
519 (not in POSIX; 0, NUL)
520 Yet another end-of-line character (EOL2).
526 (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #)
527 Erase character (ERASE).
528 This erases the previous not-yet-erased character,
529 but does not erase past EOF or beginning-of-line.
532 is set, and then not passed as input.
535 (003, ETX, Ctrl-C, or also 0177, DEL, rubout)
536 Interrupt character (INTR).
542 is set, and then not passed as input.
545 (025, NAK, Ctrl-U, or Ctrl-X, or also @)
546 Kill character (KILL).
547 This erases the input since the last EOF or beginning-of-line.
550 is set, and then not passed as input.
553 (not in POSIX; 026, SYN, Ctrl-V)
554 Literal next (LNEXT).
555 Quotes the next input character, depriving it of
556 a possible special meaning.
559 is set, and then not passed as input.
562 Minimum number of characters for noncanonical read (MIN).
566 Quit character (QUIT).
572 is set, and then not passed as input.
575 (not in POSIX; 022, DC2, Ctrl-R)
576 Reprint unread characters (REPRINT).
581 are set, and then not passed as input.
585 Start character (START).
586 Restarts output stopped by the Stop character.
589 is set, and then not passed as input.
592 (not in POSIX; not supported under Linux;
593 status request: 024, DC4, Ctrl-T).
594 Status character (STATUS).
595 Display status information at terminal,
596 including state of foreground process and amount of CPU time it has consumed.
599 signal (not supported on Linux) to the foreground process group.
603 Stop character (STOP).
604 Stop output until Start character typed.
607 is set, and then not passed as input.
611 Suspend character (SUSP).
617 is set, and then not passed as input.
620 (not in POSIX; not supported under Linux; 0, NUL)
621 Switch character (SWTCH).
622 Used in System V to switch shells in
624 a predecessor to shell job control.
627 Timeout in deciseconds for noncanonical read (TIME).
630 (not in POSIX; 027, ETB, Ctrl-W)
636 are set, and then not passed as input.
638 An individual terminal special character can be disabled by setting
639 the value of the corresponding
642 .BR _POSIX_VDISABLE .
644 The above symbolic subscript values are all different, except that
647 may have the same value as
651 In noncanonical mode the special character meaning is replaced
652 by the timeout meaning.
653 For an explanation of
657 see the description of
658 noncanonical mode below.
659 .SS Retrieving and changing terminal settings
661 gets the parameters associated with the object referred by \fIfd\fP and
662 stores them in the \fItermios\fP structure referenced by
664 This function may be invoked from a background process;
665 however, the terminal attributes may be subsequently changed by a
669 sets the parameters associated with the terminal (unless support is
670 required from the underlying hardware that is not available) from the
671 \fItermios\fP structure referred to by \fItermios_p\fP.
672 \fIoptional_actions\fP specifies when the changes take effect:
675 the change occurs immediately.
678 the change occurs after all output written to
680 has been transmitted.
681 This option should be used when changing
682 parameters that affect output.
685 the change occurs after all output written to the object referred by
687 has been transmitted, and all input that has been received but not read
688 will be discarded before the change is made.
689 .SS Canonical and noncanonical mode
694 determines whether the terminal is operating in canonical mode
706 Input is made available line by line.
707 An input line is available when one of the line delimiters
708 is typed (NL, EOL, EOL2; or EOF at the start of line).
709 Except in the case of EOF, the line delimiter is included
710 in the buffer returned by
713 Line editing is enabled (ERASE, KILL;
716 flag is set: WERASE, REPRINT, LNEXT).
719 returns at most one line of input; if the
721 requested fewer bytes than are available in the current line of input,
722 then only as many bytes as requested are read,
723 and the remaining characters will be available for a future
726 The maximum line length is 4096 chars
727 (including the terminating newline character);
728 lines longer than 4096 chars are truncated.
729 After 4095 characters, input processing (e.g.,
733 processing) continues, but any input data after 4095 characters up to
734 (but not including) any terminating newline is discarded.
735 This ensures that the terminal can always receive
736 more input until at least one line can be read.
738 In noncanonical mode input is available immediately (without
739 the user having to type a line-delimiter character),
740 no input processing is performed,
741 and line editing is disabled.
742 The read buffer will only accept 4095 chars; this provides the
743 necessary space for a newline char if the input mode is switched
749 determine the circumstances in which a
751 completes; there are four distinct cases:
753 MIN == 0, TIME == 0 (polling read)
754 If data is available,
756 returns immediately, with the lesser of the number of bytes
757 available, or the number of bytes requested.
758 If no data is available,
762 MIN > 0, TIME == 0 (blocking read)
764 blocks until MIN bytes are available,
765 and returns up to the number of bytes requested.
767 MIN == 0, TIME > 0 (read with timeout)
768 TIME specifies the limit for a timer in tenths of a second.
769 The timer is started when
773 returns either when at least one byte of data is available,
774 or when the timer expires.
775 If the timer expires without any input becoming available,
778 If data is already available at the time of the call to
780 the call behaves as though the data was received immediately after the call.
782 MIN > 0, TIME > 0 (read with interbyte timeout)
783 TIME specifies the limit for a timer in tenths of a second.
784 Once an initial byte of input becomes available,
785 the timer is restarted after each further byte is received.
787 returns when any of the following conditions is met:
790 MIN bytes have been received.
792 The interbyte timer expires.
794 The number of bytes requested by
797 (POSIX does not specify this termination condition,
798 and on some other implementations
801 does not return in this case.)
804 Because the timer is started only after the initial byte
805 becomes available, at least one byte will be read.
806 If data is already available at the time of the call to
808 the call behaves as though the data was received immediately after the call.
811 .\" POSIX.1-2008 XBD 11.1.7
812 does not specify whether the setting of the
814 file status flag takes precedence over the MIN and TIME settings.
819 in noncanonical mode may return immediately,
820 regardless of the setting of MIN or TIME.
821 Furthermore, if no data is available,
824 in noncanonical mode to return either 0, or \-1 with
830 sets the terminal to something like the
831 "raw" mode of the old Version 7 terminal driver:
832 input is available character by character,
833 echoing is disabled, and all special processing of
834 terminal input and output characters is disabled.
835 The terminal attributes are set as follows:
839 termios_p\->c_iflag &= \(ti(IGNBRK | BRKINT | PARMRK | ISTRIP
840 | INLCR | IGNCR | ICRNL | IXON);
841 termios_p\->c_oflag &= \(tiOPOST;
842 termios_p\->c_lflag &= \(ti(ECHO | ECHONL | ICANON | ISIG | IEXTEN);
843 termios_p\->c_cflag &= \(ti(CSIZE | PARENB);
844 termios_p\->c_cflag |= CS8;
850 transmits a continuous stream of zero-valued bits for a specific
851 duration, if the terminal is using asynchronous serial data
853 If \fIduration\fP is zero, it transmits zero-valued bits
854 for at least 0.25 seconds, and not more than 0.5 seconds.
855 If \fIduration\fP is not zero, it sends zero-valued bits for some
856 implementation-defined length of time.
858 If the terminal is not using asynchronous serial data transmission,
860 returns without taking any action.
863 waits until all output written to the object referred to by
865 has been transmitted.
868 discards data written to the object referred to by
870 but not transmitted, or data received but not read, depending on the
875 flushes data received but not read.
878 flushes data written but not transmitted.
881 flushes both data received but not read, and data written but not
885 suspends transmission or reception of data on the object referred to by
887 depending on the value of
894 restarts suspended output.
897 transmits a STOP character, which stops the terminal device from
898 transmitting data to the system.
901 transmits a START character, which starts the terminal device
902 transmitting data to the system.
904 The default on open of a terminal file is that neither its input nor its
907 The baud rate functions are provided for getting and setting the values
908 of the input and output baud rates in the \fItermios\fP structure.
909 The new values do not take effect
912 is successfully called.
914 Setting the speed to \fBB0\fP instructs the modem to "hang up".
915 The actual bit rate corresponding to \fBB38400\fP may be altered with
918 The input and output baud rates are stored in the \fItermios\fP
922 returns the output baud rate stored in the \fItermios\fP structure
927 sets the output baud rate stored in the \fItermios\fP structure pointed
928 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
986 These constants are additionally supported on the SPARC architecture:
998 These constants are additionally supported on non-SPARC architectures:
1010 Due to differences between architectures, portable applications should check
1013 constant is defined prior to using it.
1017 is used to terminate the connection.
1020 is specified, the modem control lines shall no longer be asserted.
1021 Normally, this will disconnect the line.
1024 for the speeds beyond those defined in POSIX.1 (57600 and above).
1026 .BR B57600 " & " CBAUDEX
1029 Setting the baud rate to a value other than those defined by
1031 constants is possible via the
1037 returns the input baud rate stored in the
1042 sets the input baud rate stored in the
1046 which must be specified as one of the
1048 constants listed above for
1050 If the input baud rate is set to the literal constant
1052 (not the symbolic constant
1054 the input baud rate will be
1055 equal to the output baud rate.
1058 is a 4.4BSD extension.
1059 It takes the same arguments as
1061 and sets both input and output speed.
1064 returns the input baud rate stored in the
1069 returns the output baud rate stored in the \fItermios\fP structure.
1071 All other functions return:
1079 to indicate the error.
1083 returns success if \fIany\fP of the requested changes could be
1084 successfully carried out.
1085 Therefore, when making multiple changes
1086 it may be necessary to follow this call with a further call to
1088 to check that all changes have been performed successfully.
1090 For an explanation of the terms used in this section, see
1099 Interface Attribute Value
1113 T} Thread safety MT-Safe
1118 .\" FIXME: The markings are different from that in the glibc manual.
1119 .\" markings in glibc manual are more detailed:
1121 .\" tcsendbreak: MT-Unsafe race:tcattr(filedes)/bsd
1122 .\" tcflow: MT-Unsafe race:tcattr(filedes)/bsd
1124 .\" glibc manual says /bsd indicate the preceding marker only applies
1125 .\" when the underlying kernel is a BSD kernel.
1126 .\" So, it is safety in Linux kernel.
1140 are specified in POSIX.1-2001.
1145 are nonstandard, but available on the BSDs.
1147 UNIX\ V7 and several later systems have a list of baud rates
1148 where after the values
1152 one finds the two constants
1155 ("External A" and "External B").
1156 Many systems extend the list with much higher baud rates.
1158 The effect of a nonzero \fIduration\fP with
1161 SunOS specifies a break of
1163 seconds, where \fIN\fP is at least 0.25, and not more than 0.5.
1164 Linux, AIX, DU, Tru64 send a break of
1167 FreeBSD and NetBSD and HP-UX and MacOS ignore the value of
1169 Under Solaris and UnixWare,
1175 .\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0.
1176 .\" libc4.7.6, libc5, glibc for unix: duration in ms.
1177 .\" glibc for bsd: duration in us
1178 .\" glibc for sunos4: ignore duration
1180 .\" kernel 77e5bff1640432f28794a00800955e646dcd7455
1181 .\" glibc 573963e32ffac46d9891970ddebde2ac3212c5c0
1182 On the Alpha architecture before Linux 4.16 (and glibc before glibc 2.28), the
1184 value was different from
1186 and it was ignored by the
1188 line discipline code of the terminal driver as a result
1189 (because as it wasn't part of the
1199 .BR ioctl_console (2),
1202 .BR speed_t (3type),
1203 .BR tcflag_t (3type),
projects / thirdparty / man-pages.git / blob