1 .\" Hey Emacs! This file is -*- nroff -*- source.
3 .\" Copyright (c) 1993 Michael Haardt
5 .\" Fri Apr 2 11:32:09 MET DST 1993
7 .\" This is free documentation; you can redistribute it and/or
8 .\" modify it under the terms of the GNU General Public License as
9 .\" published by the Free Software Foundation; either version 2 of
10 .\" the License, or (at your option) any later version.
12 .\" The GNU General Public License's references to "object code"
13 .\" and "executables" are to be interpreted as the output of any
14 .\" document formatting or typesetting system, including
15 .\" intermediate and printed output.
17 .\" This manual is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
22 .\" You should have received a copy of the GNU General Public
23 .\" License along with this manual; if not, write to the Free
24 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
27 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
28 .\" Modified 1995-02-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
29 .\" Modified 1995-09-02 by Jim Van Zandt <jrv@vanzandt.mv.com>
30 .\" moved to man3, aeb, 950919
31 .\" Modified 2001-09-22 by Michael Kerrisk <mtk-manpages@gmx.net>
32 .\" Modified 2001-12-17, aeb
33 .\" Modified 2004-10-31, aeb
35 .TH TERMIOS 3 2004-10-31 "Linux" "Linux Programmer's Manual"
37 termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow,
38 cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \-
39 get and set terminal attributes, line control, get and set baud rate
47 .BI "int tcgetattr(int " fd ", struct termios *" termios_p );
49 .BI "int tcsetattr(int " fd ", int " optional_actions ", const struct termios *" termios_p );
51 .BI "int tcsendbreak(int " fd ", int " duration );
53 .BI "int tcdrain(int " fd );
55 .BI "int tcflush(int " fd ", int " queue_selector );
57 .BI "int tcflow(int " fd ", int " action );
59 .BI "void cfmakeraw(struct termios *" termios_p );
61 .BI "speed_t cfgetispeed(const struct termios *" termios_p );
63 .BI "speed_t cfgetospeed(const struct termios *" termios_p );
65 .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed );
67 .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed );
71 The termios functions describe a general terminal interface that is
72 provided to control asynchronous communications ports.
74 Many of the functions described here have a \fItermios_p\fP argument
75 that is a pointer to a \fBtermios\fP structure. This structure contains
76 at least the following members:
81 tcflag_t \fIc_iflag\fP; /* input modes */
82 tcflag_t \fIc_oflag\fP; /* output modes */
83 tcflag_t \fIc_cflag\fP; /* control modes */
84 tcflag_t \fIc_lflag\fP; /* local modes */
85 cc_t \fIc_cc\fP[\fBNCCS\fP]; /* control chars */
89 \fIc_iflag\fP flag constants:
92 Ignore BREAK condition on input.
95 If \fBIGNBRK\fP is set, a BREAK is ignored. If it is not set
96 but \fBBRKINT\fP is set, then a BREAK causes the input and output
97 queues to be flushed, and if the terminal is the controlling
98 terminal of a foreground process group, it will cause a
99 \fBSIGINT\fP to be sent to this foreground process group.
100 When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK
101 reads as a NUL character, except when \fBPARMRK\fP is set,
102 in which case it reads as the sequence \\377 \\0 \\0.
105 Ignore framing errors and parity errors.
108 If \fBIGNPAR\fP is not set, prefix a character with a parity error or
109 framing error with \\377 \\0. If neither \fBIGNPAR\fP nor \fBPARMRK\fP
110 is set, read a character with a parity error or framing error
114 Enable input parity checking.
117 Strip off eighth bit.
120 Translate NL to CR on input.
123 Ignore carriage return on input.
126 Translate carriage return to newline on input (unless \fBIGNCR\fP is set).
129 (not in POSIX) Map uppercase characters to lowercase on input.
132 Enable XON/XOFF flow control on output.
135 (not in POSIX.1; XSI) Enable any character to restart output.
138 Enable XON/XOFF flow control on input.
141 (not in POSIX) Ring bell when input queue is full.
142 Linux does not implement this bit, and acts as if it is always set.
144 \fIc_oflag\fP flag constants defined in POSIX.1:
147 Enable implementation-defined output processing.
149 The remaining \fIc_oflag\fP flag constants are defined in POSIX 1003.1-2001,
150 unless marked otherwise.
153 (not in POSIX) Map lowercase characters to uppercase on output.
156 (XSI) Map NL to CR-NL on output.
159 Map CR to NL on output.
162 Don't output CR at column 0.
168 Send fill characters for a delay, rather than using a timed delay.
171 (not in POSIX) Fill character is ASCII DEL (0177).
172 If unset, fill character is ASCII NUL.
175 Newline delay mask. Values are \fBNL0\fP and \fBNL1\fP.
178 Carriage return delay mask.
179 Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP.
182 Horizontal tab delay mask.
183 Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP).
184 A value of TAB3, that is, XTABS, expands tabs to spaces
185 (with tab stops every eight columns).
188 Backspace delay mask. Values are \fBBS0\fP or \fBBS1\fP.
189 (Has never been implemented.)
192 Vertical tab delay mask. Values are \fBVT0\fP or \fBVT1\fP.
195 Form feed delay mask. Values are \fBFF0\fP or \fBFF1\fP.
197 \fIc_cflag\fP flag constants:
200 (not in POSIX) Baud speed mask (4+1 bits).
203 (not in POSIX) Extra baud speed mask (1 bit), included in CBAUD.
205 (POSIX says that the baud speed is stored in the termios structure
206 without specifying where precisely, and provides
210 for getting at it. Some systems use bits selected by CBAUD in
212 other systems use separate fields, e.g.
219 Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP.
222 Set two stop bits, rather than one.
228 Enable parity generation on output and parity checking for input.
231 Parity for input and output is odd.
234 Lower modem control lines after last process closes the device (hang up).
237 Ignore modem control lines.
240 (not in POSIX) Block output from a noncurrent shell layer.
241 (For use by \fBshl\fP.)
244 (not in POSIX) Mask for input speeds. The values for the CIBAUD bits are
245 the same as the values for the CBAUD bits, shifted left IBSHIFT bits.
248 (not in POSIX) Enable RTS/CTS (hardware) flow control.
250 \fIc_lflag\fP flag constants:
253 When any of the characters INTR, QUIT, SUSP, or DSUSP are received,
254 generate the corresponding signal.
257 Enable canonical mode. This enables the special characters
258 EOF, EOL, EOL2, ERASE, KILL, LNEXT, REPRINT, STATUS, and WERASE, and
262 (not in POSIX; not supported under Linux)
263 If \fBICANON\fP is also set, terminal is uppercase only.
264 Input is converted to lowercase, except for characters preceded by \\.
265 On output, uppercase characters are preceded by \\ and lowercase
266 characters are converted to uppercase.
269 Echo input characters.
272 If \fBICANON\fP is also set, the ERASE character erases the preceding
273 input character, and WERASE erases the preceding word.
276 If \fBICANON\fP is also set, the KILL character erases the current line.
279 If \fBICANON\fP is also set, echo the NL character even if ECHO is not set.
282 (not in POSIX) If \fBECHO\fP is also set, ASCII control signals other than
283 TAB, NL, START, and STOP are echoed as ^X, where X is the character with
284 ASCII code 0x40 greater than the control signal. For example, character
285 0x08 (BS) is echoed as ^H.
288 (not in POSIX) If \fBICANON\fP and \fBIECHO\fP are also set, characters
289 are printed as they are being erased.
292 (not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing
293 each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP.
296 (not in POSIX) Echo only when a process is reading.
299 (not in POSIX; not supported under Linux)
300 Output is being flushed. This flag is toggled by typing
301 the DISCARD character.
304 Disable flushing the input and output queues when generating the SIGINT,
305 SIGQUIT and SIGSUSP signals.
306 .\" Stevens lets SIGSUSP only flush the input queue
309 Send the SIGTTOU signal to the process group of a background process
310 which tries to write to its controlling terminal.
313 (not in POSIX; not supported under Linux)
314 All characters in the input queue are reprinted when
315 the next character is read. (\fBbash\fP handles typeahead this way.)
318 Enable implementation-defined input processing.
319 This flag, as well as \fBICANON\fP must be enabled for the
320 special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted,
321 and for the \fBIUCLC\fP flag to be effective.
323 The \fIc_cc\fP array defines the special control characters.
324 The symbolic indices (initial values) and meaning are:
327 (003, ETX, Ctrl-C, or also 0177, DEL, rubout)
328 Interrupt character. Send a SIGINT signal.
329 Recognized when ISIG is set, and then not passed as input.
333 Quit character. Send SIGQUIT signal.
334 Recognized when ISIG is set, and then not passed as input.
337 (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #)
338 Erase character. This erases the previous not-yet-erased character,
339 but does not erase past EOF or beginning-of-line.
340 Recognized when ICANON is set, and then not passed as input.
343 (025, NAK, Ctrl-U, or Ctrl-X, or also @)
344 Kill character. This erases the input since the last EOF or beginning-of-line.
345 Recognized when ICANON is set, and then not passed as input.
349 End-of-file character.
350 More precisely: this character causes the pending tty buffer to be sent
351 to the waiting user program without waiting for end-of-line.
352 If it is the first character of the line, the \fIread\fP() in the
353 user program returns 0, which signifies end-of-file.
354 Recognized when ICANON is set, and then not passed as input.
357 Minimum number of characters for non-canonical read.
361 Additional end-of-line character.
362 Recognized when ICANON is set.
365 Timeout in deciseconds for non-canonical read.
368 (not in POSIX; 0, NUL)
369 Yet another end-of-line character.
370 Recognized when ICANON is set.
373 (not in POSIX; not supported under Linux; 0, NUL)
374 Switch character. (Used by \fBshl\fP only.)
378 Start character. Restarts output stopped by the Stop character.
379 Recognized when IXON is set, and then not passed as input.
383 Stop character. Stop output until Start character typed.
384 Recognized when IXON is set, and then not passed as input.
388 Suspend character. Send SIGTSTP signal.
389 Recognized when ISIG is set, and then not passed as input.
392 (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y)
393 Delayed suspend character:
394 send SIGTSTP signal when the character is read by the user program.
395 Recognized when IEXTEN and ISIG are set, and the system supports
396 job control, and then not passed as input.
399 (not in POSIX; 026, SYN, Ctrl-V)
400 Literal next. Quotes the next input character, depriving it of
401 a possible special meaning.
402 Recognized when IEXTEN is set, and then not passed as input.
405 (not in POSIX; 027, ETB, Ctrl-W)
407 Recognized when ICANON and IEXTEN are set, and then not passed as input.
410 (not in POSIX; 022, DC2, Ctrl-R)
411 Reprint unread characters.
412 Recognized when ICANON and IEXTEN are set, and then not passed as input.
415 (not in POSIX; not supported under Linux; 017, SI, Ctrl-O)
416 Toggle: start/stop discarding pending output.
417 Recognized when IEXTEN is set, and then not passed as input.
420 (not in POSIX; not supported under Linux;
421 status request: 024, DC4, Ctrl-T).
423 These symbolic subscript values are all different, except that
424 VTIME, VMIN may have the same value as VEOL, VEOF, respectively.
425 (In non-canonical mode the special character meaning is replaced
426 by the timeout meaning. MIN represents the minimum number of characters
427 that should be received to satisfy the read. TIME is a decisecond-valued
428 timer. When both are set, a read will wait until at least one character
429 has been received, and then return as soon as either MIN characters
430 have been received or time TIME has passed since the last character
431 was received. If only MIN is set, the read will not return before
432 MIN characters have been received. If only TIME is set, the read will
433 return as soon as either at least one character has been received,
434 or the timer times out. If neither is set, the read will return
435 immediately, only giving the currently already available characters.)
438 gets the parameters associated with the object referred by \fIfd\fP and
439 stores them in the \fBtermios\fP structure referenced by
440 \fItermios_p\fP. This function may be invoked from a background process;
441 however, the terminal attributes may be subsequently changed by a
445 sets the parameters associated with the terminal (unless support is
446 required from the underlying hardware that is not available) from the
447 \fBtermios\fP structure referred to by \fItermios_p\fP.
448 \fIoptional_actions\fP specifies when the changes take effect:
450 the change occurs immediately.
452 the change occurs after all output written to
454 has been transmitted. This function should be used when changing
455 parameters that affect output.
457 the change occurs after all output written to the object referred by
459 has been transmitted, and all input that has been received but not read
460 will be discarded before the change is made.
463 transmits a continuous stream of zero-valued bits for a specific
464 duration, if the terminal is using asynchronous serial data
465 transmission. If \fIduration\fP is zero, it transmits zero-valued bits
466 for at least 0.25 seconds, and not more that 0.5 seconds. If
467 \fIduration\fP is not zero, it sends zero-valued bits for some
468 implementation-defined length of time.
470 If the terminal is not using asynchronous serial data transmission,
471 \fBtcsendbreak\fP() returns without taking any action.
474 waits until all output written to the object referred to by
476 has been transmitted.
479 discards data written to the object referred to by
481 but not transmitted, or data received but not read, depending on the
485 flushes data received but not read.
487 flushes data written but not transmitted.
489 flushes both data received but not read, and data written but not
493 suspends transmission or reception of data on the object referred to by
495 depending on the value of
500 restarts suspended output.
502 transmits a STOP character, which stops the terminal device from transmitting data to the
505 transmits a START character, which starts the terminal device transmitting data to the
508 The default on open of a terminal file is that neither its input nor its
511 The baud rate functions are provided for getting and setting the values
512 of the input and output baud rates in the \fBtermios\fP structure. The
513 new values do not take effect
514 until \fBtcsetattr\fP() is successfully called.
516 Setting the speed to \fBB0\fP instructs the modem to "hang up".
517 The actual bit rate corresponding to \fBB38400\fP may be altered with
520 The input and output baud rates are stored in the \fBtermios\fP
523 \fBcfmakeraw\fP() sets the terminal attributes as follows:
525 termios_p->c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP
526 |INLCR|IGNCR|ICRNL|IXON);
527 termios_p->c_oflag &= ~OPOST;
528 termios_p->c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
529 termios_p->c_cflag &= ~(CSIZE|PARENB);
530 termios_p->c_cflag |= CS8;
534 returns the output baud rate stored in the \fBtermios\fP structure
539 sets the output baud rate stored in the \fBtermios\fP structure pointed
540 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
564 The zero baud rate, \fBB0\fP,
565 is used to terminate the connection. If B0
566 is specified, the modem control lines shall no longer be asserted.
567 Normally, this will disconnect the line. \fBCBAUDEX\fP is a mask
568 for the speeds beyond those defined in POSIX.1 (57600 and above).
569 Thus, \fBB57600\fP & \fBCBAUDEX\fP is non-zero.
572 returns the input baud rate stored in the \fBtermios\fP structure.
575 sets the input baud rate stored in the \fBtermios\fP structure to
577 If the input baud rate is set to zero, the input baud rate will be
578 equal to the output baud rate.
581 is a 4.4 BSD extension. It will set both input and output speed.
585 returns the input baud rate stored in the
590 returns the output baud rate stored in the \fBtermios\fP structure.
592 All other functions return:
598 to indicate the error.
602 returns success if \fIany\fP of the requested changes could be
603 successfully carried out. Therefore, when making multiple changes
604 it may be necessary to follow this call with a further call to
606 to check that all changes have been performed successfully.
609 Unix V7 and several later systems have a list of baud rates
610 where after the fourteen values B0, ..., B9600 one finds the
611 two constants EXTA, EXTB ("External A" and "External B").
612 Many systems extend the list with much higher baud rates.
614 The effect of a non-zero \fIduration\fP with \fBtcsendbreak\fP() varies.
615 SunOS specifies a break of
617 seconds, where \fIN\fP is at least 0.25, and not more than 0.5.
618 Linux, AIX, DU, Tru64 send a break of
621 FreeBSD and NetBSD and HP-UX and MacOS ignore the value of
623 Under Solaris and Unixware,
629 .\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0.
630 .\" libc4.7.6, libc5, glibc for unix: duration in ms.
631 .\" glibc for bsd: duration in us
632 .\" glibc for sunos4: ignore duration