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, const struct termios
18 *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
39 The termios functions describe a general terminal interface that is
40 provided to control asynchronous communications ports.
41 The termios structure
43 Many of the functions described here have a termios_p argument that is
44 a pointer to a termios structure. This structure contains at least the
45 following members:
46 tcflag_t c_iflag; /* input modes */
48 tcflag_t c_oflag; /* output modes */
49 tcflag_t c_cflag; /* control modes */
50 tcflag_t c_lflag; /* local modes */
51 cc_t c_cc[NCCS]; /* control chars */
52 The values that may be assigned to these fields are described below.
54 In the case of the first four bit-mask fields, the definitions of some
55 of the associated flags that may be set are only exposed if a specific
56 feature test macro (see feature_test_macros(7)) is defined, as noted in
57 brackets ("[]").
58 In the descriptions below, "not in POSIX" means that the value is not
60 specified in POSIX.1-2001, and "XSI" means that the value is specified
61 in POSIX.1-2001 as part of the XSI extension.
62 c_iflag flag constants:
64 IGNBRK Ignore BREAK condition on input.
66 BRKINT If IGNBRK is set, a BREAK is ignored. If it is not set but
68 BRKINT is set, then a BREAK causes the input and output queues
69 to be flushed, and if the terminal is the controlling terminal
70 of a foreground process group, it will cause a SIGINT to be sent
71 to this foreground process group. When neither IGNBRK nor
72 BRKINT are set, a BREAK reads as a null byte ('\0'), except when
73 PARMRK is set, in which case it reads as the sequence \377 \0
74 \0.
75 IGNPAR Ignore framing errors and parity errors.
77 PARMRK If IGNPAR is not set, prefix a character with a parity error or
79 framing error with \377 \0. If neither IGNPAR nor PARMRK is
80 set, read a character with a parity error or framing error as
81 \0.
82 INPCK Enable input parity checking.
84 ISTRIP Strip off eighth bit.
86 INLCR Translate NL to CR on input.
88 IGNCR Ignore carriage return on input.
90 ICRNL Translate carriage return to newline on input (unless IGNCR is
92 set).
93 IUCLC (not in POSIX) Map uppercase characters to lowercase on input.
95 IXON Enable XON/XOFF flow control on output.
97 IXANY (XSI) Typing any character will restart stopped output. (The
99 default is to allow just the START character to restart output.)
100 IXOFF Enable XON/XOFF flow control on input.
102 IMAXBEL
104 (not in POSIX) Ring bell when input queue is full. Linux does
105 not implement this bit, and acts as if it is always set.
106 IUTF8 (since Linux 2.6.4)
108 (not in POSIX) Input is UTF8; this allows character-erase to be
109 correctly performed in cooked mode.
110 c_oflag flag constants defined in POSIX.1:
112 OPOST Enable implementation-defined output processing.
114 The remaining c_oflag flag constants are defined in POSIX.1-2001,
116 unless marked otherwise.
117 OLCUC (not in POSIX) Map lowercase characters to uppercase on output.
119 ONLCR (XSI) Map NL to CR-NL on output.
121 OCRNL Map CR to NL on output.
123 ONOCR Don't output CR at column 0.
125 ONLRET Don't output CR.
127 OFILL Send fill characters for a delay, rather than using a timed
129 delay.
130 OFDEL (not in POSIX) Fill character is ASCII DEL (0177). If unset,
132 fill character is ASCII NUL ('\0'). (Not implemented on Linux.)
133 NLDLY Newline delay mask. Values are NL0 and NL1. [requires
135 _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
136 CRDLY Carriage return delay mask. Values are CR0, CR1, CR2, or CR3.
138 [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
139 TABDLY Horizontal tab delay mask. Values are TAB0, TAB1, TAB2, TAB3
141 (or XTABS). A value of TAB3, that is, XTABS, expands tabs to
142 spaces (with tab stops every eight columns). [requires
143 _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
144 BSDLY Backspace delay mask. Values are BS0 or BS1. (Has never been
146 implemented.) [requires _BSD_SOURCE or _SVID_SOURCE or
147 _XOPEN_SOURCE]
148 VTDLY Vertical tab delay mask. Values are VT0 or VT1.
150 FFDLY Form feed delay mask. Values are FF0 or FF1. [requires
152 _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
153 c_cflag flag constants:
155 CBAUD (not in POSIX) Baud speed mask (4+1 bits). [requires
157 _BSD_SOURCE or _SVID_SOURCE]
158 CBAUDEX
160 (not in POSIX) Extra baud speed mask (1 bit), included in CBAUD.
161 [requires _BSD_SOURCE or _SVID_SOURCE]
162 (POSIX says that the baud speed is stored in the termios struc‐
164 ture without specifying where precisely, and provides
165 cfgetispeed() and cfsetispeed() for getting at it. Some systems
166 use bits selected by CBAUD in c_cflag, other systems use sepa‐
167 rate fields, e.g. sg_ispeed and sg_ospeed.)
168 CSIZE Character size mask. Values are CS5, CS6, CS7, or CS8.
170 CSTOPB Set two stop bits, rather than one.
172 CREAD Enable receiver.
174 PARENB Enable parity generation on output and parity checking for
176 input.
177 PARODD If set, then parity for input and output is odd; otherwise even
179 parity is used.
180 HUPCL Lower modem control lines after last process closes the device
182 (hang up).
183 CLOCAL Ignore modem control lines.
185 LOBLK (not in POSIX) Block output from a noncurrent shell layer. For
187 use by shl (shell layers). (Not implemented on Linux.)
188 CIBAUD (not in POSIX) Mask for input speeds. The values for the CIBAUD
190 bits are the same as the values for the CBAUD bits, shifted left
191 IBSHIFT bits. [requires _BSD_SOURCE or _SVID_SOURCE] (Not
192 implemented on Linux.)
193 CMSPAR (not in POSIX) Use "stick" (mark/space) parity (supported on
195 certain serial devices): if PARODD is set, the parity bit is
196 always 1; if PARODD is not set, then the parity bit is always
197 0). [requires _BSD_SOURCE or _SVID_SOURCE]
198 CRTSCTS
200 (not in POSIX) Enable RTS/CTS (hardware) flow control.
201 [requires _BSD_SOURCE or _SVID_SOURCE]
202 c_lflag flag constants:
204 ISIG When any of the characters INTR, QUIT, SUSP, or DSUSP are
206 received, generate the corresponding signal.
207 ICANON Enable canonical mode (described below).
209 XCASE (not in POSIX; not supported under Linux) If ICANON is also set,
211 terminal is uppercase only. Input is converted to lowercase,
212 except for characters preceded by \. On output, uppercase char‐
213 acters are preceded by \ and lowercase characters are converted
214 to uppercase.
215 ECHO Echo input characters.
217 ECHOE If ICANON is also set, the ERASE character erases the preceding
219 input character, and WERASE erases the preceding word.
220 ECHOK If ICANON is also set, the KILL character erases the current
222 line.
223 ECHONL If ICANON is also set, echo the NL character even if ECHO is not
225 set.
226 ECHOCTL
228 (not in POSIX) If ECHO is also set, ASCII control signals other
229 than TAB, NL, START, and STOP are echoed as ^X, where X is the
230 character with ASCII code 0x40 greater than the control signal.
231 For example, character 0x08 (BS) is echoed as ^H. [requires
232 _BSD_SOURCE or _SVID_SOURCE]
233 ECHOPRT
235 (not in POSIX) If ICANON and IECHO are also set, characters are
236 printed as they are being erased. [requires _BSD_SOURCE or
237 _SVID_SOURCE]
238 ECHOKE (not in POSIX) If ICANON is also set, KILL is echoed by erasing
240 each character on the line, as specified by ECHOE and ECHOPRT.
241 [requires _BSD_SOURCE or _SVID_SOURCE]
242 DEFECHO
244 (not in POSIX) Echo only when a process is reading. (Not imple‐
245 mented on Linux.)
246 FLUSHO (not in POSIX; not supported under Linux) Output is being
248 flushed. This flag is toggled by typing the DISCARD character.
249 [requires _BSD_SOURCE or _SVID_SOURCE]
250 NOFLSH Disable flushing the input and output queues when generating the
252 SIGINT, SIGQUIT and SIGSUSP signals.
253 TOSTOP Send the SIGTTOU signal to the process group of a background
255 process which tries to write to its controlling terminal.
256 PENDIN (not in POSIX; not supported under Linux) All characters in the
258 input queue are reprinted when the next character is read.
259 (bash handles typeahead this way.) [requires _BSD_SOURCE or
260 _SVID_SOURCE]
261 IEXTEN Enable implementation-defined input processing. This flag, as
263 well as ICANON must be enabled for the special characters EOL2,
264 LNEXT, REPRINT, WERASE to be interpreted, and for the IUCLC flag
265 to be effective.
266 The c_cc array defines the special control characters. The symbolic
268 indices (initial values) and meaning are:
269 VINTR (003, ETX, Ctrl-C, or also 0177, DEL, rubout) Interrupt charac‐
271 ter. Send a SIGINT signal. Recognized when ISIG is set, and
272 then not passed as input.
273 VQUIT (034, FS, Ctrl-\) Quit character. Send SIGQUIT signal. Recog‐
275 nized when ISIG is set, and then not passed as input.
276 VERASE (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #) Erase charac‐
278 ter. This erases the previous not-yet-erased character, but does
279 not erase past EOF or beginning-of-line. Recognized when ICANON
280 is set, and then not passed as input.
281 VKILL (025, NAK, Ctrl-U, or Ctrl-X, or also @) Kill character. This
283 erases the input since the last EOF or beginning-of-line. Rec‐
284 ognized when ICANON is set, and then not passed as input.
285 VEOF (004, EOT, Ctrl-D) End-of-file character. More precisely: this
287 character causes the pending tty buffer to be sent to the wait‐
288 ing user program without waiting for end-of-line. If it is the
289 first character of the line, the read() in the user program
290 returns 0, which signifies end-of-file. Recognized when ICANON
291 is set, and then not passed as input.
292 VMIN Minimum number of characters for non-canonical read.
294 VEOL (0, NUL) Additional end-of-line character. Recognized when
296 ICANON is set.
297 VTIME Timeout in deciseconds for non-canonical read.
299 VEOL2 (not in POSIX; 0, NUL) Yet another end-of-line character. Rec‐
301 ognized when ICANON is set.
302 VSWTCH (not in POSIX; not supported under Linux; 0, NUL) Switch charac‐
304 ter. (Used by shl only.)
305 VSTART (021, DC1, Ctrl-Q) Start character. Restarts output stopped by
307 the Stop character. Recognized when IXON is set, and then not
308 passed as input.
309 VSTOP (023, DC3, Ctrl-S) Stop character. Stop output until Start char‐
311 acter typed. Recognized when IXON is set, and then not passed
312 as input.
313 VSUSP (032, SUB, Ctrl-Z) Suspend character. Send SIGTSTP signal. Rec‐
315 ognized when ISIG is set, and then not passed as input.
316 VDSUSP (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y)
318 Delayed suspend character: send SIGTSTP signal when the charac‐
319 ter is read by the user program. Recognized when IEXTEN and
320 ISIG are set, and the system supports job control, and then not
321 passed as input.
322 VLNEXT (not in POSIX; 026, SYN, Ctrl-V) Literal next. Quotes the next
324 input character, depriving it of a possible special meaning.
325 Recognized when IEXTEN is set, and then not passed as input.
326 VWERASE
328 (not in POSIX; 027, ETB, Ctrl-W) Word erase. Recognized when
329 ICANON and IEXTEN are set, and then not passed as input.
330 VREPRINT
332 (not in POSIX; 022, DC2, Ctrl-R) Reprint unread characters.
333 Recognized when ICANON and IEXTEN are set, and then not passed
334 as input.
335 VDISCARD
337 (not in POSIX; not supported under Linux; 017, SI, Ctrl-O) Tog‐
338 gle: start/stop discarding pending output. Recognized when IEX‐
339 TEN is set, and then not passed as input.
340 VSTATUS
342 (not in POSIX; not supported under Linux; status request: 024,
343 DC4, Ctrl-T).
344 These symbolic subscript values are all different, except that VTIME,
346 VMIN may have the same value as VEOL, VEOF, respectively. In non-
347 canonical mode the special character meaning is replaced by the timeout
348 meaning. For an explanation of VMIN and VTIME, see the description of
349 non-canonical mode below.
350 Retrieving and changing terminal settings
352 tcgetattr() gets the parameters associated with the object referred by
353 fd and stores them in the termios structure referenced by termios_p.
354 This function may be invoked from a background process; however, the
355 terminal attributes may be subsequently changed by a foreground
356 process.
357 tcsetattr() sets the parameters associated with the terminal (unless
359 support is required from the underlying hardware that is not available)
360 from the termios structure referred to by termios_p. optional_actions
361 specifies when the changes take effect:
362 TCSANOW
364 the change occurs immediately.
365 TCSADRAIN
367 the change occurs after all output written to fd has been trans‐
368 mitted. This function should be used when changing parameters
369 that affect output.
370 TCSAFLUSH
372 the change occurs after all output written to the object
373 referred by fd has been transmitted, and all input that has been
374 received but not read will be discarded before the change is
375 made.
376 Canonical and non-canonical mode
378 The setting of the ICANON canon flag in c_lflag determines whether the
379 terminal is operating in canonical mode (ICANON set) or non-canonical
380 mode (ICANON unset). By default, ICANON set.
381 In canonical mode:
383 * Input is made available line by line. An input line is available
385 when one of the line delimiters is typed (NL, EOL, EOL2; or EOF at
386 the start of line). Except in the case of EOF, the line delimiter is
387 included in the buffer returned by read(2).
388 * Line editing is enabled (ERASE, KILL; and if the IEXTEN flag is set:
390 WERASE, REPRINT, LNEXT). A read() returns at most one line of input;
391 if the read() requested fewer bytes than are available in the current
392 line of input, then only as many bytes as requested are read, and the
393 remaining characters will be available for a future read().
394 In non-canonical mode input is available immediately (without the user
396 having to type a line-delimiter character), and line editing is dis‐
397 abled. The settings of MIN (c_cc[VMIN]) and (c_cc[VTIME]) determine
398 the circumstances in which a read(2) completes; there are four distinct
399 cases:
400 * MIN == 0; TIME == 0: If data is available, read() returns immedi‐
402 ately, with the lesser of the number of bytes available, or the num‐
403 ber of bytes requested. If no data is available, read() returns 0.
404 * MIN > 0; TIME == 0: read() blocks until the lesser of MIN bytes or
406 the number of bytes requested are available, and returns the lesser
407 of these two values.
408 * MIN == 0; TIME > 0: TIME specifies the limit for a timer in tenths of
410 a second. The timer is started when read() is called. read()
411 returns either when at least one byte of data is available, or when
412 the timer expires. If the timer expires without any input becoming
413 available, read() returns 0.
414 * MIN > 0; TIME > 0: TIME specifies the limit for a timer in tenths of
416 a second. Once an initial byte of input becomes available, the timer
417 is restarted after each further byte is received. read() returns
418 either when the lesser of the number of bytes requested or MIN byte
419 have been read, or when the inter-byte timeout expires. Because the
420 timer is only started after the initial byte becomes available, at
421 least one byte will be read.
422 Raw mode
424 cfmakeraw() sets the terminal to something like the "raw" mode of the
425 old Version 7 terminal driver: input is available character by charac‐
426 ter, echoing is disabled, and all special processing of terminal input
427 and output characters is disabled. The terminal attributes are set as
428 follows:
429 termios_p->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP
431 | INLCR | IGNCR | ICRNL | IXON);
432 termios_p->c_oflag &= ~OPOST;
433 termios_p->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN);
434 termios_p->c_cflag &= ~(CSIZE | PARENB);
435 termios_p->c_cflag |= CS8;
436 Line control
438 tcsendbreak() transmits a continuous stream of zero-valued bits for a
439 specific duration, if the terminal is using asynchronous serial data
440 transmission. If duration is zero, it transmits zero-valued bits for
441 at least 0.25 seconds, and not more that 0.5 seconds. If duration is
442 not zero, it sends zero-valued bits for some implementation-defined
443 length of time.
444 If the terminal is not using asynchronous serial data transmission,
446 tcsendbreak() returns without taking any action.
447 tcdrain() waits until all output written to the object referred to by
449 fd has been transmitted.
450 tcflush() discards data written to the object referred to by fd but not
452 transmitted, or data received but not read, depending on the value of
453 queue_selector:
454 TCIFLUSH
456 flushes data received but not read.
457 TCOFLUSH
459 flushes data written but not transmitted.
460 TCIOFLUSH
462 flushes both data received but not read, and data written but
463 not transmitted.
464 tcflow() suspends transmission or reception of data on the object
466 referred to by fd, depending on the value of action:
467 TCOOFF suspends output.
469 TCOON restarts suspended output.
471 TCIOFF transmits a STOP character, which stops the terminal device from
473 transmitting data to the system.
474 TCION transmits a START character, which starts the terminal device
476 transmitting data to the system.
477 The default on open of a terminal file is that neither its input nor
479 its output is suspended.
480 Line speed
482 The baud rate functions are provided for getting and setting the values
483 of the input and output baud rates in the termios structure. The new
484 values do not take effect until tcsetattr() is successfully called.
485 Setting the speed to B0 instructs the modem to "hang up". The actual
487 bit rate corresponding to B38400 may be altered with setserial(8).
488 The input and output baud rates are stored in the termios structure.
490 cfgetospeed() returns the output baud rate stored in the termios struc‐
492 ture pointed to by termios_p.
493 cfsetospeed() sets the output baud rate stored in the termios structure
495 pointed to by termios_p to speed, which must be one of these constants:
496 B0
498 B50
499 B75
500 B110
501 B134
502 B150
503 B200
504 B300
505 B600
506 B1200
507 B1800
508 B2400
509 B4800
510 B9600
511 B19200
512 B38400
513 B57600
514 B115200
515 B230400
516 The zero baud rate, B0, is used to terminate the connection. If B0 is
518 specified, the modem control lines shall no longer be asserted. Nor‐
519 mally, this will disconnect the line. CBAUDEX is a mask for the speeds
520 beyond those defined in POSIX.1 (57600 and above). Thus, B57600 &
521 CBAUDEX is non-zero.
522 cfgetispeed() returns the input baud rate stored in the termios struc‐
524 ture.
525 cfsetispeed() sets the input baud rate stored in the termios structure
527 to speed, which must be specified as one of the Bnnn constants listed
528 above for cfsetospeed(). If the input baud rate is set to zero, the
529 input baud rate will be equal to the output baud rate.
530 cfsetspeed() is a 4.4BSD extension. It takes the same arguments as
532 cfsetispeed(), and sets both input and output speed.
533
535 cfgetispeed() returns the input baud rate stored in the termios struc‐
536 ture.
537 cfgetospeed() returns the output baud rate stored in the termios struc‐
539 ture.
540 All other functions return:
542 0 on success.
544 -1 on failure and set errno to indicate the error.
546 Note that tcsetattr() returns success if any of the requested changes
548 could be successfully carried out. Therefore, when making multiple
549 changes it may be necessary to follow this call with a further call to
550 tcgetattr() to check that all changes have been performed successfully.
551
554 Unix V7 and several later systems have a list of baud rates where after
555 the fourteen values B0, ..., B9600 one finds the two constants EXTA,
556 EXTB ("External A" and "External B"). Many systems extend the list
557 with much higher baud rates.
558 The effect of a non-zero duration with tcsendbreak() varies. SunOS
560 specifies a break of duration*N seconds, where N is at least 0.25, and
561 not more than 0.5. Linux, AIX, DU, Tru64 send a break of duration mil‐
562 liseconds. FreeBSD and NetBSD and HP-UX and MacOS ignore the value of
563 duration. Under Solaris and Unixware, tcsendbreak() with non-zero
564 duration behaves like tcdrain().
565
567 stty(1), console_ioctl(4), tty_ioctl(4), feature_test_macros(7), setse‐
568 rial(8)
569Linux 2004-10-31 TERMIOS(3)