1TERMIOS(3) Linux Programmer's Manual TERMIOS(3)
2
3
4
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
15 int tcgetattr(int fd, struct termios *termios_p);
16
17 int tcsetattr(int fd, int optional_actions, const struct termios
18 *termios_p);
19
20 int tcsendbreak(int fd, int duration);
21
22 int tcdrain(int fd);
23
24 int tcflush(int fd, int queue_selector);
25
26 int tcflow(int fd, int action);
27
28 void cfmakeraw(struct termios *termios_p);
29
30 speed_t cfgetispeed(const struct termios *termios_p);
31
32 speed_t cfgetospeed(const struct termios *termios_p);
33
34 int cfsetispeed(struct termios *termios_p, speed_t speed);
35
36 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
42 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
47 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
53 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
59 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
63 c_iflag flag constants:
64
65 IGNBRK Ignore BREAK condition on input.
66
67 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
76 IGNPAR Ignore framing errors and parity errors.
77
78 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
83 INPCK Enable input parity checking.
84
85 ISTRIP Strip off eighth bit.
86
87 INLCR Translate NL to CR on input.
88
89 IGNCR Ignore carriage return on input.
90
91 ICRNL Translate carriage return to newline on input (unless IGNCR is
92 set).
93
94 IUCLC (not in POSIX) Map uppercase characters to lowercase on input.
95
96 IXON Enable XON/XOFF flow control on output.
97
98 IXANY (XSI) Typing any character will restart stopped output. (The
99 default is to allow just the START character to restart output.)
100
101 IXOFF Enable XON/XOFF flow control on input.
102
103 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
107 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
111 c_oflag flag constants defined in POSIX.1:
112
113 OPOST Enable implementation-defined output processing.
114
115 The remaining c_oflag flag constants are defined in POSIX.1-2001,
116 unless marked otherwise.
117
118 OLCUC (not in POSIX) Map lowercase characters to uppercase on output.
119
120 ONLCR (XSI) Map NL to CR-NL on output.
121
122 OCRNL Map CR to NL on output.
123
124 ONOCR Don't output CR at column 0.
125
126 ONLRET Don't output CR.
127
128 OFILL Send fill characters for a delay, rather than using a timed
129 delay.
130
131 OFDEL (not in POSIX) Fill character is ASCII DEL (0177). If unset,
132 fill character is ASCII NUL ('\0'). (Not implemented on Linux.)
133
134 NLDLY Newline delay mask. Values are NL0 and NL1. [requires
135 _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
136
137 CRDLY Carriage return delay mask. Values are CR0, CR1, CR2, or CR3.
138 [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
139
140 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
145 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
149 VTDLY Vertical tab delay mask. Values are VT0 or VT1.
150
151 FFDLY Form feed delay mask. Values are FF0 or FF1. [requires
152 _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
153
154 c_cflag flag constants:
155
156 CBAUD (not in POSIX) Baud speed mask (4+1 bits). [requires
157 _BSD_SOURCE or _SVID_SOURCE]
158
159 CBAUDEX
160 (not in POSIX) Extra baud speed mask (1 bit), included in CBAUD.
161 [requires _BSD_SOURCE or _SVID_SOURCE]
162
163 (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
169 CSIZE Character size mask. Values are CS5, CS6, CS7, or CS8.
170
171 CSTOPB Set two stop bits, rather than one.
172
173 CREAD Enable receiver.
174
175 PARENB Enable parity generation on output and parity checking for
176 input.
177
178 PARODD If set, then parity for input and output is odd; otherwise even
179 parity is used.
180
181 HUPCL Lower modem control lines after last process closes the device
182 (hang up).
183
184 CLOCAL Ignore modem control lines.
185
186 LOBLK (not in POSIX) Block output from a noncurrent shell layer. For
187 use by shl (shell layers). (Not implemented on Linux.)
188
189 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
194 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
199 CRTSCTS
200 (not in POSIX) Enable RTS/CTS (hardware) flow control.
201 [requires _BSD_SOURCE or _SVID_SOURCE]
202
203 c_lflag flag constants:
204
205 ISIG When any of the characters INTR, QUIT, SUSP, or DSUSP are
206 received, generate the corresponding signal.
207
208 ICANON Enable canonical mode (described below).
209
210 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
216 ECHO Echo input characters.
217
218 ECHOE If ICANON is also set, the ERASE character erases the preceding
219 input character, and WERASE erases the preceding word.
220
221 ECHOK If ICANON is also set, the KILL character erases the current
222 line.
223
224 ECHONL If ICANON is also set, echo the NL character even if ECHO is not
225 set.
226
227 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
234 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
239 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
243 DEFECHO
244 (not in POSIX) Echo only when a process is reading. (Not imple‐
245 mented on Linux.)
246
247 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
251 NOFLSH Disable flushing the input and output queues when generating the
252 SIGINT, SIGQUIT and SIGSUSP signals.
253
254 TOSTOP Send the SIGTTOU signal to the process group of a background
255 process which tries to write to its controlling terminal.
256
257 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
262 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
267 The c_cc array defines the special control characters. The symbolic
268 indices (initial values) and meaning are:
269
270 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
274 VQUIT (034, FS, Ctrl-\) Quit character. Send SIGQUIT signal. Recog‐
275 nized when ISIG is set, and then not passed as input.
276
277 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
282 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
286 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
293 VMIN Minimum number of characters for non-canonical read.
294
295 VEOL (0, NUL) Additional end-of-line character. Recognized when
296 ICANON is set.
297
298 VTIME Timeout in deciseconds for non-canonical read.
299
300 VEOL2 (not in POSIX; 0, NUL) Yet another end-of-line character. Rec‐
301 ognized when ICANON is set.
302
303 VSWTCH (not in POSIX; not supported under Linux; 0, NUL) Switch charac‐
304 ter. (Used by shl only.)
305
306 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
310 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
314 VSUSP (032, SUB, Ctrl-Z) Suspend character. Send SIGTSTP signal. Rec‐
315 ognized when ISIG is set, and then not passed as input.
316
317 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
323 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
327 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
331 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
336 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
341 VSTATUS
342 (not in POSIX; not supported under Linux; status request: 024,
343 DC4, Ctrl-T).
344
345 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
351 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
358 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
363 TCSANOW
364 the change occurs immediately.
365
366 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
371 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
377 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
382 In canonical mode:
383
384 * 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
389 * 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
395 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
401 * 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
405 * 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
409 * 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
415 * 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
423 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
430 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
437 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
445 If the terminal is not using asynchronous serial data transmission,
446 tcsendbreak() returns without taking any action.
447
448 tcdrain() waits until all output written to the object referred to by
449 fd has been transmitted.
450
451 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
455 TCIFLUSH
456 flushes data received but not read.
457
458 TCOFLUSH
459 flushes data written but not transmitted.
460
461 TCIOFLUSH
462 flushes both data received but not read, and data written but
463 not transmitted.
464
465 tcflow() suspends transmission or reception of data on the object
466 referred to by fd, depending on the value of action:
467
468 TCOOFF suspends output.
469
470 TCOON restarts suspended output.
471
472 TCIOFF transmits a STOP character, which stops the terminal device from
473 transmitting data to the system.
474
475 TCION transmits a START character, which starts the terminal device
476 transmitting data to the system.
477
478 The default on open of a terminal file is that neither its input nor
479 its output is suspended.
480
481 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
486 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
489 The input and output baud rates are stored in the termios structure.
490
491 cfgetospeed() returns the output baud rate stored in the termios struc‐
492 ture pointed to by termios_p.
493
494 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
497 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
517 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
523 cfgetispeed() returns the input baud rate stored in the termios struc‐
524 ture.
525
526 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
531 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
538 cfgetospeed() returns the output baud rate stored in the termios struc‐
539 ture.
540
541 All other functions return:
542
543 0 on success.
544
545 -1 on failure and set errno to indicate the error.
546
547 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
552
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
559 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)
569
570
571
572Linux 2004-10-31 TERMIOS(3)