| blob | fbf909bb24fb3b795e7fe2d1a9dc76156256264e |
1 .\" Copyright (c) 1993 Michael Haardt
2 .\" (michael@moria.de)
3 .\" Fri Apr 2 11:32:09 MET DST 1993
4 .\"
5 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
6 .\" This is free documentation; you can redistribute it and/or
7 .\" modify it under the terms of the GNU General Public License as
8 .\" published by the Free Software Foundation; either version 2 of
9 .\" the License, or (at your option) any later version.
10 .\"
11 .\" The GNU General Public License's references to "object code"
12 .\" and "executables" are to be interpreted as the output of any
13 .\" document formatting or typesetting system, including
14 .\" intermediate and printed output.
15 .\"
16 .\" This manual is distributed in the hope that it will be useful,
17 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 .\" GNU General Public License for more details.
20 .\"
21 .\" You should have received a copy of the GNU General Public
22 .\" License along with this manual; if not, see
23 .\" <http://www.gnu.org/licenses/>.
24 .\" %%%LICENSE_END
25 .\"
26 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
27 .\" Modified 1995-02-25 by Jim Van Zandt <jrv@vanzandt.mv.com>
28 .\" Modified 1995-09-02 by Jim Van Zandt <jrv@vanzandt.mv.com>
29 .\" moved to man3, aeb, 950919
30 .\" Modified 2001-09-22 by Michael Kerrisk <mtk.manpages@gmail.com>
31 .\" Modified 2001-12-17, aeb
32 .\" Modified 2004-10-31, aeb
33 .\" 2006-12-28, mtk:
34 .\" Added .SS headers to give some structure to this page; and a
35 .\" small amount of reordering.
36 .\" Added a section on canonical and noncanonical mode.
37 .\" Enhanced the discussion of "raw" mode for cfmakeraw().
38 .\" Document CMSPAR.
39 .\"
40 .TH TERMIOS 3 2014-05-08 "Linux" "Linux Programmer's Manual"
41 .SH NAME
42 termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow,
43 cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \-
44 get and set terminal attributes, line control, get and set baud rate
45 .SH SYNOPSIS
46 .nf
47 .B #include <termios.h>
48 .br
49 .B #include <unistd.h>
50 .sp
51 .BI "int tcgetattr(int " fd ", struct termios *" termios_p );
52 .sp
53 .BI "int tcsetattr(int " fd ", int " optional_actions ,
54 .BI " const struct termios *" termios_p );
55 .sp
56 .BI "int tcsendbreak(int " fd ", int " duration );
57 .sp
58 .BI "int tcdrain(int " fd );
59 .sp
60 .BI "int tcflush(int " fd ", int " queue_selector );
61 .sp
62 .BI "int tcflow(int " fd ", int " action );
63 .sp
64 .BI "void cfmakeraw(struct termios *" termios_p );
65 .sp
66 .BI "speed_t cfgetispeed(const struct termios *" termios_p );
67 .sp
68 .BI "speed_t cfgetospeed(const struct termios *" termios_p );
69 .sp
70 .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed );
71 .sp
72 .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed );
73 .sp
74 .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed );
75 .fi
76 .sp
77 .in -4n
78 Feature Test Macro Requirements for glibc (see
79 .BR feature_test_macros (7)):
80 .in
81 .sp
82 .BR cfsetspeed (),
83 .BR cfmakeraw ():
84 _BSD_SOURCE
85 .SH DESCRIPTION
86 The termios functions describe a general terminal interface that is
87 provided to control asynchronous communications ports.
88 .SS The termios structure
89 .LP
90 Many of the functions described here have a \fItermios_p\fP argument
91 that is a pointer to a \fItermios\fP structure.
92 This structure contains at least the following members:
93 .sp
94 .in +4n
95 .nf
96 tcflag_t c_iflag; /* input modes */
97 tcflag_t c_oflag; /* output modes */
98 tcflag_t c_cflag; /* control modes */
99 tcflag_t c_lflag; /* local modes */
100 cc_t c_cc[NCCS]; /* special characters */
101 .fi
102 .in
103 .PP
104 The values that may be assigned to these fields are described below.
105 In the case of the first four bit-mask fields,
106 the definitions of some of the associated flags that may be set are
107 exposed only if a specific feature test macro (see
108 .BR feature_test_macros (7))
109 is defined, as noted in brackets ("[]").
110 .PP
111 In the descriptions below, "not in POSIX" means that the
112 value is not specified in POSIX.1-2001,
113 and "XSI" means that the value is specified in POSIX.1-2001
114 as part of the XSI extension.
115 .PP
116 \fIc_iflag\fP flag constants:
117 .TP
118 .B IGNBRK
119 Ignore BREAK condition on input.
120 .TP
121 .B BRKINT
122 If \fBIGNBRK\fP is set, a BREAK is ignored.
123 If it is not set
124 but \fBBRKINT\fP is set, then a BREAK causes the input and output
125 queues to be flushed, and if the terminal is the controlling
126 terminal of a foreground process group, it will cause a
127 \fBSIGINT\fP to be sent to this foreground process group.
128 When neither \fBIGNBRK\fP nor \fBBRKINT\fP are set, a BREAK
129 reads as a null byte (\(aq\\0\(aq), except when \fBPARMRK\fP is set,
130 in which case it reads as the sequence \\377 \\0 \\0.
131 .TP
132 .B IGNPAR
133 Ignore framing errors and parity errors.
134 .TP
135 .B PARMRK
136 If \fBIGNPAR\fP is not set, prefix a character with a parity error or
137 framing error with \\377 \\0.
138 If neither \fBIGNPAR\fP nor \fBPARMRK\fP
139 is set, read a character with a parity error or framing error
140 as \\0.
141 .TP
142 .B INPCK
143 Enable input parity checking.
144 .TP
145 .B ISTRIP
146 Strip off eighth bit.
147 .TP
148 .B INLCR
149 Translate NL to CR on input.
150 .TP
151 .B IGNCR
152 Ignore carriage return on input.
153 .TP
154 .B ICRNL
155 Translate carriage return to newline on input (unless \fBIGNCR\fP is set).
156 .TP
157 .B IUCLC
158 (not in POSIX) Map uppercase characters to lowercase on input.
159 .TP
160 .B IXON
161 Enable XON/XOFF flow control on output.
162 .TP
163 .B IXANY
164 (XSI) Typing any character will restart stopped output.
165 (The default is to allow just the START character to restart output.)
166 .TP
167 .B IXOFF
168 Enable XON/XOFF flow control on input.
169 .TP
170 .B IMAXBEL
171 (not in POSIX) Ring bell when input queue is full.
172 Linux does not implement this bit, and acts as if it is always set.
173 .TP
174 .BR IUTF8 " (since Linux 2.6.4)"
175 (not in POSIX) Input is UTF8;
176 this allows character-erase to be correctly performed in cooked mode.
177 .PP
178 .I c_oflag
179 flag constants:
180 .TP
181 .B OPOST
182 Enable implementation-defined output processing.
183 .TP
184 .B OLCUC
185 (not in POSIX) Map lowercase characters to uppercase on output.
186 .TP
187 .B ONLCR
188 (XSI) Map NL to CR-NL on output.
189 .TP
190 .B OCRNL
191 Map CR to NL on output.
192 .TP
193 .B ONOCR
194 Don't output CR at column 0.
195 .TP
196 .B ONLRET
197 Don't output CR.
198 .TP
199 .B OFILL
200 Send fill characters for a delay, rather than using a timed delay.
201 .TP
202 .B OFDEL
203 Fill character is ASCII DEL (0177).
204 If unset, fill character is ASCII NUL (\(aq\\0\(aq).
205 (Not implemented on Linux.)
206 .TP
207 .B NLDLY
208 Newline delay mask.
209 Values are \fBNL0\fP and \fBNL1\fP.
210 [requires
211 .B _BSD_SOURCE
212 or
213 .B _SVID_SOURCE
214 or
215 .BR _XOPEN_SOURCE ]
216 .TP
217 .B CRDLY
218 Carriage return delay mask.
219 Values are \fBCR0\fP, \fBCR1\fP, \fBCR2\fP, or \fBCR3\fP.
220 [requires
221 .B _BSD_SOURCE
222 or
223 .B _SVID_SOURCE
224 or
225 .BR _XOPEN_SOURCE ]
226 .TP
227 .B TABDLY
228 Horizontal tab delay mask.
229 Values are \fBTAB0\fP, \fBTAB1\fP, \fBTAB2\fP, \fBTAB3\fP (or \fBXTABS\fP).
230 A value of TAB3, that is, XTABS, expands tabs to spaces
231 (with tab stops every eight columns).
232 [requires
233 .B _BSD_SOURCE
234 or
235 .B _SVID_SOURCE
236 or
237 .BR _XOPEN_SOURCE ]
238 .TP
239 .B BSDLY
240 Backspace delay mask.
241 Values are \fBBS0\fP or \fBBS1\fP.
242 (Has never been implemented.)
243 [requires
244 .B _BSD_SOURCE
245 or
246 .B _SVID_SOURCE
247 or
248 .BR _XOPEN_SOURCE ]
249 .TP
250 .B VTDLY
251 Vertical tab delay mask.
252 Values are \fBVT0\fP or \fBVT1\fP.
253 .TP
254 .B FFDLY
255 Form feed delay mask.
256 Values are \fBFF0\fP or \fBFF1\fP.
257 [requires
258 .B _BSD_SOURCE
259 or
260 .B _SVID_SOURCE
261 or
262 .BR _XOPEN_SOURCE ]
263 .PP
264 \fIc_cflag\fP flag constants:
265 .TP
266 .B CBAUD
267 (not in POSIX) Baud speed mask (4+1 bits).
268 [requires
269 .B _BSD_SOURCE
270 or
271 .BR _SVID_SOURCE ]
272 .TP
273 .B CBAUDEX
274 (not in POSIX) Extra baud speed mask (1 bit), included in
275 .BR CBAUD .
276 [requires
277 .B _BSD_SOURCE
278 or
279 .BR _SVID_SOURCE ]
280 .sp
281 (POSIX says that the baud speed is stored in the
282 .I termios
283 structure without specifying where precisely, and provides
284 .BR cfgetispeed ()
285 and
286 .BR cfsetispeed ()
287 for getting at it.
288 Some systems use bits selected by
289 .B CBAUD
290 in
291 .IR c_cflag ,
292 other systems use separate fields, for example,
293 .I sg_ispeed
294 and
295 .IR sg_ospeed .)
296 .TP
297 .B CSIZE
298 Character size mask.
299 Values are \fBCS5\fP, \fBCS6\fP, \fBCS7\fP, or \fBCS8\fP.
300 .TP
301 .B CSTOPB
302 Set two stop bits, rather than one.
303 .TP
304 .B CREAD
305 Enable receiver.
306 .TP
307 .B PARENB
308 Enable parity generation on output and parity checking for input.
309 .TP
310 .B PARODD
311 If set, then parity for input and output is odd;
312 otherwise even parity is used.
313 .TP
314 .B HUPCL
315 Lower modem control lines after last process closes the device (hang up).
316 .TP
317 .B CLOCAL
318 Ignore modem control lines.
319 .TP
320 .B LOBLK
321 (not in POSIX) Block output from a noncurrent shell layer.
322 For use by \fBshl\fP (shell layers). (Not implemented on Linux.)
323 .TP
324 .B CIBAUD
325 (not in POSIX) Mask for input speeds.
326 The values for the
327 .B CIBAUD
328 bits are
329 the same as the values for the
330 .B CBAUD
331 bits, shifted left
332 .B IBSHIFT
333 bits.
334 [requires
335 .B _BSD_SOURCE
336 or
337 .BR _SVID_SOURCE ]
338 (Not implemented on Linux.)
339 .TP
340 .B CMSPAR
341 (not in POSIX)
342 Use "stick" (mark/space) parity (supported on certain serial
343 devices): if
344 .B PARODD
345 is set, the parity bit is always 1; if
346 .B PARODD
347 is not set, then the parity bit is always 0.
348 [requires
349 .B _BSD_SOURCE
350 or
351 .BR _SVID_SOURCE ]
352 .TP
353 .B CRTSCTS
354 (not in POSIX) Enable RTS/CTS (hardware) flow control.
355 [requires
356 .B _BSD_SOURCE
357 or
358 .BR _SVID_SOURCE ]
359 .PP
360 \fIc_lflag\fP flag constants:
361 .TP
362 .B ISIG
363 When any of the characters INTR, QUIT, SUSP, or DSUSP are received,
364 generate the corresponding signal.
365 .TP
366 .B ICANON
367 Enable canonical mode (described below).
368 .TP
369 .B XCASE
370 (not in POSIX; not supported under Linux)
371 If \fBICANON\fP is also set, terminal is uppercase only.
372 Input is converted to lowercase, except for characters preceded by \\.
373 On output, uppercase characters are preceded by \\ and lowercase
374 characters are converted to uppercase.
375 [requires
376 .B _BSD_SOURCE
377 or
378 .B _SVID_SOURCE
379 or
380 .BR _XOPEN_SOURCE ]
381 .\" glibc is probably now wrong to allow
382 .\" Define
383 .\" .B _XOPEN_SOURCE
384 .\" to expose
385 .\" .BR XCASE .
386 .TP
387 .B ECHO
388 Echo input characters.
389 .TP
390 .B ECHOE
391 If \fBICANON\fP is also set, the ERASE character erases the preceding
392 input character, and WERASE erases the preceding word.
393 .TP
394 .B ECHOK
395 If \fBICANON\fP is also set, the KILL character erases the current line.
396 .TP
397 .B ECHONL
398 If \fBICANON\fP is also set, echo the NL character even if ECHO is not set.
399 .TP
400 .B ECHOCTL
401 (not in POSIX) If \fBECHO\fP is also set,
402 terminal special characters other than
403 TAB, NL, START, and STOP are echoed as \fB^X\fP,
404 where X is the character with
405 ASCII code 0x40 greater than the special character.
406 For example, character
407 0x08 (BS) is echoed as \fB^H\fP.
408 [requires
409 .B _BSD_SOURCE
410 or
411 .BR _SVID_SOURCE ]
412 .TP
413 .B ECHOPRT
414 (not in POSIX) If \fBICANON\fP and \fBECHO\fP are also set, characters
415 are printed as they are being erased.
416 [requires
417 .B _BSD_SOURCE
418 or
419 .BR _SVID_SOURCE ]
420 .TP
421 .B ECHOKE
422 (not in POSIX) If \fBICANON\fP is also set, KILL is echoed by erasing
423 each character on the line, as specified by \fBECHOE\fP and \fBECHOPRT\fP.
424 [requires
425 .B _BSD_SOURCE
426 or
427 .BR _SVID_SOURCE ]
428 .TP
429 .B DEFECHO
430 (not in POSIX) Echo only when a process is reading.
431 (Not implemented on Linux.)
432 .TP
433 .B FLUSHO
434 (not in POSIX; not supported under Linux)
435 Output is being flushed.
436 This flag is toggled by typing
437 the DISCARD character.
438 [requires
439 .B _BSD_SOURCE
440 or
441 .BR _SVID_SOURCE ]
442 .TP
443 .B NOFLSH
444 Disable flushing the input and output queues when generating signals for the
445 INT, QUIT, and SUSP characters.
446 .\" Stevens lets SUSP only flush the input queue
447 .TP
448 .B TOSTOP
449 Send the
450 .B SIGTTOU
451 signal to the process group of a background process
452 which tries to write to its controlling terminal.
453 .TP
454 .B PENDIN
455 (not in POSIX; not supported under Linux)
456 All characters in the input queue are reprinted when
457 the next character is read.
458 .RB ( bash (1)
459 handles typeahead this way.)
460 [requires
461 .B _BSD_SOURCE
462 or
463 .BR _SVID_SOURCE ]
464 .TP
465 .B IEXTEN
466 Enable implementation-defined input processing.
467 This flag, as well as \fBICANON\fP must be enabled for the
468 special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted,
469 and for the \fBIUCLC\fP flag to be effective.
470 .PP
471 The \fIc_cc\fP array defines the terminal special characters.
472 The symbolic indices (initial values) and meaning are:
473 .TP
474 .B VDISCARD
475 (not in POSIX; not supported under Linux; 017, SI, Ctrl-O)
476 Toggle: start/stop discarding pending output.
477 Recognized when
478 .B IEXTEN
479 is set, and then not passed as input.
480 .TP
481 .B VDSUSP
482 (not in POSIX; not supported under Linux; 031, EM, Ctrl-Y)
483 Delayed suspend character (DSUSP):
484 send
485 .B SIGTSTP
486 signal when the character is read by the user program.
487 Recognized when
488 .B IEXTEN
489 and
490 .B ISIG
491 are set, and the system supports
492 job control, and then not passed as input.
493 .TP
494 .B VEOF
495 (004, EOT, Ctrl-D)
496 End-of-file character (EOF).
497 More precisely: this character causes the pending tty buffer to be sent
498 to the waiting user program without waiting for end-of-line.
499 If it is the first character of the line, the
500 .BR read (2)
501 in the user program returns 0, which signifies end-of-file.
502 Recognized when
503 .B ICANON
504 is set, and then not passed as input.
505 .TP
506 .B VEOL
507 (0, NUL)
508 Additional end-of-line character (EOL).
509 Recognized when
510 .B ICANON
511 is set.
512 .TP
513 .B VEOL2
514 (not in POSIX; 0, NUL)
515 Yet another end-of-line character (EOL2).
516 Recognized when
517 .B ICANON
518 is set.
519 .TP
520 .B VERASE
521 (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #)
522 Erase character (ERASE).
523 This erases the previous not-yet-erased character,
524 but does not erase past EOF or beginning-of-line.
525 Recognized when
526 .B ICANON
527 is set, and then not passed as input.
528 .TP
529 .B VINTR
530 (003, ETX, Ctrl-C, or also 0177, DEL, rubout)
531 Interrupt character (INTR).
532 Send a
533 .B SIGINT
534 signal.
535 Recognized when
536 .B ISIG
537 is set, and then not passed as input.
538 .TP
539 .B VKILL
540 (025, NAK, Ctrl-U, or Ctrl-X, or also @)
541 Kill character (KILL).
542 This erases the input since the last EOF or beginning-of-line.
543 Recognized when
544 .B ICANON
545 is set, and then not passed as input.
546 .TP
547 .B VLNEXT
548 (not in POSIX; 026, SYN, Ctrl-V)
549 Literal next (LNEXT).
550 Quotes the next input character, depriving it of
551 a possible special meaning.
552 Recognized when
553 .B IEXTEN
554 is set, and then not passed as input.
555 .TP
556 .B VMIN
557 Minimum number of characters for noncanonical read (MIN).
558 .TP
559 .B VQUIT
560 (034, FS, Ctrl-\e)
561 Quit character (QUIT).
562 Send
563 .B SIGQUIT
564 signal.
565 Recognized when
566 .B ISIG
567 is set, and then not passed as input.
568 .TP
569 .B VREPRINT
570 (not in POSIX; 022, DC2, Ctrl-R)
571 Reprint unread characters (REPRINT).
572 Recognized when
573 .B ICANON
574 and
575 .B IEXTEN
576 are set, and then not passed as input.
577 .TP
578 .B VSTART
579 (021, DC1, Ctrl-Q)
580 Start character (START).
581 Restarts output stopped by the Stop character.
582 Recognized when
583 .B IXON
584 is set, and then not passed as input.
585 .TP
586 .B VSTATUS
587 (not in POSIX; not supported under Linux;
588 status request: 024, DC4, Ctrl-T).
589 Status character (STATUS).
590 Display status information at terminal,
591 including state of foreground process and amount of CPU time it has consumed.
592 Also sends a
593 .BR SIGINFO
594 signal (not supported on Linux) to the foreground process group.
595 .TP
596 .B VSTOP
597 (023, DC3, Ctrl-S)
598 Stop character (STOP).
599 Stop output until Start character typed.
600 Recognized when
601 .B IXON
602 is set, and then not passed as input.
603 .TP
604 .B VSUSP
605 (032, SUB, Ctrl-Z)
606 Suspend character (SUSP).
607 Send
608 .B SIGTSTP
609 signal.
610 Recognized when
611 .B ISIG
612 is set, and then not passed as input.
613 .TP
614 .B VSWTCH
615 (not in POSIX; not supported under Linux; 0, NUL)
616 Switch character (SWTCH).
617 Used in System V to switch shells in
618 .IR "shell layers" ,
619 a predecessor to shell job control.
620 .TP
621 .B VTIME
622 Timeout in deciseconds for noncanonical read (TIME).
623 .TP
624 .B VWERASE
625 (not in POSIX; 027, ETB, Ctrl-W)
626 Word erase (WERASE).
627 Recognized when
628 .B ICANON
629 and
630 .B IEXTEN
631 are set, and then not passed as input.
632 .LP
633 An individual terminal special character can be disabled by setting
634 the value of the corresponding
635 .I c_cc
636 element to
637 .BR _POSIX_VDISABLE .
638 .LP
639 The above symbolic subscript values are all different, except that
640 .BR VTIME ,
641 .B VMIN
642 may have the same value as
643 .BR VEOL ,
644 .BR VEOF ,
645 respectively.
646 In noncanonical mode the special character meaning is replaced
647 by the timeout meaning.
648 For an explanation of
649 .B VMIN
650 and
651 .BR VTIME ,
652 see the description of
653 noncanonical mode below.
654 .SS Retrieving and changing terminal settings
655 .PP
656 .BR tcgetattr ()
657 gets the parameters associated with the object referred by \fIfd\fP and
658 stores them in the \fItermios\fP structure referenced by
659 \fItermios_p\fP.
660 This function may be invoked from a background process;
661 however, the terminal attributes may be subsequently changed by a
662 foreground process.
663 .LP
664 .BR tcsetattr ()
665 sets the parameters associated with the terminal (unless support is
666 required from the underlying hardware that is not available) from the
667 \fItermios\fP structure referred to by \fItermios_p\fP.
668 \fIoptional_actions\fP specifies when the changes take effect:
669 .IP \fBTCSANOW\fP
670 the change occurs immediately.
671 .IP \fBTCSADRAIN\fP
672 the change occurs after all output written to
673 .I fd
674 has been transmitted.
675 This option should be used when changing
676 parameters that affect output.
677 .IP \fBTCSAFLUSH\fP
678 the change occurs after all output written to the object referred by
679 .I fd
680 has been transmitted, and all input that has been received but not read
681 will be discarded before the change is made.
682 .SS Canonical and noncanonical mode
683 The setting of the
684 .B ICANON
685 canon flag in
686 .I c_lflag
687 determines whether the terminal is operating in canonical mode
688 .RB ( ICANON
689 set) or
690 noncanonical mode
691 .RB ( ICANON
692 unset).
693 By default,
694 .B ICANON
695 set.
697 In canonical mode:
698 .IP * 2
699 Input is made available line by line.
700 An input line is available when one of the line delimiters
701 is typed (NL, EOL, EOL2; or EOF at the start of line).
702 Except in the case of EOF, the line delimiter is included
703 in the buffer returned by
704 .BR read (2).
705 .IP * 2
706 Line editing is enabled (ERASE, KILL;
707 and if the
708 .B IEXTEN
709 flag is set: WERASE, REPRINT, LNEXT).
710 A
711 .BR read (2)
712 returns at most one line of input; if the
713 .BR read (2)
714 requested fewer bytes than are available in the current line of input,
715 then only as many bytes as requested are read,
716 and the remaining characters will be available for a future
717 .BR read (2).
718 .PP
719 In noncanonical mode input is available immediately (without
720 the user having to type a line-delimiter character),
721 no input processing is performed,
722 and line editing is disabled.
723 The settings of MIN
724 .RI ( c_cc[VMIN] )
725 and TIME
726 .RI ( c_cc[VTIME] )
727 determine the circumstances in which a
728 .BR read (2)
729 completes; there are four distinct cases:
730 .TP
731 MIN == 0, TIME == 0 (polling read)
732 If data is available,
733 .BR read (2)
734 returns immediately, with the lesser of the number of bytes
735 available, or the number of bytes requested.
736 If no data is available,
737 .BR read (2)
738 returns 0.
739 .TP
740 MIN > 0, TIME == 0 (blocking read)
741 .BR read (2)
742 blocks until MIN bytes are available,
743 and returns up to the number of bytes requested.
744 .TP
745 MIN == 0, TIME > 0 (read with timeout)
746 TIME specifies the limit for a timer in tenths of a second.
747 The timer is started when
748 .BR read (2)
749 is called.
750 .BR read (2)
751 returns either when at least one byte of data is available,
752 or when the timer expires.
753 If the timer expires without any input becoming available,
754 .BR read (2)
755 returns 0.
756 If data is already available at the time of the call to
757 .BR read (2),
758 the call behaves as though the data was received immediately after the call.
759 .TP
760 MIN > 0, TIME > 0 (read with interbyte timeout)
761 TIME specifies the limit for a timer in tenths of a second.
762 Once an initial byte of input becomes available,
763 the timer is restarted after each further byte is received.
764 .BR read (2)
765 returns when any of the following conditions is met:
766 .RS
767 .IP * 3
768 MIN bytes have been received.
769 .IP *
770 The interbyte timer expires.
771 .IP *
772 The number of bytes requested by
773 .BR read (2)
774 has been received.
775 (POSIX does not specify this termination condition,
776 and on some other implementations
777 .\" e.g., Solaris
778 .BR read (2)
779 does not return in this case.)
780 .RE
781 .IP
782 Because the timer is started only after the initial byte
783 becomes available, at least one byte will be read.
784 If data is already available at the time of the call to
785 .BR read (2),
786 the call behaves as though the data was received immediately after the call.
787 .PP
788 POSIX
789 .\" POSIX.1-2008 XBD 11.1.7
790 does not specify whether the setting of the
791 .B O_NONBLOCK
792 file status flag takes precedence over the MIN and TIME settings.
793 If
794 .B O_NONBLOCK
795 is set, a
796 .BR read (2)
797 in noncanonical mode may return immediately,
798 regardless of the setting of MIN or TIME.
799 Furthermore, if no data is available,
800 POSIX permits a
801 .BR read (2)
802 in noncanonical mode to return either 0, or \-1 with
803 .I errno
804 set to
805 .BR EAGAIN .
806 .SS Raw mode
807 .LP
808 .BR cfmakeraw ()
809 sets the terminal to something like the
810 "raw" mode of the old Version 7 terminal driver:
811 input is available character by character,
812 echoing is disabled, and all special processing of
813 terminal input and output characters is disabled.
814 The terminal attributes are set as follows:
815 .nf
817 termios_p\->c_iflag &= ~(IGNBRK | BRKINT | PARMRK | ISTRIP
818 | INLCR | IGNCR | ICRNL | IXON);
819 termios_p\->c_oflag &= ~OPOST;
820 termios_p\->c_lflag &= ~(ECHO | ECHONL | ICANON | ISIG | IEXTEN);
821 termios_p\->c_cflag &= ~(CSIZE | PARENB);
822 termios_p\->c_cflag |= CS8;
823 .fi
824 .SS Line control
825 .LP
826 .BR tcsendbreak ()
827 transmits a continuous stream of zero-valued bits for a specific
828 duration, if the terminal is using asynchronous serial data
829 transmission.
830 If \fIduration\fP is zero, it transmits zero-valued bits
831 for at least 0.25 seconds, and not more that 0.5 seconds.
832 If \fIduration\fP is not zero, it sends zero-valued bits for some
833 implementation-defined length of time.
834 .LP
835 If the terminal is not using asynchronous serial data transmission,
836 .BR tcsendbreak ()
837 returns without taking any action.
838 .LP
839 .BR tcdrain ()
840 waits until all output written to the object referred to by
841 .I fd
842 has been transmitted.
843 .LP
844 .BR tcflush ()
845 discards data written to the object referred to by
846 .I fd
847 but not transmitted, or data received but not read, depending on the
848 value of
849 .IR queue_selector :
850 .IP \fBTCIFLUSH\fP
851 flushes data received but not read.
852 .IP \fBTCOFLUSH\fP
853 flushes data written but not transmitted.
854 .IP \fBTCIOFLUSH\fP
855 flushes both data received but not read, and data written but not
856 transmitted.
857 .LP
858 .BR tcflow ()
859 suspends transmission or reception of data on the object referred to by
860 .IR fd ,
861 depending on the value of
862 .IR action :
863 .IP \fBTCOOFF\fP
864 suspends output.
865 .IP \fBTCOON\fP
866 restarts suspended output.
867 .IP \fBTCIOFF\fP
868 transmits a STOP character, which stops the terminal device from
869 transmitting data to the system.
870 .IP \fBTCION\fP
871 transmits a START character, which starts the terminal device
872 transmitting data to the system.
873 .LP
874 The default on open of a terminal file is that neither its input nor its
875 output is suspended.
876 .SS Line speed
877 The baud rate functions are provided for getting and setting the values
878 of the input and output baud rates in the \fItermios\fP structure.
879 The new values do not take effect
880 until
881 .BR tcsetattr ()
882 is successfully called.
884 Setting the speed to \fBB0\fP instructs the modem to "hang up".
885 The actual bit rate corresponding to \fBB38400\fP may be altered with
886 .BR setserial (8).
887 .LP
888 The input and output baud rates are stored in the \fItermios\fP
889 structure.
890 .LP
891 .BR cfgetospeed ()
892 returns the output baud rate stored in the \fItermios\fP structure
893 pointed to by
894 .IR termios_p .
895 .LP
896 .BR cfsetospeed ()
897 sets the output baud rate stored in the \fItermios\fP structure pointed
898 to by \fItermios_p\fP to \fIspeed\fP, which must be one of these constants:
899 .nf
901 .ft B
902 B0
903 B50
904 B75
905 B110
906 B134
907 B150
908 B200
909 B300
910 B600
911 B1200
912 B1800
913 B2400
914 B4800
915 B9600
916 B19200
917 B38400
918 B57600
919 B115200
920 B230400
921 .ft P
923 .fi
924 The zero baud rate, \fBB0\fP,
925 is used to terminate the connection.
926 If B0 is specified, the modem control lines shall no longer be asserted.
927 Normally, this will disconnect the line.
928 \fBCBAUDEX\fP is a mask
929 for the speeds beyond those defined in POSIX.1 (57600 and above).
930 Thus, \fBB57600\fP & \fBCBAUDEX\fP is nonzero.
931 .LP
932 .BR cfgetispeed ()
933 returns the input baud rate stored in the \fItermios\fP structure.
934 .LP
935 .BR cfsetispeed ()
936 sets the input baud rate stored in the \fItermios\fP structure to
937 .IR speed ,
938 which must be specified as one of the \fBBnnn\fP constants listed above for
939 .BR cfsetospeed ().
940 If the input baud rate is set to zero, the input baud rate will be
941 equal to the output baud rate.
942 .LP
943 .BR cfsetspeed ()
944 is a 4.4BSD extension.
945 It takes the same arguments as
946 .BR cfsetispeed (),
947 and sets both input and output speed.
948 .SH RETURN VALUE
949 .LP
950 .BR cfgetispeed ()
951 returns the input baud rate stored in the
952 \fItermios\fP
953 structure.
954 .LP
955 .BR cfgetospeed ()
956 returns the output baud rate stored in the \fItermios\fP structure.
957 .LP
958 All other functions return:
959 .IP 0
960 on success.
961 .IP \-1
962 on failure and set
963 .I errno
964 to indicate the error.
965 .LP
966 Note that
967 .BR tcsetattr ()
968 returns success if \fIany\fP of the requested changes could be
969 successfully carried out.
970 Therefore, when making multiple changes
971 it may be necessary to follow this call with a further call to
972 .BR tcgetattr ()
973 to check that all changes have been performed successfully.
974 .SH ATTRIBUTES
975 .SS Multithreading (see pthreads(7))
976 The
977 .BR tcgetattr (),
978 .BR tcsetattr (),
979 .BR tcsendbreak (),
980 .BR tcdrain (),
981 .BR tcflush (),
982 .BR tcflow (),
983 .BR cfmakeraw (),
984 .BR cfgetispeed (),
985 .BR cfgetospeed (),
986 .BR cfsetispeed (),
987 .BR cfsetospeed (),
988 and
989 .BR cfsetspeed ()
990 functions are thread-safe.
991 .SH CONFORMING TO
992 .BR tcgetattr (),
993 .BR tcsetattr (),
994 .BR tcsendbreak (),
995 .BR tcdrain (),
996 .BR tcflush (),
997 .BR tcflow (),
998 .BR cfgetispeed (),
999 .BR cfgetospeed (),
1000 .BR cfsetispeed (),
1001 and
1002 .BR cfsetospeed ()
1003 are specified in POSIX.1-2001.
1005 .BR cfmakeraw ()
1006 and
1007 .BR cfsetspeed ()
1008 are nonstandard, but available on the BSDs.
1009 .SH NOTES
1010 UNIX\ V7 and several later systems have a list of baud rates
1011 where after the fourteen values B0, ..., B9600 one finds the
1012 two constants EXTA, EXTB ("External A" and "External B").
1013 Many systems extend the list with much higher baud rates.
1014 .LP
1015 The effect of a nonzero \fIduration\fP with
1016 .BR tcsendbreak ()
1017 varies.
1018 SunOS specifies a break of
1019 .I "duration\ *\ N"
1020 seconds, where \fIN\fP is at least 0.25, and not more than 0.5.
1021 Linux, AIX, DU, Tru64 send a break of
1022 .I duration
1023 milliseconds.
1024 FreeBSD and NetBSD and HP-UX and MacOS ignore the value of
1025 .IR duration .
1026 Under Solaris and UnixWare,
1027 .BR tcsendbreak ()
1028 with nonzero
1029 .I duration
1030 behaves like
1031 .BR tcdrain ().
1032 .\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0.
1033 .\" libc4.7.6, libc5, glibc for unix: duration in ms.
1034 .\" glibc for bsd: duration in us
1035 .\" glibc for sunos4: ignore duration
1036 .SH SEE ALSO
1037 .BR stty (1),
1038 .BR console_ioctl (4),
1039 .BR tty_ioctl (4),
1040 .BR setserial (8)