Debian Codegraph @

upstream/debian-unstable/man3/termios.3

raw
1 '\" t
2 .\" Copyright 2006-2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH termios 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 termios, tcgetattr, tcsetattr, tcsendbreak, tcdrain, tcflush, tcflow,
10 cfmakeraw, cfgetospeed, cfgetispeed, cfsetispeed, cfsetospeed, cfsetspeed \-
11 get and set terminal attributes, line control, get and set baud rate
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .B #include <termios.h>
18 .B #include <unistd.h>
19 .P
20 .BI "int tcgetattr(int " fd ", struct termios *" termios_p );
21 .BI "int tcsetattr(int " fd ", int " optional_actions ,
22 .BI " const struct termios *" termios_p );
23 .P
24 .BI "int tcsendbreak(int " fd ", int " duration );
25 .BI "int tcdrain(int " fd );
26 .BI "int tcflush(int " fd ", int " queue_selector );
27 .BI "int tcflow(int " fd ", int " action );
28 .P
29 .BI "void cfmakeraw(struct termios *" termios_p );
30 .P
31 .BI "speed_t cfgetispeed(const struct termios *" termios_p );
32 .BI "speed_t cfgetospeed(const struct termios *" termios_p );
33 .P
34 .BI "int cfsetispeed(struct termios *" termios_p ", speed_t " speed );
35 .BI "int cfsetospeed(struct termios *" termios_p ", speed_t " speed );
36 .BI "int cfsetspeed(struct termios *" termios_p ", speed_t " speed );
37 .fi
38 .P
39 .RS -4
40 Feature Test Macro Requirements for glibc (see
41 .BR feature_test_macros (7)):
42 .RE
43 .P
44 .BR cfsetspeed (),
45 .BR cfmakeraw ():
46 .nf
47 Since glibc 2.19:
48 _DEFAULT_SOURCE
49 glibc 2.19 and earlier:
50 _BSD_SOURCE
51 .fi
52 .SH DESCRIPTION
53 The termios functions describe a general terminal interface that is
54 provided to control asynchronous communications ports.
55 .SS The termios structure
56 Many of the functions described here have a
57 .I termios_p
58 argument
59 that is a pointer to a
60 .I termios
61 structure.
62 This structure contains at least the following members:
63 .P
64 .in +4n
65 .EX
66 tcflag_t c_iflag; /* input modes */
67 tcflag_t c_oflag; /* output modes */
68 tcflag_t c_cflag; /* control modes */
69 tcflag_t c_lflag; /* local modes */
70 cc_t c_cc[NCCS]; /* special characters */
71 .EE
72 .in
73 .P
74 The values that may be assigned to these fields are described below.
75 In the case of the first four bit-mask fields,
76 the definitions of some of the associated flags that may be set are
77 exposed only if a specific feature test macro (see
78 .BR feature_test_macros (7))
79 is defined, as noted in brackets ("[]").
80 .P
81 In the descriptions below, "not in POSIX" means that the
82 value is not specified in POSIX.1-2001,
83 and "XSI" means that the value is specified in POSIX.1-2001
84 as part of the XSI extension.
85 .P
86 .I c_iflag
87 flag constants:
88 .TP
89 .B IGNBRK
90 Ignore BREAK condition on input.
91 .TP
92 .B BRKINT
93 If
94 .B IGNBRK
95 is set, a BREAK is ignored.
96 If it is not set
97 but
98 .B BRKINT
99 is set, then a BREAK causes the input and output
100 queues to be flushed, and if the terminal is the controlling
101 terminal of a foreground process group, it will cause a
102 .B SIGINT
103 to be sent to this foreground process group.
104 When neither
105 .B IGNBRK
106 nor
107 .B BRKINT
108 are set, a BREAK
109 reads as a null byte
110 .RB ( \[aq]\[rs]0\[aq] ),
111 except when
112 .B PARMRK
113 is set,
114 in which case it reads as the sequence \[rs]377 \[rs]0 \[rs]0.
115 .TP
116 .B IGNPAR
117 Ignore framing errors and parity errors.
118 .TP
119 .B PARMRK
120 If this bit is set, input bytes with parity or framing errors are
121 marked when passed to the program.
122 This bit is meaningful only when
123 .B INPCK
124 is set and
125 .B IGNPAR
126 is not set.
127 The way erroneous bytes are marked is with two preceding bytes,
128 \[rs]377 and \[rs]0.
129 Thus, the program actually reads three bytes for one
130 erroneous byte received from the terminal.
131 If a valid byte has the value \[rs]377,
132 and
133 .B ISTRIP
134 (see below) is not set,
135 the program might confuse it with the prefix that marks a
136 parity error.
137 Therefore, a valid byte \[rs]377 is passed to the program as two
138 bytes, \[rs]377 \[rs]377, in this case.
139 .IP
140 If neither
141 .B IGNPAR
142 nor
143 .B PARMRK
144 is set, read a character with a parity error or framing error
145 as \[rs]0.
146 .TP
147 .B INPCK
148 Enable input parity checking.
149 .TP
150 .B ISTRIP
151 Strip off eighth bit.
152 .TP
153 .B INLCR
154 Translate NL to CR on input.
155 .TP
156 .B IGNCR
157 Ignore carriage return on input.
158 .TP
159 .B ICRNL
160 Translate carriage return to newline on input (unless
161 .B IGNCR
162 is set).
163 .TP
164 .B IUCLC
165 (not in POSIX) Map uppercase characters to lowercase on input.
166 .TP
167 .B IXON
168 Enable XON/XOFF flow control on output.
169 .TP
170 .B IXANY
171 (XSI) Typing any character will restart stopped output.
172 (The default is to allow just the START character to restart output.)
173 .TP
174 .B IXOFF
175 Enable XON/XOFF flow control on input.
176 .TP
177 .B IMAXBEL
178 (not in POSIX) Ring bell when input queue is full.
179 Linux does not implement this bit, and acts as if it is always set.
180 .TP
181 .BR IUTF8 " (since Linux 2.6.4)"
182 (not in POSIX) Input is UTF8;
183 this allows character-erase to be correctly performed in cooked mode.
184 .P
185 .I c_oflag
186 flag constants:
187 .TP
188 .B OPOST
189 Enable implementation-defined output processing.
190 .TP
191 .B OLCUC
192 (not in POSIX) Map lowercase characters to uppercase on output.
193 .TP
194 .B ONLCR
195 (XSI) Map NL to CR-NL on output.
196 .TP
197 .B OCRNL
198 Map CR to NL on output.
199 .TP
200 .B ONOCR
201 Don't output CR at column 0.
202 .TP
203 .B ONLRET
204 The NL character is assumed to do the carriage-return function;
205 the kernel's idea of the current column is set to 0
206 after both NL and CR.
207 .TP
208 .B OFILL
209 Send fill characters for a delay, rather than using a timed delay.
210 .TP
211 .B OFDEL
212 Fill character is ASCII DEL (0177).
213 If unset, fill character is ASCII NUL (\[aq]\[rs]0\[aq]).
214 (Not implemented on Linux.)
215 .TP
216 .B NLDLY
217 Newline delay mask.
218 Values are
219 .B NL0
220 and
221 .BR NL1 .
222 [requires
223 .B _BSD_SOURCE
224 or
225 .B _SVID_SOURCE
226 or
227 .BR _XOPEN_SOURCE ]
228 .TP
229 .B CRDLY
230 Carriage return delay mask.
231 Values are
232 .BR CR0 ,
233 .BR CR1 ,
234 .BR CR2 ,
235 or
236 .BR CR3 .
237 [requires
238 .B _BSD_SOURCE
239 or
240 .B _SVID_SOURCE
241 or
242 .BR _XOPEN_SOURCE ]
243 .TP
244 .B TABDLY
245 Horizontal tab delay mask.
246 Values are
247 .BR TAB0 ,
248 .BR TAB1 ,
249 .BR TAB2 ,
250 .B TAB3
251 (or
252 .BR XTABS ,
253 but see the
254 .B BUGS
255 section).
256 A value of TAB3, that is, XTABS, expands tabs to spaces
257 (with tab stops every eight columns).
258 [requires
259 .B _BSD_SOURCE
260 or
261 .B _SVID_SOURCE
262 or
263 .BR _XOPEN_SOURCE ]
264 .TP
265 .B BSDLY
266 Backspace delay mask.
267 Values are
268 .B BS0
269 or
270 .BR BS1 .
271 (Has never been implemented.)
272 [requires
273 .B _BSD_SOURCE
274 or
275 .B _SVID_SOURCE
276 or
277 .BR _XOPEN_SOURCE ]
278 .TP
279 .B VTDLY
280 Vertical tab delay mask.
281 Values are
282 .B VT0
283 or
284 .BR VT1 .
285 .TP
286 .B FFDLY
287 Form feed delay mask.
288 Values are
289 .B FF0
290 or
291 .BR FF1 .
292 [requires
293 .B _BSD_SOURCE
294 or
295 .B _SVID_SOURCE
296 or
297 .BR _XOPEN_SOURCE ]
298 .P
299 .I c_cflag
300 flag constants:
301 .TP
302 .B CBAUD
303 (not in POSIX) Baud speed mask (4+1 bits).
304 [requires
305 .B _BSD_SOURCE
306 or
307 .BR _SVID_SOURCE ]
308 .TP
309 .B CBAUDEX
310 (not in POSIX) Extra baud speed mask (1 bit), included in
311 .BR CBAUD .
312 [requires
313 .B _BSD_SOURCE
314 or
315 .BR _SVID_SOURCE ]
316 .IP
317 (POSIX says that the baud speed is stored in the
318 .I termios
319 structure without specifying where precisely, and provides
320 .BR cfgetispeed ()
321 and
322 .BR cfsetispeed ()
323 for getting at it.
324 Some systems use bits selected by
325 .B CBAUD
326 in
327 .IR c_cflag ,
328 other systems use separate fields, for example,
329 .I sg_ispeed
330 and
331 .IR sg_ospeed .)
332 .TP
333 .B CSIZE
334 Character size mask.
335 Values are
336 .BR CS5 ,
337 .BR CS6 ,
338 .BR CS7 ,
339 or
340 .BR CS8 .
341 .TP
342 .B CSTOPB
343 Set two stop bits, rather than one.
344 .TP
345 .B CREAD
346 Enable receiver.
347 .TP
348 .B PARENB
349 Enable parity generation on output and parity checking for input.
350 .TP
351 .B PARODD
352 If set, then parity for input and output is odd;
353 otherwise even parity is used.
354 .TP
355 .B HUPCL
356 Lower modem control lines after last process closes the device (hang up).
357 .TP
358 .B CLOCAL
359 Ignore modem control lines.
360 .TP
361 .B LOBLK
362 (not in POSIX) Block output from a noncurrent shell layer.
363 For use by
364 .B shl
365 (shell layers).
366 (Not implemented on Linux.)
367 .TP
368 .B CIBAUD
369 (not in POSIX) Mask for input speeds.
370 The values for the
371 .B CIBAUD
372 bits are
373 the same as the values for the
374 .B CBAUD
375 bits, shifted left
376 .B IBSHIFT
377 bits.
378 [requires
379 .B _BSD_SOURCE
380 or
381 .BR _SVID_SOURCE ]
382 (Not implemented in glibc, supported on Linux via
383 .BR TCGET *
384 and
385 .BR TCSET *
386 ioctls;
387 see
388 .BR ioctl_tty (2))
389 .TP
390 .B CMSPAR
391 (not in POSIX)
392 Use "stick" (mark/space) parity
393 (supported on certain serial devices):
394 if
395 .B PARODD
396 is set,
397 the parity bit is always 1;
398 if
399 .B PARODD
400 is not set,
401 then the parity bit is always 0.
402 [requires
403 .B _BSD_SOURCE
404 or
405 .BR _SVID_SOURCE ]
406 .TP
407 .B CRTSCTS
408 (not in POSIX)
409 Enable RTS/CTS (hardware) flow control.
410 [requires
411 .B _BSD_SOURCE
412 or
413 .BR _SVID_SOURCE ]
414 .P
415 .I c_lflag
416 flag constants:
417 .TP
418 .B ISIG
419 When any of the characters INTR, QUIT, SUSP, or DSUSP are received,
420 generate the corresponding signal.
421 .TP
422 .B ICANON
423 Enable canonical mode (described below).
424 .TP
425 .B XCASE
426 (not in POSIX;
427 not supported under Linux)
428 If
429 .B ICANON
430 is also set,
431 terminal is uppercase only.
432 Input is converted to lowercase,
433 except for characters preceded by \[rs].
434 On output,
435 uppercase characters are preceded by \[rs]
436 and lowercase characters are converted to uppercase.
437 [requires
438 .B _BSD_SOURCE
439 or
440 .B _SVID_SOURCE
441 or
442 .BR _XOPEN_SOURCE ]
443 .\" glibc is probably now wrong to allow
444 .\" Define
445 .\" .B _XOPEN_SOURCE
446 .\" to expose
447 .\" .BR XCASE .
448 .TP
449 .B ECHO
450 Echo input characters.
451 .TP
452 .B ECHOE
453 If
454 .B ICANON
455 is also set, the ERASE character erases the preceding
456 input character, and WERASE erases the preceding word.
457 .TP
458 .B ECHOK
459 If
460 .B ICANON
461 is also set, the KILL character erases the current line.
462 .TP
463 .B ECHONL
464 If
465 .B ICANON
466 is also set, echo the NL character even if ECHO is not set.
467 .TP
468 .B ECHOCTL
469 (not in POSIX)
470 If
471 .B ECHO
472 is also set,
473 terminal special characters other than
474 TAB, NL, START, and STOP are echoed as
475 .BR \[ha]X ,
476 where X is the character with
477 ASCII code 0x40 greater than the special character.
478 For example, character
479 0x08 (BS) is echoed as
480 .BR \[ha]H .
481 [requires
482 .B _BSD_SOURCE
483 or
484 .BR _SVID_SOURCE ]
485 .TP
486 .B ECHOPRT
487 (not in POSIX) If
488 .B ICANON
489 and
490 .B ECHO
491 are also set,
492 characters are printed as they are being erased.
493 [requires
494 .B _BSD_SOURCE
495 or
496 .BR _SVID_SOURCE ]
497 .TP
498 .B ECHOKE
499 (not in POSIX) If
500 .B ICANON
501 is also set,
502 KILL is echoed by erasing
503 each character on the line,
504 as specified by
505 .B ECHOE
506 and
507 .BR ECHOPRT .
508 [requires
509 .B _BSD_SOURCE
510 or
511 .BR _SVID_SOURCE ]
512 .TP
513 .B DEFECHO
514 (not in POSIX)
515 Echo only when a process is reading.
516 (Not implemented on Linux.)
517 .TP
518 .B FLUSHO
519 (not in POSIX;
520 not supported under Linux)
521 Output is being flushed.
522 This flag is toggled by typing
523 the DISCARD character.
524 [requires
525 .B _BSD_SOURCE
526 or
527 .BR _SVID_SOURCE ]
528 .TP
529 .B NOFLSH
530 Disable flushing the input and output queues when generating signals for the
531 INT, QUIT, and SUSP characters.
532 .\" Stevens lets SUSP only flush the input queue
533 .TP
534 .B TOSTOP
535 Send the
536 .B SIGTTOU
537 signal to the process group of a background process
538 which tries to write to its controlling terminal.
539 .TP
540 .B PENDIN
541 (not in POSIX;
542 not supported under Linux)
543 All characters in the input queue are reprinted
544 when the next character is read.
545 .RB ( bash (1)
546 handles typeahead this way.)
547 [requires
548 .B _BSD_SOURCE
549 or
550 .BR _SVID_SOURCE ]
551 .TP
552 .B IEXTEN
553 Enable implementation-defined input processing.
554 This flag, as well as
555 .B ICANON
556 must be enabled for the
557 special characters EOL2, LNEXT, REPRINT, WERASE to be interpreted,
558 and for the
559 .B IUCLC
560 flag to be effective.
561 .P
562 The
563 .I c_cc
564 array defines the terminal special characters.
565 The symbolic indices (initial values) and meaning are:
566 .TP
567 .B VDISCARD
568 (not in POSIX;
569 not supported under Linux;
570 017, SI, Ctrl-O)
571 Toggle: start/stop discarding pending output.
572 Recognized when
573 .B IEXTEN
574 is set, and then not passed as input.
575 .TP
576 .B VDSUSP
577 (not in POSIX;
578 not supported under Linux;
579 031, EM, Ctrl-Y)
580 Delayed suspend character (DSUSP):
581 send
582 .B SIGTSTP
583 signal when the character is read by the user program.
584 Recognized when
585 .B IEXTEN
586 and
587 .B ISIG
588 are set,
589 and the system supports job control,
590 and then not passed as input.
591 .TP
592 .B VEOF
593 (004, EOT, Ctrl-D)
594 End-of-file character (EOF).
595 More precisely:
596 this character causes the pending tty buffer to be sent
597 to the waiting user program
598 without waiting for end-of-line.
599 If it is the first character of the line,
600 the
601 .BR read (2)
602 in the user program returns 0,
603 which signifies end-of-file.
604 Recognized when
605 .B ICANON
606 is set,
607 and then not passed as input.
608 .TP
609 .B VEOL
610 (0, NUL)
611 Additional end-of-line character (EOL).
612 Recognized when
613 .B ICANON
614 is set.
615 .TP
616 .B VEOL2
617 (not in POSIX;
618 0, NUL)
619 Yet another end-of-line character (EOL2).
620 Recognized when
621 .B ICANON
622 is set.
623 .TP
624 .B VERASE
625 (0177, DEL, rubout, or 010, BS, Ctrl-H, or also #)
626 Erase character (ERASE).
627 This erases the previous not-yet-erased character,
628 but does not erase past EOF or beginning-of-line.
629 Recognized when
630 .B ICANON
631 is set,
632 and then not passed as input.
633 .TP
634 .B VINTR
635 (003, ETX, Ctrl-C, or also 0177, DEL, rubout)
636 Interrupt character (INTR).
637 Send a
638 .B SIGINT
639 signal.
640 Recognized when
641 .B ISIG
642 is set,
643 and then not passed as input.
644 .TP
645 .B VKILL
646 (025, NAK, Ctrl-U, or Ctrl-X, or also @)
647 Kill character (KILL).
648 This erases the input since the last EOF or beginning-of-line.
649 Recognized when
650 .B ICANON
651 is set,
652 and then not passed as input.
653 .TP
654 .B VLNEXT
655 (not in POSIX;
656 026, SYN, Ctrl-V)
657 Literal next (LNEXT).
658 Quotes the next input character,
659 depriving it of a possible special meaning.
660 Recognized when
661 .B IEXTEN
662 is set,
663 and then not passed as input.
664 .TP
665 .B VMIN
666 Minimum number of characters for noncanonical read (MIN).
667 .TP
668 .B VQUIT
669 (034, FS, Ctrl-\[rs])
670 Quit character (QUIT).
671 Send
672 .B SIGQUIT
673 signal.
674 Recognized when
675 .B ISIG
676 is set,
677 and then not passed as input.
678 .TP
679 .B VREPRINT
680 (not in POSIX;
681 022, DC2, Ctrl-R)
682 Reprint unread characters (REPRINT).
683 Recognized when
684 .B ICANON
685 and
686 .B IEXTEN
687 are set,
688 and then not passed as input.
689 .TP
690 .B VSTART
691 (021, DC1, Ctrl-Q)
692 Start character (START).
693 Restarts output stopped by the Stop character.
694 Recognized when
695 .B IXON
696 is set,
697 and then not passed as input.
698 .TP
699 .B VSTATUS
700 (not in POSIX;
701 not supported under Linux;
702 status request:
703 024, DC4, Ctrl-T).
704 Status character (STATUS).
705 Display status information at terminal,
706 including state of foreground process and amount of CPU time it has consumed.
707 Also sends a
708 .B SIGINFO
709 signal
710 (not supported on Linux)
711 to the foreground process group.
712 .TP
713 .B VSTOP
714 (023, DC3, Ctrl-S)
715 Stop character (STOP).
716 Stop output until Start character typed.
717 Recognized when
718 .B IXON
719 is set,
720 and then not passed as input.
721 .TP
722 .B VSUSP
723 (032, SUB, Ctrl-Z)
724 Suspend character (SUSP).
725 Send
726 .B SIGTSTP
727 signal.
728 Recognized when
729 .B ISIG
730 is set,
731 and then not passed as input.
732 .TP
733 .B VSWTCH
734 (not in POSIX;
735 not supported under Linux;
736 0, NUL)
737 Switch character (SWTCH).
738 Used in System V to switch shells in
739 .IR "shell layers" ,
740 a predecessor to shell job control.
741 .TP
742 .B VTIME
743 Timeout in deciseconds for noncanonical read (TIME).
744 .TP
745 .B VWERASE
746 (not in POSIX;
747 027, ETB, Ctrl-W)
748 Word erase (WERASE).
749 Recognized when
750 .B ICANON
751 and
752 .B IEXTEN
753 are set,
754 and then not passed as input.
755 .P
756 An individual terminal special character can be disabled
757 by setting the value of the corresponding
758 .I c_cc
759 element to
760 .BR _POSIX_VDISABLE .
761 .P
762 The above symbolic subscript values are all different,
763 except that
764 .BR VTIME ,
765 .B VMIN
766 may have the same value as
767 .BR VEOL ,
768 .BR VEOF ,
769 respectively.
770 In noncanonical mode,
771 the special character meaning
772 is replaced by the timeout meaning.
773 For an explanation of
774 .B VMIN
775 and
776 .BR VTIME ,
777 see the description of
778 noncanonical mode below.
779 .SS Retrieving and changing terminal settings
780 .BR tcgetattr ()
781 gets the parameters associated with the object referred by
782 .IR fd ,
783 and stores them in the
784 .I termios
785 structure referenced by
786 .IR termios_p .
787 This function may be invoked from a background process;
788 however,
789 the terminal attributes may be subsequently changed
790 by a foreground process.
791 .P
792 .BR tcsetattr ()
793 sets the parameters associated with the terminal
794 (unless support is required from the underlying hardware that is not available)
795 from the
796 .I termios
797 structure referred to by
798 .IR termios_p .
799 .I optional_actions
800 specifies when the changes take effect:
801 .TP
802 .B TCSANOW
803 the change occurs immediately.
804 .TP
805 .B TCSADRAIN
806 the change occurs after all output written to
807 .I fd
808 has been transmitted.
809 This option should be used when changing
810 parameters that affect output.
811 .TP
812 .B TCSAFLUSH
813 the change occurs after all output written to the object referred by
814 .I fd
815 has been transmitted,
816 and all input that has been received but not read
817 will be discarded before the change is made.
818 .SS Canonical and noncanonical mode
819 The setting of the
820 .B ICANON
821 canon flag in
822 .I c_lflag
823 determines whether the terminal is operating
824 in canonical mode
825 .RB ( ICANON
826 set)
827 or noncanonical mode
828 .RB ( ICANON
829 unset).
830 By default,
831 .B ICANON
832 is set.
833 .P
834 In canonical mode:
835 .IP \[bu] 3
836 Input is made available line by line.
837 An input line is available when one of the line delimiters is typed
838 (NL, EOL, EOL2;
839 or EOF at the start of line).
840 Except in the case of EOF,
841 the line delimiter is included
842 in the buffer returned by
843 .BR read (2).
844 .IP \[bu]
845 Line editing is enabled
846 (ERASE, KILL;
847 and if the
848 .B IEXTEN
849 flag is set: WERASE, REPRINT, LNEXT).
850 A
851 .BR read (2)
852 returns at most one line of input;
853 if the
854 .BR read (2)
855 requested fewer bytes than are available in the current line of input,
856 then only as many bytes as requested are read,
857 and the remaining characters will be available for a future
858 .BR read (2).
859 .IP \[bu]
860 The maximum line length is 4096 chars
861 (including the terminating newline character);
862 lines longer than 4096 chars are truncated.
863 After 4095 characters,
864 input processing
865 (e.g.,
866 .B ISIG
867 and
868 .B ECHO*
869 processing)
870 continues,
871 but any input data after 4095 characters
872 up to (but not including) any terminating newline
873 is discarded.
874 This ensures that
875 the terminal can always receive more input
876 until at least one line can be read.
877 .P
878 In noncanonical mode input is available immediately
879 (without the user having to type a line-delimiter character),
880 no input processing is performed,
881 and line editing is disabled.
882 The read buffer will only accept 4095 chars;
883 this provides the necessary space for a newline char
884 if the input mode is switched to canonical.
885 The settings of MIN
886 .RI ( c_cc[VMIN] )
887 and TIME
888 .RI ( c_cc[VTIME] )
889 determine the circumstances in which a
890 .BR read (2)
891 completes;
892 there are four distinct cases:
893 .TP
894 MIN == 0, TIME == 0 (polling read)
895 If data is available,
896 .BR read (2)
897 returns immediately,
898 with the lesser of the number of bytes available,
899 or the number of bytes requested.
900 If no data is available,
901 .BR read (2)
902 returns 0.
903 .TP
904 MIN > 0, TIME == 0 (blocking read)
905 .BR read (2)
906 blocks until MIN bytes are available,
907 and returns up to the number of bytes requested.
908 .TP
909 MIN == 0, TIME > 0 (read with timeout)
910 TIME specifies the limit for a timer in tenths of a second.
911 The timer is started when
912 .BR read (2)
913 is called.
914 .BR read (2)
915 returns either when at least one byte of data is available,
916 or when the timer expires.
917 If the timer expires without any input becoming available,
918 .BR read (2)
919 returns 0.
920 If data is already available at the time of the call to
921 .BR read (2),
922 the call behaves as though the data was received immediately after the call.
923 .TP
924 MIN > 0, TIME > 0 (read with interbyte timeout)
925 TIME specifies the limit for a timer in tenths of a second.
926 Once an initial byte of input becomes available,
927 the timer is restarted after each further byte is received.
928 .BR read (2)
929 returns when any of the following conditions is met:
930 .RS
931 .IP \[bu] 3
932 MIN bytes have been received.
933 .IP \[bu]
934 The interbyte timer expires.
935 .IP \[bu]
936 The number of bytes requested by
937 .BR read (2)
938 has been received.
939 (POSIX does not specify this termination condition,
940 and on some other implementations
941 .\" e.g., Solaris
942 .BR read (2)
943 does not return in this case.)
944 .RE
945 .IP
946 Because the timer is started only after the initial byte becomes available,
947 at least one byte will be read.
948 If data is already available at the time of the call to
949 .BR read (2),
950 the call behaves as though the data was received immediately after the call.
951 .P
952 POSIX
953 .\" POSIX.1-2008 XBD 11.1.7
954 does not specify whether the setting of the
955 .B O_NONBLOCK
956 file status flag takes precedence over the MIN and TIME settings.
957 If
958 .B O_NONBLOCK
959 is set, a
960 .BR read (2)
961 in noncanonical mode may return immediately,
962 regardless of the setting of MIN or TIME.
963 Furthermore,
964 if no data is available,
965 POSIX permits a
966 .BR read (2)
967 in noncanonical mode to return either 0, or \-1 with
968 .I errno
969 set to
970 .BR EAGAIN .
971 .SS Raw mode
972 .BR cfmakeraw ()
973 sets the terminal to something like the
974 "raw" mode of the old Version 7 terminal driver:
975 input is available character by character,
976 echoing is disabled,
977 and all special processing of terminal input and output characters is disabled.
978 The terminal attributes are set as follows:
979 .P
980 .in +4n
981 .EX
982 termios_p\->c_iflag &= \[ti](IGNBRK | BRKINT | PARMRK | ISTRIP
983 | INLCR | IGNCR | ICRNL | IXON);
984 termios_p\->c_oflag &= \[ti]OPOST;
985 termios_p\->c_lflag &= \[ti](ECHO | ECHONL | ICANON | ISIG | IEXTEN);
986 termios_p\->c_cflag &= \[ti](CSIZE | PARENB);
987 termios_p\->c_cflag |= CS8;
988 .EE
989 .in
990 .\"
991 .SS Line control
992 .BR tcsendbreak ()
993 transmits a continuous stream of zero-valued bits for a specific duration,
994 if the terminal is using asynchronous serial data transmission.
995 If
996 .I duration
997 is zero,
998 it transmits zero-valued bits
999 for at least 0.25 seconds,
1000 and not more than 0.5 seconds.
1001 If
1002 .I duration
1003 is not zero,
1004 it sends zero-valued bits for some
1005 implementation-defined length of time.
1006 .P
1007 If the terminal is not using asynchronous serial data transmission,
1008 .BR tcsendbreak ()
1009 returns without taking any action.
1010 .P
1011 .BR tcdrain ()
1012 waits until all output written to the object referred to by
1013 .I fd
1014 has been transmitted.
1015 .P
1016 .BR tcflush ()
1017 discards data written to the object referred to by
1018 .I fd
1019 but not transmitted,
1020 or data received but not read,
1021 depending on the value of
1022 .IR queue_selector :
1023 .TP
1024 .B TCIFLUSH
1025 flushes data received but not read.
1026 .TP
1027 .B TCOFLUSH
1028 flushes data written but not transmitted.
1029 .TP
1030 .B TCIOFLUSH
1031 flushes both data received but not read,
1032 and data written but not transmitted.
1033 .P
1034 .BR tcflow ()
1035 suspends transmission or reception of data
1036 on the object referred to by
1037 .IR fd ,
1038 depending on the value of
1039 .IR action :
1040 .TP
1041 .B TCOOFF
1042 suspends output.
1043 .TP
1044 .B TCOON
1045 restarts suspended output.
1046 .TP
1047 .B TCIOFF
1048 transmits a STOP character,
1049 which stops the terminal device from
1050 transmitting data to the system.
1051 .TP
1052 .B TCION
1053 transmits a START character,
1054 which starts the terminal device
1055 transmitting data to the system.
1056 .P
1057 The default on open of a terminal file is that
1058 neither its input nor its output is suspended.
1059 .SS Line speed
1060 The baud rate functions are provided
1061 for getting and setting
1062 the values of the input and output baud rates
1063 in the
1064 .I termios
1065 structure.
1066 The new values do not take effect
1067 until
1068 .BR tcsetattr ()
1069 is successfully called.
1070 .P
1071 Setting the speed to
1072 .B B0
1073 instructs the modem to "hang up".
1074 The actual bit rate corresponding to
1075 .B B38400
1076 may be altered with
1077 .BR setserial (8).
1078 .P
1079 The input and output baud rates are stored in the
1080 .I termios
1081 structure.
1082 .P
1083 .BR cfgetospeed ()
1084 returns the output baud rate stored in the
1085 .I termios
1086 structure
1087 pointed to by
1088 .IR termios_p .
1089 .P
1090 .BR cfsetospeed ()
1091 sets the output baud rate stored in the
1092 .I termios
1093 structure
1094 pointed to by
1095 .I termios_p
1096 to
1097 .IR speed ,
1098 which must be one of these constants:
1099 .RS
1100 .TP
1101 .B B0
1102 .TQ
1103 .B B50
1104 .TQ
1105 .B B75
1106 .TQ
1107 .B B110
1108 .TQ
1109 .B B134
1110 .TQ
1111 .B B150
1112 .TQ
1113 .B B200
1114 .TQ
1115 .B B300
1116 .TQ
1117 .B B600
1118 .TQ
1119 .B B1200
1120 .TQ
1121 .B B1800
1122 .TQ
1123 .B B2400
1124 .TQ
1125 .B B4800
1126 .TQ
1127 .B B9600
1128 .TQ
1129 .B B19200
1130 .TQ
1131 .B B38400
1132 .TQ
1133 .B B57600
1134 .TQ
1135 .B B115200
1136 .TQ
1137 .B B230400
1138 .TQ
1139 .B B460800
1140 .TQ
1141 .B B500000
1142 .TQ
1143 .B B576000
1144 .TQ
1145 .B B921600
1146 .TQ
1147 .B B1000000
1148 .TQ
1149 .B B1152000
1150 .TQ
1151 .B B1500000
1152 .TQ
1153 .B B2000000
1154 .RE
1155 .P
1156 These constants are additionally supported on the SPARC architecture:
1157 .RS
1158 .TP
1159 .B B76800
1160 .TQ
1161 .B B153600
1162 .TQ
1163 .B B307200
1164 .TQ
1165 .B B614400
1166 .RE
1167 .P
1168 These constants are additionally supported on non-SPARC architectures:
1169 .RS
1170 .TP
1171 .B B2500000
1172 .TQ
1173 .B B3000000
1174 .TQ
1175 .B B3500000
1176 .TQ
1177 .B B4000000
1178 .RE
1179 .P
1180 Due to differences between architectures,
1181 portable applications should check
1182 if a particular
1183 .BI B nnn
1184 constant is defined prior to using it.
1185 .P
1186 The zero baud rate,
1187 .BR B0 ,
1188 is used to terminate the connection.
1189 If
1190 .B B0
1191 is specified,
1192 the modem control lines shall no longer be asserted.
1193 Normally,
1194 this will disconnect the line.
1195 .B CBAUDEX
1196 is a mask
1197 for the speeds beyond those defined in POSIX.1
1198 (57600 and above).
1199 Thus,
1200 .BR B57600 " & " CBAUDEX
1201 is nonzero.
1202 .P
1203 Setting the baud rate to a value other than those defined by
1204 .BI B nnn
1205 constants is possible via the
1206 .B TCSETS2
1207 ioctl;
1208 see
1209 .BR ioctl_tty (2).
1210 .P
1211 .BR cfgetispeed ()
1212 returns the input baud rate stored in the
1213 .I termios
1214 structure.
1215 .P
1216 .BR cfsetispeed ()
1217 sets the input baud rate stored in the
1218 .I termios
1219 structure to
1220 .IR speed ,
1221 which must be specified as one of the
1222 .BI B nnn
1223 constants listed above for
1224 .BR cfsetospeed ().
1225 If the input baud rate is set to the literal constant
1226 .B 0
1227 (not the symbolic constant
1228 .BR B0 ),
1229 the input baud rate will be
1230 equal to the output baud rate.
1231 .P
1232 .BR cfsetspeed ()
1233 is a 4.4BSD extension.
1234 It takes the same arguments as
1235 .BR cfsetispeed (),
1236 and sets both input and output speed.
1237 .SH RETURN VALUE
1238 .BR cfgetispeed ()
1239 returns the input baud rate stored in the
1240 .I termios
1241 structure.
1242 .P
1243 .BR cfgetospeed ()
1244 returns the output baud rate stored in the
1245 .I termios
1246 structure.
1247 .P
1248 All other functions return:
1249 .TP
1250 .B 0
1251 on success.
1252 .TP
1253 .B \-1
1254 on failure and set
1255 .I errno
1256 to indicate the error.
1257 .P
1258 Note that
1259 .BR tcsetattr ()
1260 returns success if
1261 .I any
1262 of the requested changes could be
1263 successfully carried out.
1264 Therefore,
1265 when making multiple changes,
1266 it may be necessary to follow this call with a further call to
1267 .BR tcgetattr ()
1268 to check that all changes have been performed successfully.
1269 .SH ATTRIBUTES
1270 For an explanation of the terms used in this section,
1271 see
1272 .BR attributes (7).
1273 .TS
1274 allbox;
1275 lbx lb lb
1276 l l l.
1277 Interface Attribute Value
1278 T{
1279 .na
1280 .nh
1281 .BR tcgetattr (),
1282 .BR tcsetattr (),
1283 .BR tcdrain (),
1284 .BR tcflush (),
1285 .BR tcflow (),
1286 .BR tcsendbreak (),
1287 .BR cfmakeraw (),
1288 .BR cfgetispeed (),
1289 .BR cfgetospeed (),
1290 .BR cfsetispeed (),
1291 .BR cfsetospeed (),
1292 .BR cfsetspeed ()
1293 T} Thread safety MT-Safe
1294 .TE
1295 .\" FIXME: The markings are different from that in the glibc manual.
1296 .\" markings in glibc manual are more detailed:
1297 .\"
1298 .\" tcsendbreak: MT-Unsafe race:tcattr(filedes)/bsd
1299 .\" tcflow: MT-Unsafe race:tcattr(filedes)/bsd
1300 .\"
1301 .\" glibc manual says /bsd indicate the preceding marker only applies
1302 .\" when the underlying kernel is a BSD kernel.
1303 .\" So, it is safety in Linux kernel.
1304 .SH STANDARDS
1305 .TP
1306 .BR tcgetattr ()
1307 .TQ
1308 .BR tcsetattr ()
1309 .TQ
1310 .BR tcsendbreak ()
1311 .TQ
1312 .BR tcdrain ()
1313 .TQ
1314 .BR tcflush ()
1315 .TQ
1316 .BR tcflow ()
1317 .TQ
1318 .BR cfgetispeed ()
1319 .TQ
1320 .BR cfgetospeed ()
1321 .TQ
1322 .BR cfsetispeed ()
1323 .TQ
1324 .BR cfsetospeed ()
1325 POSIX.1-2008.
1326 .TP
1327 .BR cfmakeraw ()
1328 .TQ
1329 .BR cfsetspeed ()
1330 BSD.
1331 .SH HISTORY
1332 .TP
1333 .BR tcgetattr ()
1334 .TQ
1335 .BR tcsetattr ()
1336 .TQ
1337 .BR tcsendbreak ()
1338 .TQ
1339 .BR tcdrain ()
1340 .TQ
1341 .BR tcflush ()
1342 .TQ
1343 .BR tcflow ()
1344 .TQ
1345 .BR cfgetispeed ()
1346 .TQ
1347 .BR cfgetospeed ()
1348 .TQ
1349 .BR cfsetispeed ()
1350 .TQ
1351 .BR cfsetospeed ()
1352 POSIX.1-2001.
1353 .TP
1354 .BR cfmakeraw ()
1355 .TQ
1356 .BR cfsetspeed ()
1357 BSD.
1358 .SH NOTES
1359 UNIX\ V7 and several later systems have a list of baud rates
1360 where after the values
1361 .B B0
1362 through
1363 .B B9600
1364 one finds the two constants
1365 .BR EXTA ,
1366 .B EXTB
1367 ("External A" and "External B").
1368 Many systems extend the list with much higher baud rates.
1369 .P
1370 The effect of a nonzero
1371 .I duration
1372 with
1373 .BR tcsendbreak ()
1374 varies.
1375 SunOS specifies a break of
1376 .I "duration\ *\ N"
1377 seconds, where
1378 .I N
1379 is at least 0.25, and not more than 0.5.
1380 Linux, AIX, DU, Tru64 send a break of
1381 .I duration
1382 milliseconds.
1383 FreeBSD and NetBSD and HP-UX and MacOS ignore the value of
1384 .IR duration .
1385 Under Solaris and UnixWare,
1386 .BR tcsendbreak ()
1387 with nonzero
1388 .I duration
1389 behaves like
1390 .BR tcdrain ().
1391 .\" libc4 until 4.7.5, glibc for sysv: EINVAL for duration > 0.
1392 .\" libc4.7.6, libc5, glibc for unix: duration in ms.
1393 .\" glibc for bsd: duration in us
1394 .\" glibc for sunos4: ignore duration
1395 .SH BUGS
1396 .\" kernel 77e5bff1640432f28794a00800955e646dcd7455
1397 .\" glibc 573963e32ffac46d9891970ddebde2ac3212c5c0
1398 On the Alpha architecture before Linux 4.16 (and glibc before glibc 2.28), the
1399 .B XTABS
1400 value was different from
1401 .B TAB3
1402 and it was ignored by the
1403 .B N_TTY
1404 line discipline code of the terminal driver as a result
1405 (because as it wasn't part of the
1406 .B TABDLY
1407 mask).
1408 .SH SEE ALSO
1409 .BR reset (1),
1410 .BR setterm (1),
1411 .BR stty (1),
1412 .BR tput (1),
1413 .BR tset (1),
1414 .BR tty (1),
1415 .BR ioctl_console (2),
1416 .BR ioctl_tty (2),
1417 .BR cc_t (3type),
1418 .BR speed_t (3type),
1419 .BR tcflag_t (3type),
1420 .BR setserial (8)