1TERMIOS(3)                 Linux Programmer's Manual                TERMIOS(3)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

NOTES

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

SEE ALSO

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)
Impressum