1TERMIOS(3) Linux Programmer's Manual TERMIOS(3)
2
6 termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow,
7 cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfset‐
8 speed - get and set terminal attributes, line control, get and set baud
9 rate
10
12 #include <termios.h>
13 #include <unistd.h>
14 int tcgetattr(int fd, struct termios *termios_p);
16 int tcsetattr(int fd, int optional_actions,
18 const struct termios *termios_p);
19 int tcsendbreak(int fd, int duration);
21 int tcdrain(int fd);
23 int tcflush(int fd, int queue_selector);
25 int tcflow(int fd, int action);
27 void cfmakeraw(struct termios *termios_p);
29 speed_t cfgetispeed(const struct termios *termios_p);
31 speed_t cfgetospeed(const struct termios *termios_p);
33 int cfsetispeed(struct termios *termios_p, speed_t speed);
35 int cfsetospeed(struct termios *termios_p, speed_t speed);
37 int cfsetspeed(struct termios *termios_p, speed_t speed);
39 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
41 cfsetspeed(), cfmakeraw(): _BSD_SOURCE
43
45 The termios functions describe a general terminal interface that is
46 provided to control asynchronous communications ports.
47 The termios structure
49 Many of the functions described here have a termios_p argument that is
50 a pointer to a termios structure. This structure contains at least the
51 following members:
52 tcflag_t c_iflag; /* input modes */
54 tcflag_t c_oflag; /* output modes */
55 tcflag_t c_cflag; /* control modes */
56 tcflag_t c_lflag; /* local modes */
57 cc_t c_cc[NCCS]; /* special characters */
58 The values that may be assigned to these fields are described below.
60 In the case of the first four bit-mask fields, the definitions of some
61 of the associated flags that may be set are exposed only if a specific
62 feature test macro (see feature_test_macros(7)) is defined, as noted in
63 brackets ("[]").
64 In the descriptions below, "not in POSIX" means that the value is not
66 specified in POSIX.1-2001, and "XSI" means that the value is specified
67 in POSIX.1-2001 as part of the XSI extension.
68 c_iflag flag constants:
70 IGNBRK Ignore BREAK condition on input.
72 BRKINT If IGNBRK is set, a BREAK is ignored. If it is not set but
74 BRKINT is set, then a BREAK causes the input and output queues
75 to be flushed, and if the terminal is the controlling terminal
76 of a foreground process group, it will cause a SIGINT to be sent
77 to this foreground process group. When neither IGNBRK nor
78 BRKINT are set, a BREAK reads as a null byte ('\0'), except when
79 PARMRK is set, in which case it reads as the sequence \377 \0
80 \0.
81 IGNPAR Ignore framing errors and parity errors.
83 PARMRK If IGNPAR is not set, prefix a character with a parity error or
85 framing error with \377 \0. If neither IGNPAR nor PARMRK is
86 set, read a character with a parity error or framing error as
87 \0.
88 INPCK Enable input parity checking.
90 ISTRIP Strip off eighth bit.
92 INLCR Translate NL to CR on input.
94 IGNCR Ignore carriage return on input.
96 ICRNL Translate carriage return to newline on input (unless IGNCR is
98 set).
99 IUCLC (not in POSIX) Map uppercase characters to lowercase on input.
101 IXON Enable XON/XOFF flow control on output.
103 IXANY (XSI) Typing any character will restart stopped output. (The
105 default is to allow just the START character to restart output.)
106 IXOFF Enable XON/XOFF flow control on input.
108 IMAXBEL
110 (not in POSIX) Ring bell when input queue is full. Linux does
111 not implement this bit, and acts as if it is always set.
112 IUTF8 (since Linux 2.6.4)
114 (not in POSIX) Input is UTF8; this allows character-erase to be
115 correctly performed in cooked mode.
116 c_oflag flag constants defined in POSIX.1:
118 OPOST Enable implementation-defined output processing.
120 The remaining c_oflag flag constants are defined in POSIX.1-2001,
122 unless marked otherwise.
123 OLCUC (not in POSIX) Map lowercase characters to uppercase on output.
125 ONLCR (XSI) Map NL to CR-NL on output.
127 OCRNL Map CR to NL on output.
129 ONOCR Don't output CR at column 0.
131 ONLRET Don't output CR.
133 OFILL Send fill characters for a delay, rather than using a timed
135 delay.
136 OFDEL (not in POSIX) Fill character is ASCII DEL (0177). If unset,
138 fill character is ASCII NUL ('\0'). (Not implemented on Linux.)
139 NLDLY Newline delay mask. Values are NL0 and NL1. [requires
141 _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
142 CRDLY Carriage return delay mask. Values are CR0, CR1, CR2, or CR3.
144 [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
145 TABDLY Horizontal tab delay mask. Values are TAB0, TAB1, TAB2, TAB3
147 (or XTABS). A value of TAB3, that is, XTABS, expands tabs to
148 spaces (with tab stops every eight columns). [requires
149 _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
150 BSDLY Backspace delay mask. Values are BS0 or BS1. (Has never been
152 implemented.) [requires _BSD_SOURCE or _SVID_SOURCE or
153 _XOPEN_SOURCE]
154 VTDLY Vertical tab delay mask. Values are VT0 or VT1.
156 FFDLY Form feed delay mask. Values are FF0 or FF1. [requires
158 _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
159 c_cflag flag constants:
161 CBAUD (not in POSIX) Baud speed mask (4+1 bits). [requires
163 _BSD_SOURCE or _SVID_SOURCE]
164 CBAUDEX
166 (not in POSIX) Extra baud speed mask (1 bit), included in CBAUD.
167 [requires _BSD_SOURCE or _SVID_SOURCE]
168 (POSIX says that the baud speed is stored in the termios struc‐
170 ture without specifying where precisely, and provides
171 cfgetispeed() and cfsetispeed() for getting at it. Some systems
172 use bits selected by CBAUD in c_cflag, other systems use sepa‐
173 rate fields, for example, sg_ispeed and sg_ospeed.)
174 CSIZE Character size mask. Values are CS5, CS6, CS7, or CS8.
176 CSTOPB Set two stop bits, rather than one.
178 CREAD Enable receiver.
180 PARENB Enable parity generation on output and parity checking for
182 input.
183 PARODD If set, then parity for input and output is odd; otherwise even
185 parity is used.
186 HUPCL Lower modem control lines after last process closes the device
188 (hang up).
189 CLOCAL Ignore modem control lines.
191 LOBLK (not in POSIX) Block output from a noncurrent shell layer. For
193 use by shl (shell layers). (Not implemented on Linux.)
194 CIBAUD (not in POSIX) Mask for input speeds. The values for the CIBAUD
196 bits are the same as the values for the CBAUD bits, shifted left
197 IBSHIFT bits. [requires _BSD_SOURCE or _SVID_SOURCE] (Not
198 implemented on Linux.)
199 CMSPAR (not in POSIX) Use "stick" (mark/space) parity (supported on
201 certain serial devices): if PARODD is set, the parity bit is
202 always 1; if PARODD is not set, then the parity bit is always
203 0). [requires _BSD_SOURCE or _SVID_SOURCE]
204 CRTSCTS
206 (not in POSIX) Enable RTS/CTS (hardware) flow control.
207 [requires _BSD_SOURCE or _SVID_SOURCE]
208 c_lflag flag constants:
210 ISIG When any of the characters INTR, QUIT, SUSP, or DSUSP are
212 received, generate the corresponding signal.
213 ICANON Enable canonical mode (described below).
215 XCASE (not in POSIX; not supported under Linux) If ICANON is also set,
217 terminal is uppercase only. Input is converted to lowercase,
218 except for characters preceded by \. On output, uppercase char‐
219 acters are preceded by \ and lowercase characters are converted
220 to uppercase. [requires _BSD_SOURCE or _SVID_SOURCE or
221 _XOPEN_SOURCE]
222 ECHO Echo input characters.
224 ECHOE If ICANON is also set, the ERASE character erases the preceding
226 input character, and WERASE erases the preceding word.
227 ECHOK If ICANON is also set, the KILL character erases the current
229 line.
230 ECHONL If ICANON is also set, echo the NL character even if ECHO is not
232 set.
233 ECHOCTL
235 (not in POSIX) If ECHO is also set, terminal special characters
236 other than TAB, NL, START, and STOP are echoed as ^X, where X is
237 the character with ASCII code 0x40 greater than the special
238 character. For example, character 0x08 (BS) is echoed as ^H.
239 [requires _BSD_SOURCE or _SVID_SOURCE]
240 ECHOPRT
242 (not in POSIX) If ICANON and ECHO are also set, characters are
243 printed as they are being erased. [requires _BSD_SOURCE or
244 _SVID_SOURCE]
245 ECHOKE (not in POSIX) If ICANON is also set, KILL is echoed by erasing
247 each character on the line, as specified by ECHOE and ECHOPRT.
248 [requires _BSD_SOURCE or _SVID_SOURCE]
249 DEFECHO
251 (not in POSIX) Echo only when a process is reading. (Not imple‐
252 mented on Linux.)
253 FLUSHO (not in POSIX; not supported under Linux) Output is being
255 flushed. This flag is toggled by typing the DISCARD character.
256 [requires _BSD_SOURCE or _SVID_SOURCE]
257 NOFLSH Disable flushing the input and output queues when generating
259 signals for the INT, QUIT, and SUSP characters.
260 TOSTOP Send the SIGTTOU signal to the process group of a background
262 process which tries to write to its controlling terminal.
263 PENDIN (not in POSIX; not supported under Linux) All characters in the
265 input queue are reprinted when the next character is read.
266 (bash(1) handles typeahead this way.) [requires _BSD_SOURCE or
267 _SVID_SOURCE]
268 IEXTEN Enable implementation-defined input processing. This flag, as
270 well as ICANON must be enabled for the special characters EOL2,
271 LNEXT, REPRINT, WERASE to be interpreted, and for the IUCLC flag
272 to be effective.
273 The c_cc array defines the terminal special characters. The symbolic
275 indices (initial values) and meaning are:
276 VDISCARD
278 (not in POSIX; not supported under Linux; 017, SI, Ctrl-O) Tog‐
279 gle: start/stop discarding pending output. Recognized when IEX‐
280 TEN is set, and then not passed as input.
281 VDSUSP (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y)
283 Delayed suspend character (DSUSP): send SIGTSTP signal when the
284 character is read by the user program. Recognized when IEXTEN
285 and ISIG are set, and the system supports job control, and then
286 not passed as input.
287 VEOF (004, EOT, Ctrl-D) End-of-file character (EOF). More precisely:
289 this character causes the pending tty buffer to be sent to the
290 waiting user program without waiting for end-of-line. If it is
291 the first character of the line, the read(2) in the user program
292 returns 0, which signifies end-of-file. Recognized when ICANON
293 is set, and then not passed as input.
294 VEOL (0, NUL) Additional end-of-line character (EOL). Recognized
296 when ICANON is set.
297 VEOL2 (not in POSIX; 0, NUL) Yet another end-of-line character (EOL2).
299 Recognized when ICANON is set.
300 VERASE (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) Erase charac‐
302 ter (ERASE). This erases the previous not-yet-erased character,
303 but does not erase past EOF or beginning-of-line. Recognized
304 when ICANON is set, and then not passed as input.
305 VINTR (003, ETX, Ctrl-C, or also 0177, DEL, rubout) Interrupt charac‐
307 ter (INTR). Send a SIGINT signal. Recognized when ISIG is set,
308 and then not passed as input.
309 VKILL (025, NAK, Ctrl-U, or Ctrl-X, or also @) Kill character (KILL).
311 This erases the input since the last EOF or beginning-of-line.
312 Recognized when ICANON is set, and then not passed as input.
313 VLNEXT (not in POSIX; 026, SYN, Ctrl-V) Literal next (LNEXT). Quotes
315 the next input character, depriving it of a possible special
316 meaning. Recognized when IEXTEN is set, and then not passed as
317 input.
318 VMIN Minimum number of characters for noncanonical read (MIN).
320 VQUIT (034, FS, Ctrl-\) Quit character (QUIT). Send SIGQUIT signal.
322 Recognized when ISIG is set, and then not passed as input.
323 VREPRINT
325 (not in POSIX; 022, DC2, Ctrl-R) Reprint unread characters (RE‐
326 PRINT). Recognized when ICANON and IEXTEN are set, and then not
327 passed as input.
328 VSTART (021, DC1, Ctrl-Q) Start character (START). Restarts output
330 stopped by the Stop character. Recognized when IXON is set, and
331 then not passed as input.
332 VSTATUS
334 (not in POSIX; not supported under Linux; status request: 024,
335 DC4, Ctrl-T). Status character (STATUS). Display status infor‐
336 mation at terminal, including state of foreground process and
337 amount of CPU time it has consumed. Also sends a SIGINFO signal
338 (not supported on Linux) to the foreground process group.
339 VSTOP (023, DC3, Ctrl-S) Stop character (STOP). Stop output until
341 Start character typed. Recognized when IXON is set, and then
342 not passed as input.
343 VSUSP (032, SUB, Ctrl-Z) Suspend character (SUSP). Send SIGTSTP sig‐
345 nal. Recognized when ISIG is set, and then not passed as input.
346 VSWTCH (not in POSIX; not supported under Linux; 0, NUL) Switch charac‐
348 ter (SWTCH). Used in System V to switch shells in shell layers,
349 a predecessor to shell job control.
350 VTIME Timeout in deciseconds for noncanonical read (TIME).
352 VWERASE
354 (not in POSIX; 027, ETB, Ctrl-W) Word erase (WERASE). Recog‐
355 nized when ICANON and IEXTEN are set, and then not passed as
356 input.
357 An individual terminal special character can be disabled by setting the
359 value of the corresponding c_cc element to _POSIX_VDISABLE.
360 The above symbolic subscript values are all different, except that
362 VTIME, VMIN may have the same value as VEOL, VEOF, respectively. In
363 noncanonical mode the special character meaning is replaced by the
364 timeout meaning. For an explanation of VMIN and VTIME, see the
365 description of noncanonical mode below.
366 Retrieving and changing terminal settings
368 tcgetattr() gets the parameters associated with the object referred by
369 fd and stores them in the termios structure referenced by termios_p.
370 This function may be invoked from a background process; however, the
371 terminal attributes may be subsequently changed by a foreground
372 process.
373 tcsetattr() sets the parameters associated with the terminal (unless
375 support is required from the underlying hardware that is not available)
376 from the termios structure referred to by termios_p. optional_actions
377 specifies when the changes take effect:
378 TCSANOW
380 the change occurs immediately.
381 TCSADRAIN
383 the change occurs after all output written to fd has been trans‐
384 mitted. This function should be used when changing parameters
385 that affect output.
386 TCSAFLUSH
388 the change occurs after all output written to the object
389 referred by fd has been transmitted, and all input that has been
390 received but not read will be discarded before the change is
391 made.
392 Canonical and noncanonical mode
394 The setting of the ICANON canon flag in c_lflag determines whether the
395 terminal is operating in canonical mode (ICANON set) or noncanonical
396 mode (ICANON unset). By default, ICANON set.
397 In canonical mode:
399 * Input is made available line by line. An input line is available
401 when one of the line delimiters is typed (NL, EOL, EOL2; or EOF at
402 the start of line). Except in the case of EOF, the line delimiter is
403 included in the buffer returned by read(2).
404 * Line editing is enabled (ERASE, KILL; and if the IEXTEN flag is set:
406 WERASE, REPRINT, LNEXT). A read(2) returns at most one line of
407 input; if the read(2) requested fewer bytes than are available in the
408 current line of input, then only as many bytes as requested are read,
409 and the remaining characters will be available for a future read(2).
410 In noncanonical mode input is available immediately (without the user
412 having to type a line-delimiter character), no input processing is per‐
413 formed, and line editing is disabled. The settings of MIN (c_cc[VMIN])
414 and TIME (c_cc[VTIME]) determine the circumstances in which a read(2)
415 completes; there are four distinct cases:
416 * MIN == 0; TIME == 0: If data is available, read(2) returns immedi‐
418 ately, with the lesser of the number of bytes available, or the num‐
419 ber of bytes requested. If no data is available, read(2) returns 0.
420 * MIN > 0; TIME == 0: read(2) blocks until the lesser of MIN bytes or
422 the number of bytes requested are available, and returns the lesser
423 of these two values.
424 * MIN == 0; TIME > 0: TIME specifies the limit for a timer in tenths of
426 a second. The timer is started when read(2) is called. read(2)
427 returns either when at least one byte of data is available, or when
428 the timer expires. If the timer expires without any input becoming
429 available, read(2) returns 0.
430 * MIN > 0; TIME > 0: TIME specifies the limit for a timer in tenths of
432 a second. Once an initial byte of input becomes available, the timer
433 is restarted after each further byte is received. read(2) returns
434 either when the lesser of the number of bytes requested or MIN byte
435 have been read, or when the inter-byte timeout expires. Because the
436 timer is started only after the initial byte becomes available, at
437 least one byte will be read.
438 Raw mode
440 cfmakeraw() sets the terminal to something like the "raw" mode of the
441 old Version 7 terminal driver: input is available character by charac‐
442 ter, echoing is disabled, and all special processing of terminal input
443 and output characters is disabled. The terminal attributes are set as
444 follows:
445 termios_p->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP
447 | INLCR | IGNCR | ICRNL | IXON);
448 termios_p->c_oflag &= ~OPOST;
449 termios_p->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN);
450 termios_p->c_cflag &= ~(CSIZE | PARENB);
451 termios_p->c_cflag |= CS8;
452 Line control
454 tcsendbreak() transmits a continuous stream of zero-valued bits for a
455 specific duration, if the terminal is using asynchronous serial data
456 transmission. If duration is zero, it transmits zero-valued bits for
457 at least 0.25 seconds, and not more that 0.5 seconds. If duration is
458 not zero, it sends zero-valued bits for some implementation-defined
459 length of time.
460 If the terminal is not using asynchronous serial data transmission,
462 tcsendbreak() returns without taking any action.
463 tcdrain() waits until all output written to the object referred to by
465 fd has been transmitted.
466 tcflush() discards data written to the object referred to by fd but not
468 transmitted, or data received but not read, depending on the value of
469 queue_selector:
470 TCIFLUSH
472 flushes data received but not read.
473 TCOFLUSH
475 flushes data written but not transmitted.
476 TCIOFLUSH
478 flushes both data received but not read, and data written but
479 not transmitted.
480 tcflow() suspends transmission or reception of data on the object
482 referred to by fd, depending on the value of action:
483 TCOOFF suspends output.
485 TCOON restarts suspended output.
487 TCIOFF transmits a STOP character, which stops the terminal device from
489 transmitting data to the system.
490 TCION transmits a START character, which starts the terminal device
492 transmitting data to the system.
493 The default on open of a terminal file is that neither its input nor
495 its output is suspended.
496 Line speed
498 The baud rate functions are provided for getting and setting the values
499 of the input and output baud rates in the termios structure. The new
500 values do not take effect until tcsetattr() is successfully called.
501 Setting the speed to B0 instructs the modem to "hang up". The actual
503 bit rate corresponding to B38400 may be altered with setserial(8).
504 The input and output baud rates are stored in the termios structure.
506 cfgetospeed() returns the output baud rate stored in the termios struc‐
508 ture pointed to by termios_p.
509 cfsetospeed() sets the output baud rate stored in the termios structure
511 pointed to by termios_p to speed, which must be one of these constants:
512 B0
514 B50
515 B75
516 B110
517 B134
518 B150
519 B200
520 B300
521 B600
522 B1200
523 B1800
524 B2400
525 B4800
526 B9600
527 B19200
528 B38400
529 B57600
530 B115200
531 B230400
532 The zero baud rate, B0, is used to terminate the connection. If B0 is
534 specified, the modem control lines shall no longer be asserted. Nor‐
535 mally, this will disconnect the line. CBAUDEX is a mask for the speeds
536 beyond those defined in POSIX.1 (57600 and above). Thus, B57600 &
537 CBAUDEX is nonzero.
538 cfgetispeed() returns the input baud rate stored in the termios struc‐
540 ture.
541 cfsetispeed() sets the input baud rate stored in the termios structure
543 to speed, which must be specified as one of the Bnnn constants listed
544 above for cfsetospeed(). If the input baud rate is set to zero, the
545 input baud rate will be equal to the output baud rate.
546 cfsetspeed() is a 4.4BSD extension. It takes the same arguments as
548 cfsetispeed(), and sets both input and output speed.
549
551 cfgetispeed() returns the input baud rate stored in the termios struc‐
552 ture.
553 cfgetospeed() returns the output baud rate stored in the termios struc‐
555 ture.
556 All other functions return:
558 0 on success.
560 -1 on failure and set errno to indicate the error.
562 Note that tcsetattr() returns success if any of the requested changes
564 could be successfully carried out. Therefore, when making multiple
565 changes it may be necessary to follow this call with a further call to
566 tcgetattr() to check that all changes have been performed successfully.
567
569 tcgetattr(), tcsetattr(), tcsendbreak(), tcdrain(), tcflush(),
570 tcflow(), cfgetispeed(), cfgetospeed(), cfsetispeed(), and cfse‐
571 tospeed() are specified in POSIX.1-2001.
572 cfmakeraw() and cfsetspeed() are nonstandard, but available on the
574 BSDs.
575
577 UNIX V7 and several later systems have a list of baud rates where after
578 the fourteen values B0, ..., B9600 one finds the two constants EXTA,
579 EXTB ("External A" and "External B"). Many systems extend the list
580 with much higher baud rates.
581 The effect of a nonzero duration with tcsendbreak() varies. SunOS
583 specifies a break of duration * N seconds, where N is at least 0.25,
584 and not more than 0.5. Linux, AIX, DU, Tru64 send a break of duration
585 milliseconds. FreeBSD and NetBSD and HP-UX and MacOS ignore the value
586 of duration. Under Solaris and UnixWare, tcsendbreak() with nonzero
587 duration behaves like tcdrain().
588
590 stty(1), console_ioctl(4), tty_ioctl(4), setserial(8)
591
593 This page is part of release 3.53 of the Linux man-pages project. A
594 description of the project, and information about reporting bugs, can
595 be found at http://www.kernel.org/doc/man-pages/.
596Linux 2013-03-15 TERMIOS(3)