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,
18                     const struct termios *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
38       int cfsetspeed(struct termios *termios_p, speed_t speed);
39
40   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
41
42       cfsetspeed(), cfmakeraw(): _BSD_SOURCE
43

DESCRIPTION

45       The termios functions describe a general  terminal  interface  that  is
46       provided to control asynchronous communications ports.
47
48   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
53           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
59       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
65       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
69       c_iflag flag constants:
70
71       IGNBRK Ignore BREAK condition on input.
72
73       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
82       IGNPAR Ignore framing errors and parity errors.
83
84       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
89       INPCK  Enable input parity checking.
90
91       ISTRIP Strip off eighth bit.
92
93       INLCR  Translate NL to CR on input.
94
95       IGNCR  Ignore carriage return on input.
96
97       ICRNL  Translate  carriage  return to newline on input (unless IGNCR is
98              set).
99
100       IUCLC  (not in POSIX) Map uppercase characters to lowercase on input.
101
102       IXON   Enable XON/XOFF flow control on output.
103
104       IXANY  (XSI) Typing any character will restart  stopped  output.   (The
105              default is to allow just the START character to restart output.)
106
107       IXOFF  Enable XON/XOFF flow control on input.
108
109       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
113       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
117       c_oflag flag constants defined in POSIX.1:
118
119       OPOST  Enable implementation-defined output processing.
120
121       The  remaining  c_oflag  flag  constants  are  defined in POSIX.1-2001,
122       unless marked otherwise.
123
124       OLCUC  (not in POSIX) Map lowercase characters to uppercase on output.
125
126       ONLCR  (XSI) Map NL to CR-NL on output.
127
128       OCRNL  Map CR to NL on output.
129
130       ONOCR  Don't output CR at column 0.
131
132       ONLRET Don't output CR.
133
134       OFILL  Send fill characters for a delay,  rather  than  using  a  timed
135              delay.
136
137       OFDEL  (not  in  POSIX)  Fill character is ASCII DEL (0177).  If unset,
138              fill character is ASCII NUL ('\0').  (Not implemented on Linux.)
139
140       NLDLY  Newline  delay  mask.   Values  are  NL0  and  NL1.    [requires
141              _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
142
143       CRDLY  Carriage  return  delay mask.  Values are CR0, CR1, CR2, or CR3.
144              [requires _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
145
146       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
151       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
155       VTDLY  Vertical tab delay mask.  Values are VT0 or VT1.
156
157       FFDLY  Form  feed  delay  mask.   Values  are  FF0  or  FF1.  [requires
158              _BSD_SOURCE or _SVID_SOURCE or _XOPEN_SOURCE]
159
160       c_cflag flag constants:
161
162       CBAUD  (not  in  POSIX)  Baud  speed  mask   (4+1   bits).    [requires
163              _BSD_SOURCE or _SVID_SOURCE]
164
165       CBAUDEX
166              (not in POSIX) Extra baud speed mask (1 bit), included in CBAUD.
167              [requires _BSD_SOURCE or _SVID_SOURCE]
168
169              (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
175       CSIZE  Character size mask.  Values are CS5, CS6, CS7, or CS8.
176
177       CSTOPB Set two stop bits, rather than one.
178
179       CREAD  Enable receiver.
180
181       PARENB Enable parity generation  on  output  and  parity  checking  for
182              input.
183
184       PARODD If  set, then parity for input and output is odd; otherwise even
185              parity is used.
186
187       HUPCL  Lower modem control lines after last process closes  the  device
188              (hang up).
189
190       CLOCAL Ignore modem control lines.
191
192       LOBLK  (not  in POSIX) Block output from a noncurrent shell layer.  For
193              use by shl (shell layers).  (Not implemented on Linux.)
194
195       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
200       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
205       CRTSCTS
206              (not  in  POSIX)  Enable  RTS/CTS   (hardware)   flow   control.
207              [requires _BSD_SOURCE or _SVID_SOURCE]
208
209       c_lflag flag constants:
210
211       ISIG   When  any  of  the  characters  INTR,  QUIT,  SUSP, or DSUSP are
212              received, generate the corresponding signal.
213
214       ICANON Enable canonical mode (described below).
215
216       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
223       ECHO   Echo input characters.
224
225       ECHOE  If  ICANON is also set, the ERASE character erases the preceding
226              input character, and WERASE erases the preceding word.
227
228       ECHOK  If ICANON is also set, the KILL  character  erases  the  current
229              line.
230
231       ECHONL If ICANON is also set, echo the NL character even if ECHO is not
232              set.
233
234       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
241       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
246       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
250       DEFECHO
251              (not in POSIX) Echo only when a process is reading.  (Not imple‐
252              mented on Linux.)
253
254       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
258       NOFLSH Disable  flushing  the  input  and output queues when generating
259              signals for the INT, QUIT, and SUSP characters.
260
261       TOSTOP Send the SIGTTOU signal to the process  group  of  a  background
262              process which tries to write to its controlling terminal.
263
264       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
269       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
274       The  c_cc  array  defines the special control characters.  The symbolic
275       indices (initial values) and meaning are:
276
277       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
281       VQUIT  (034, FS, Ctrl-\) Quit character.  Send SIGQUIT signal.   Recog‐
282              nized when ISIG is set, and then not passed as input.
283
284       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
289       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
293       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
300       VMIN   Minimum number of characters for noncanonical read.
301
302       VEOL   (0,  NUL)  Additional  end-of-line  character.   Recognized when
303              ICANON is set.
304
305       VTIME  Timeout in deciseconds for noncanonical read.
306
307       VEOL2  (not in POSIX; 0, NUL) Yet another end-of-line character.   Rec‐
308              ognized when ICANON is set.
309
310       VSWTCH (not in POSIX; not supported under Linux; 0, NUL) Switch charac‐
311              ter.  (Used by shl only.)
312
313       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
317       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
321       VSUSP  (032, SUB, Ctrl-Z)  Suspend  character.   Send  SIGTSTP  signal.
322              Recognized when ISIG is set, and then not passed as input.
323
324       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
330       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
334       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
338       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
343       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
348       VSTATUS
349              (not in POSIX; not supported under Linux; status  request:  024,
350              DC4, Ctrl-T).
351
352       These  symbolic  subscript values are all different, except that VTIME,
353       VMIN may have the same value as VEOL, VEOF, respectively.  In noncanon‐
354       ical  mode  the  special  character  meaning is replaced by the timeout
355       meaning.  For an explanation of VMIN and VTIME, see the description  of
356       noncanonical mode below.
357
358   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
365       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
370       TCSANOW
371              the change occurs immediately.
372
373       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
378       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
384   Canonical and noncanonical 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  noncanonical
387       mode (ICANON unset).  By default, ICANON set.
388
389       In canonical mode:
390
391       * 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
396       * 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
402       In noncanonical 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
408       * 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
412       * 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
416       * 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
422       * 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
430   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
437           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
444   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
452       If  the  terminal  is  not using asynchronous serial data transmission,
453       tcsendbreak() returns without taking any action.
454
455       tcdrain() waits until all output written to the object referred  to  by
456       fd has been transmitted.
457
458       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
462       TCIFLUSH
463              flushes data received but not read.
464
465       TCOFLUSH
466              flushes data written but not transmitted.
467
468       TCIOFLUSH
469              flushes  both  data  received but not read, and data written but
470              not transmitted.
471
472       tcflow() suspends transmission or  reception  of  data  on  the  object
473       referred to by fd, depending on the value of action:
474
475       TCOOFF suspends output.
476
477       TCOON  restarts suspended output.
478
479       TCIOFF transmits a STOP character, which stops the terminal device from
480              transmitting data to the system.
481
482       TCION  transmits a START character, which starts  the  terminal  device
483              transmitting data to the system.
484
485       The  default  on  open of a terminal file is that neither its input nor
486       its output is suspended.
487
488   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
493       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
496       The input and output baud rates are stored in the termios structure.
497
498       cfgetospeed() returns the output baud rate stored in the termios struc‐
499       ture pointed to by termios_p.
500
501       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
504            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
524       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 nonzero.
529
530       cfgetispeed()  returns the input baud rate stored in the termios struc‐
531       ture.
532
533       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
538       cfsetspeed()  is  a  4.4BSD  extension.  It takes the same arguments as
539       cfsetispeed(), and sets both input and output speed.
540

RETURN VALUE

542       cfgetispeed() returns the input baud rate stored in the termios  struc‐
543       ture.
544
545       cfgetospeed() returns the output baud rate stored in the termios struc‐
546       ture.
547
548       All other functions return:
549
550       0      on success.
551
552       -1     on failure and set errno to indicate the error.
553
554       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

CONFORMING TO

560       tcgetattr(),    tcsetattr(),   tcsendbreak(),   tcdrain(),   tcflush(),
561       tcflow(),  cfgetispeed(),  cfgetospeed(),  cfsetispeed(),   and   cfse‐
562       tospeed() are specified in POSIX.1-2001.
563
564       cfmakeraw()  and  cfsetspeed()  are  nonstandard,  but available on the
565       BSDs.
566

NOTES

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
573       The  effect  of  a  nonzero  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 nonzero
578       duration behaves like tcdrain().
579

SEE ALSO

581       stty(1), console_ioctl(4), tty_ioctl(4), setserial(8)
582

COLOPHON

584       This page is part of release 3.25 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/.
587
588
589
590Linux                             2010-06-20                        TERMIOS(3)
Impressum