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]; /* control chars */
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 only exposed 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 non-current 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, ASCII control signals other
236 than TAB, NL, START, and STOP are echoed as ^X, where X is the
237 character with ASCII code 0x40 greater than the control signal.
238 For example, character 0x08 (BS) is echoed as ^H. [requires
239 _BSD_SOURCE or _SVID_SOURCE]
240 ECHOPRT
242 (not in POSIX) If ICANON and IECHO 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 the
259 SIGINT, SIGQUIT, and SIGSUSP signals.
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 special control characters. The symbolic
275 indices (initial values) and meaning are:
276 VINTR (003, ETX, Ctrl-C, or also 0177, DEL, rubout) Interrupt charac‐
278 ter. Send a SIGINT signal. Recognized when ISIG is set, and
279 then not passed as input.
280 VQUIT (034, FS, Ctrl-\) Quit character. Send SIGQUIT signal. Recog‐
282 nized when ISIG is set, and then not passed as input.
283 VERASE (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) Erase charac‐
285 ter. This erases the previous not-yet-erased character, but
286 does not erase past EOF or beginning-of-line. Recognized when
287 ICANON is set, and then not passed as input.
288 VKILL (025, NAK, Ctrl-U, or Ctrl-X, or also @) Kill character. This
290 erases the input since the last EOF or beginning-of-line. Rec‐
291 ognized when ICANON is set, and then not passed as input.
292 VEOF (004, EOT, Ctrl-D) End-of-file character. More precisely: this
294 character causes the pending tty buffer to be sent to the wait‐
295 ing user program without waiting for end-of-line. If it is the
296 first character of the line, the read(2) in the user program
297 returns 0, which signifies end-of-file. Recognized when ICANON
298 is set, and then not passed as input.
299 VMIN Minimum number of characters for non-canonical read.
301 VEOL (0, NUL) Additional end-of-line character. Recognized when
303 ICANON is set.
304 VTIME Timeout in deciseconds for non-canonical read.
306 VEOL2 (not in POSIX; 0, NUL) Yet another end-of-line character. Rec‐
308 ognized when ICANON is set.
309 VSWTCH (not in POSIX; not supported under Linux; 0, NUL) Switch charac‐
311 ter. (Used by shl only.)
312 VSTART (021, DC1, Ctrl-Q) Start character. Restarts output stopped by
314 the Stop character. Recognized when IXON is set, and then not
315 passed as input.
316 VSTOP (023, DC3, Ctrl-S) Stop character. Stop output until Start
318 character typed. Recognized when IXON is set, and then not
319 passed as input.
320 VSUSP (032, SUB, Ctrl-Z) Suspend character. Send SIGTSTP signal.
322 Recognized when ISIG is set, and then not passed as input.
323 VDSUSP (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y)
325 Delayed suspend character: send SIGTSTP signal when the charac‐
326 ter is read by the user program. Recognized when IEXTEN and
327 ISIG are set, and the system supports job control, and then not
328 passed as input.
329 VLNEXT (not in POSIX; 026, SYN, Ctrl-V) Literal next. Quotes the next
331 input character, depriving it of a possible special meaning.
332 Recognized when IEXTEN is set, and then not passed as input.
333 VWERASE
335 (not in POSIX; 027, ETB, Ctrl-W) Word erase. Recognized when
336 ICANON and IEXTEN are set, and then not passed as input.
337 VREPRINT
339 (not in POSIX; 022, DC2, Ctrl-R) Reprint unread characters.
340 Recognized when ICANON and IEXTEN are set, and then not passed
341 as input.
342 VDISCARD
344 (not in POSIX; not supported under Linux; 017, SI, Ctrl-O) Tog‐
345 gle: start/stop discarding pending output. Recognized when IEX‐
346 TEN is set, and then not passed as input.
347 VSTATUS
349 (not in POSIX; not supported under Linux; status request: 024,
350 DC4, Ctrl-T).
351 These symbolic subscript values are all different, except that VTIME,
353 VMIN may have the same value as VEOL, VEOF, respectively. In non-
354 canonical mode the special character meaning is replaced by the timeout
355 meaning. For an explanation of VMIN and VTIME, see the description of
356 non-canonical mode below.
357 Retrieving and changing terminal settings
359 tcgetattr() gets the parameters associated with the object referred by
360 fd and stores them in the termios structure referenced by termios_p.
361 This function may be invoked from a background process; however, the
362 terminal attributes may be subsequently changed by a foreground
363 process.
364 tcsetattr() sets the parameters associated with the terminal (unless
366 support is required from the underlying hardware that is not available)
367 from the termios structure referred to by termios_p. optional_actions
368 specifies when the changes take effect:
369 TCSANOW
371 the change occurs immediately.
372 TCSADRAIN
374 the change occurs after all output written to fd has been trans‐
375 mitted. This function should be used when changing parameters
376 that affect output.
377 TCSAFLUSH
379 the change occurs after all output written to the object
380 referred by fd has been transmitted, and all input that has been
381 received but not read will be discarded before the change is
382 made.
383 Canonical and non-canonical mode
385 The setting of the ICANON canon flag in c_lflag determines whether the
386 terminal is operating in canonical mode (ICANON set) or non-canonical
387 mode (ICANON unset). By default, ICANON set.
388 In canonical mode:
390 * Input is made available line by line. An input line is available
392 when one of the line delimiters is typed (NL, EOL, EOL2; or EOF at
393 the start of line). Except in the case of EOF, the line delimiter is
394 included in the buffer returned by read(2).
395 * Line editing is enabled (ERASE, KILL; and if the IEXTEN flag is set:
397 WERASE, REPRINT, LNEXT). A read(2) returns at most one line of
398 input; if the read(2) requested fewer bytes than are available in the
399 current line of input, then only as many bytes as requested are read,
400 and the remaining characters will be available for a future read(2).
401 In non-canonical mode input is available immediately (without the user
403 having to type a line-delimiter character), and line editing is dis‐
404 abled. The settings of MIN (c_cc[VMIN]) and TIME (c_cc[VTIME]) deter‐
405 mine the circumstances in which a read(2) completes; there are four
406 distinct cases:
407 * MIN == 0; TIME == 0: If data is available, read(2) returns immedi‐
409 ately, with the lesser of the number of bytes available, or the num‐
410 ber of bytes requested. If no data is available, read(2) returns 0.
411 * MIN > 0; TIME == 0: read(2) blocks until the lesser of MIN bytes or
413 the number of bytes requested are available, and returns the lesser
414 of these two values.
415 * MIN == 0; TIME > 0: TIME specifies the limit for a timer in tenths of
417 a second. The timer is started when read(2) is called. read(2)
418 returns either when at least one byte of data is available, or when
419 the timer expires. If the timer expires without any input becoming
420 available, read(2) returns 0.
421 * MIN > 0; TIME > 0: TIME specifies the limit for a timer in tenths of
423 a second. Once an initial byte of input becomes available, the timer
424 is restarted after each further byte is received. read(2) returns
425 either when the lesser of the number of bytes requested or MIN byte
426 have been read, or when the inter-byte timeout expires. Because the
427 timer is only started after the initial byte becomes available, at
428 least one byte will be read.
429 Raw mode
431 cfmakeraw() sets the terminal to something like the "raw" mode of the
432 old Version 7 terminal driver: input is available character by charac‐
433 ter, echoing is disabled, and all special processing of terminal input
434 and output characters is disabled. The terminal attributes are set as
435 follows:
436 termios_p->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP
438 | INLCR | IGNCR | ICRNL | IXON);
439 termios_p->c_oflag &= ~OPOST;
440 termios_p->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN);
441 termios_p->c_cflag &= ~(CSIZE | PARENB);
442 termios_p->c_cflag |= CS8;
443 Line control
445 tcsendbreak() transmits a continuous stream of zero-valued bits for a
446 specific duration, if the terminal is using asynchronous serial data
447 transmission. If duration is zero, it transmits zero-valued bits for
448 at least 0.25 seconds, and not more that 0.5 seconds. If duration is
449 not zero, it sends zero-valued bits for some implementation-defined
450 length of time.
451 If the terminal is not using asynchronous serial data transmission,
453 tcsendbreak() returns without taking any action.
454 tcdrain() waits until all output written to the object referred to by
456 fd has been transmitted.
457 tcflush() discards data written to the object referred to by fd but not
459 transmitted, or data received but not read, depending on the value of
460 queue_selector:
461 TCIFLUSH
463 flushes data received but not read.
464 TCOFLUSH
466 flushes data written but not transmitted.
467 TCIOFLUSH
469 flushes both data received but not read, and data written but
470 not transmitted.
471 tcflow() suspends transmission or reception of data on the object
473 referred to by fd, depending on the value of action:
474 TCOOFF suspends output.
476 TCOON restarts suspended output.
478 TCIOFF transmits a STOP character, which stops the terminal device from
480 transmitting data to the system.
481 TCION transmits a START character, which starts the terminal device
483 transmitting data to the system.
484 The default on open of a terminal file is that neither its input nor
486 its output is suspended.
487 Line speed
489 The baud rate functions are provided for getting and setting the values
490 of the input and output baud rates in the termios structure. The new
491 values do not take effect until tcsetattr() is successfully called.
492 Setting the speed to B0 instructs the modem to "hang up". The actual
494 bit rate corresponding to B38400 may be altered with setserial(8).
495 The input and output baud rates are stored in the termios structure.
497 cfgetospeed() returns the output baud rate stored in the termios struc‐
499 ture pointed to by termios_p.
500 cfsetospeed() sets the output baud rate stored in the termios structure
502 pointed to by termios_p to speed, which must be one of these constants:
503 B0
505 B50
506 B75
507 B110
508 B134
509 B150
510 B200
511 B300
512 B600
513 B1200
514 B1800
515 B2400
516 B4800
517 B9600
518 B19200
519 B38400
520 B57600
521 B115200
522 B230400
523 The zero baud rate, B0, is used to terminate the connection. If B0 is
525 specified, the modem control lines shall no longer be asserted. Nor‐
526 mally, this will disconnect the line. CBAUDEX is a mask for the speeds
527 beyond those defined in POSIX.1 (57600 and above). Thus, B57600 &
528 CBAUDEX is non-zero.
529 cfgetispeed() returns the input baud rate stored in the termios struc‐
531 ture.
532 cfsetispeed() sets the input baud rate stored in the termios structure
534 to speed, which must be specified as one of the Bnnn constants listed
535 above for cfsetospeed(). If the input baud rate is set to zero, the
536 input baud rate will be equal to the output baud rate.
537 cfsetspeed() is a 4.4BSD extension. It takes the same arguments as
539 cfsetispeed(), and sets both input and output speed.
540
542 cfgetispeed() returns the input baud rate stored in the termios struc‐
543 ture.
544 cfgetospeed() returns the output baud rate stored in the termios struc‐
546 ture.
547 All other functions return:
549 0 on success.
551 -1 on failure and set errno to indicate the error.
553 Note that tcsetattr() returns success if any of the requested changes
555 could be successfully carried out. Therefore, when making multiple
556 changes it may be necessary to follow this call with a further call to
557 tcgetattr() to check that all changes have been performed successfully.
558
560 tcgetattr(), tcsetattr(), tcsendbreak(), tcdrain(), tcflush(),
561 tcflow(), cfgetispeed(), cfgetospeed(), cfsetispeed(), and cfse‐
562 tospeed() are specified in POSIX.1-2001.
563 cfmakeraw() and cfsetspeed() are non-standard, but available on the
565 BSDs.
566
568 Unix V7 and several later systems have a list of baud rates where after
569 the fourteen values B0, ..., B9600 one finds the two constants EXTA,
570 EXTB ("External A" and "External B"). Many systems extend the list
571 with much higher baud rates.
572 The effect of a non-zero duration with tcsendbreak() varies. SunOS
574 specifies a break of duration * N seconds, where N is at least 0.25,
575 and not more than 0.5. Linux, AIX, DU, Tru64 send a break of duration
576 milliseconds. FreeBSD and NetBSD and HP-UX and MacOS ignore the value
577 of duration. Under Solaris and Unixware, tcsendbreak() with non-zero
578 duration behaves like tcdrain().
579
581 stty(1), console_ioctl(4), tty_ioctl(4), setserial(8)
582
584 This page is part of release 3.22 of the Linux man-pages project. A
585 description of the project, and information about reporting bugs, can
586 be found at http://www.kernel.org/doc/man-pages/.
587Linux 2007-11-26 TERMIOS(3)