1 .\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
2 .\" Copyright 2019, Joyent, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .Dd February 17, 2020
19 .Dt TERMIO 7I
20 .Os
21 .Sh NAME
22 .Nm termio
23 .Nd general terminal interface
24 .Sh SYNOPSIS
25 .In termio.h
26 .Fn ioctl "int fildes" "int request" "struct termio *arg"
27 .Fn ioctl "int fildes" "int request" "int arg"
28 .Pp
29 .In termios.h
30 .Fn ioctl "int fildes" "int request" "struct termios *arg"
31 .Sh DESCRIPTION
32 This release supports a general interface for asynchronous communications ports
33 that is hardware-independent.
34 The user interface to this functionality is using
35 function calls (the preferred interface) described in
36 .Xr termios 3C
37 or
38 .Fn ioctl
39 commands described in this section.
40 This section also discusses the
41 common features of the terminal subsystem which are relevant with both user
42 interfaces.
43 .Pp
44 When a terminal file is opened, it normally causes the process to wait until a
45 connection is established.
46 In practice, user programs seldom open terminal
47 files; they are opened by the system and become a user's standard input,
48 output, and error files.
49 The first terminal file opened by the session leader
50 that is not already associated with a session becomes the controlling terminal
51 for that session.
52 The controlling terminal plays a special role in handling
53 quit and interrupt signals, as discussed below.
54 The controlling terminal is
55 inherited by a child process during a
56 .Xr fork 2 .
57 A process can break this
58 association by changing its session using
59 .Xr setsid 2 .
60 .Pp
61 A terminal associated with one of these files ordinarily operates in
62 full-duplex mode.
63 Characters may be typed at any time, even while output is
64 occurring, and are only lost when the character input buffers of the system
65 become completely full, which is rare.
66 For example, the number of characters in
67 the line discipline buffer may exceed
68 .Brq Dv MAX_CANON
69 and
70 .Dv IMAXBEL
71 (see below) is not set, or the user may accumulate
72 .Brq Dv MAX_INPUT
73 number of input characters that have not yet been read by some program.
74 When the input
75 limit is reached, all the characters saved in the buffer up to that point are
76 thrown away without notice.
77 .Ss "Session Management (Job Control)"
78 A control terminal will distinguish one of the process groups in the session
79 associated with it to be the foreground process group.
80 All other process
81 groups in the session are designated as background process groups.
82 This foreground process group plays a special role in handling signal-generating
83 input characters, as discussed below.
84 By default, when a controlling terminal
85 is allocated, the controlling process's process group is assigned as
86 foreground process group.
87 .Pp
88 Background process groups in the controlling process's session are subject to a
89 job control line discipline when they attempt to access their controlling
90 terminal.
91 Process groups can be sent signals that will cause them to stop,
92 unless they have made other arrangements.
93 An exception is made for members of
94 orphaned process groups.
95 .Pp
96 An orphaned process group is one where the process group (see
97 .Xr getpgid 2 )
98 has no members with a parent in a different process group but sharing the same
99 controlling terminal.
100 When a member of an orphaned process group attempts to
101 access its controlling terminal, EIO is returned because there would be no way
102 to restart the process if it were stopped on one of these signals.
103 .Pp
104 If a member of a background process group attempts to read its controlling
105 terminal, its process group will be sent a
106 .Dv SIGTTIN
107 signal, which will
108 normally cause the members of that process group to stop.
109 If, however, the
110 process is ignoring or holding
111 .Dv SIGTTIN ,
112 or is a member of an orphaned
113 process group, the read will fail with
114 .Va errno
115 set to
116 .Er EIO ,
117 and no signal is sent.
118 .Pp
119 If a member of a background process group attempts to write its controlling
120 terminal and the
121 .Dv TOSTOP
122 bit is set in the
123 .Fa c_lflag
124 field, its process group is sent a
125 .Dv SIGTTOU
126 signal, which will normally cause the
127 members of that process group to stop.
128 If, however, the process is ignoring or
129 holding
130 .Dv SIGTTOU ,
131 the write will succeed.
132 If the process is not ignoring
133 or holding
134 .Dv SIGTTOU
135 and is a member of an orphaned process group, the
136 write will fail with
137 .Va errno
138 set to
139 .Er EIO ,
140 and no signal will be sent.
141 .Pp
142 If
143 .Dv TOSTOP
144 is set and a member of a background process group attempts to
145 .Fn ioctl
146 its controlling terminal, and that
147 .Fn ioctl
148 will modify terminal parameters (for example,
149 .Dv TCSETA ,
150 .Dv TCSETAW ,
151 .Dv TCSETAF ,
152 or
153 .Dv TIOCSPGRP ) ,
154 its process group will be sent a
155 .Dv SIGTTOU
156 signal, which will normally cause the members of that process group to stop.
157 If, however, the process is ignoring or holding
158 .Dv SIGTTOU ,
159 the ioctl will succeed.
160 If the process is not ignoring or holding
161 .Dv SIGTTOU
162 and is a member of an orphaned
163 process group, the write will fail with
164 .Va errno
165 set to
166 .Er EIO ,
167 and no signal will be sent.
168 .Ss "Canonical Mode Input Processing"
169 Normally, terminal input is processed in units of lines.
170 A line is delimited by
171 a newline
172 .Po
173 .Sy ASCII LF
174 .Pc
175 character, an end-of-file
176 .Po
177 .Sy ASCII EOT
178 .Pc
179 character, or an end-of-line character.
180 This means that a program attempting to
181 read will block until an entire line has been typed.
182 Also, no matter how many
183 characters are requested in the read call, at most one line will be returned.
184 It is not necessary, however, to read a whole line at once; any number of
185 characters may be requested in a read, even one, without losing information.
186 .Pp
187 During input, erase, erase2, and kill processing is normally done.
188 The
189 .Sy ERASE
190 and
191 .Sy ERASE2
192 character (by default, the character
193 .Sy DEL
194 for
195 .Sy ERASE
196 and
197 .Sy Control-h
198 for
199 .Sy ERASE2 )
200 erases the last character typed.
201 The
202 .Sy WERASE
203 character (the character
204 .Sy Control-w )
205 erases the
206 last "word" typed in the current input line (but not any preceding spaces or
207 tabs).
208 A
209 .Dq word
210 is defined as a sequence of non-blank characters, with tabs counted as blanks.
211 None of
212 .Sy ERASE
213 or
214 .Sy ERASE2
215 or
216 .Sy WERASE
217 will erase beyond the beginning of the line.
218 The
219 .Sy KILL
220 character (by default,
221 the character
222 .Sy NAK )
223 kills (deletes) the entire input line, and optionally
224 outputs a newline character.
225 All these characters operate on a key stroke basis,
226 independent of any backspacing or tabbing that may have been done.
227 The
228 .Sy REPRINT
229 character (the character
230 .Sy Control-r )
231 prints a newline followed by all characters that have not been read.
232 Reprinting also occurs automatically if
233 characters that would normally be erased from the screen are fouled by program
234 output.
235 The characters are reprinted as if they were being echoed;
236 consequently, if
237 .Dv ECHO
238 is not set, they are not printed.
239 .Pp
240 The
241 .Sy ERASE ,
242 .Sy ERASE2 ,
243 and
244 .Sy KILL
245 characters may be entered literally by preceding them with the escape character.
246 In this case, the escape character is not read.
247 The erase, erase2, and kill characters may be changed.
248 .Ss "Non-canonical Mode Input Processing"
249 In non-canonical mode input processing, input characters are not assembled into
250 lines, and erase and kill processing does not occur.
251 The
252 .Sy MIN
253 and
254 .Sy TIME
255 values are used to determine how to process the characters received.
256 .Pp
257 .Sy MIN
258 represents the minimum number of characters that should be received
259 when the read is satisfied (that is, when the characters are returned to the
260 user).
261 .Sy TIME
262 is a timer of 0\&.10-second granularity that is used to timeout
263 bursty and short-term data transmissions.
264 The four possible values for
265 .Sy MIN
266 and
267 .Sy TIME
268 and their interactions are described below.
269 .Bl -tag -width "Case A: Min > 0, Time > 0"
270 .It Sy Case A: MIN > 0, TIME > 0
271 In this case,
272 .Sy TIME
273 serves as an intercharacter timer and is activated
274 after the first character is received.
275 Since it is an intercharacter timer, it
276 is reset after a character is received.
277 The interaction between
278 .Sy MIN
279 and
280 .Sy TIME
281 is as follows: as soon as one character is received, the
282 intercharacter timer is started.
283 If
284 .Sy MIN
285 characters are received before
286 the intercharacter timer expires (note that the timer is reset upon receipt of
287 each character), the read is satisfied.
288 If the timer expires before
289 .Sy MIN
290 characters are received, the characters received to that point are returned to
291 the user.
292 Note that if
293 .Sy TIME
294 expires, at least one character will be
295 returned because the timer would not have been enabled unless a character was
296 received.
297 In this case (MIN > 0, TIME > 0), the read sleeps until the
298 .Sy MIN
299 and
300 .Sy TIME
301 mechanisms are activated by the receipt of the first character.
302 If the number of characters read is less than the number of characters
303 available, the timer is not reactivated and the subsequent read is satisfied
304 immediately.
305 .It Sy Case B: MIN > 0, TIME = 0
306 In this case, since the value of
307 .Sy TIME
308 is zero, the timer plays no role
309 and only
310 .Sy MIN
311 is significant.
312 A pending read is not satisfied until
313 .Sy MIN
314 characters are received (the pending read sleeps until
315 .Sy MIN
316 characters are received).
317 A program that uses this case to read record based
318 terminal
319 .Sy I/O
320 may block indefinitely in the read operation.
321 .It Sy Case C: MIN = 0, TIME > 0
322 In this case, since
323 .Sy MIN
324 0,
325 .Sy TIME
326 no longer represents an
327 intercharacter timer: it now serves as a read timer that is activated as soon
328 as a
329 .Xr read 2
330 is done.
331 A read is satisfied as soon as a single character is
332 received or the read timer expires.
333 Note that, in this case, if the timer
334 expires, no character is returned.
335 If the timer does not expire, the only way
336 the read can be satisfied is if a character is received.
337 In this case, the
338 read will not block indefinitely waiting for a character; if no character is
339 received within
340 .Sy TIME
341 *\&.10 seconds after the read is initiated, the read
342 returns with zero characters.
343 .It Sy Case D: MIN = 0, TIME = 0
344 In this case, return is immediate.
345 The minimum of either the number of
346 characters requested or the number of characters currently available is
347 returned without waiting for more characters to be input.
348 .El
349 .Ss "Comparing Different Cases of MIN, TIME Interaction"
350 Some points to note about
351 .Sy MIN
352 and
353 .Sy TIME :
354 .Bl -bullet -offset 2n
355 .It
356 In the following explanations, note that the interactions of
357 .Sy MIN
358 and
359 .Sy TIME
360 are not symmetric.
361 For example, when
362 .Sy MIN
363 > 0 and
364 .Sy TIME
365 = 0,
366 .Sy TIME
367 has no effect.
368 However, in the opposite case, where
369 .Sy MIN
370 = 0 and
371 .Sy TIME
372 > 0, both
373 .Sy MIN
374 and
375 .Sy TIME
376 play a role in that
377 .Sy MIN
378 is satisfied with the receipt of a single character.
379 .It
380 Also note that in case A
381 .Po
382 .Sy MIN
383 > 0,
384 .Sy TIME
385 > 0
386 .Pc ,
387 .Sy TIME
388 represents
389 an intercharacter timer, whereas in case C
390 .Po
391 .Sy MIN
392 = 0,
393 .Sy TIME
394 > 0
395 .Pc ,
396 .Sy TIME
397 represents a read timer.
398 .El
399 .Pp
400 These two points highlight the dual purpose of the
401 .Sy MIN/TIME
402 feature.
403 Cases A and B, where
404 .Sy MIN
405 > 0, exist to handle burst mode activity (for
406 example, file transfer programs), where a program would like to process at
407 least
408 .Sy MIN
409 characters at a time.
410 In case A, the intercharacter timer is
411 activated by a user as a safety measure; in case B, the timer is turned off.
412 .Pp
413 Cases C and D exist to handle single character, timed transfers.
414 These cases
415 are readily adaptable to screen-based applications that need to know if a
416 character is present in the input queue before refreshing the screen.
417 In case
418 C, the read is timed, whereas in case D, it is not.
419 .Pp
420 Another important note is that
421 .Sy MIN
422 is always just a minimum.
423 It does not
424 denote a record length.
425 For example, if a program does a read of 20 bytes,
426 .Sy MIN
427 is 10, and 25 characters are present, then 20 characters will be
428 returned to the user.
429 .Ss "Writing Characters"
430 When one or more characters are written, they are transmitted to the terminal
431 as soon as previously written characters have finished typing.
432 Input characters
433 are echoed as they are typed if echoing has been enabled.
434 If a process produces
435 characters more rapidly than they can be typed, it will be suspended when its
436 output queue exceeds some limit.
437 When the queue is drained down to some
438 threshold, the program is resumed.
439 .Ss "Special Characters"
440 Certain characters have special functions on input.
441 These functions and their default character values are summarized as follows:
442 .Bl -tag -width REPRINT
443 .It Sy INTR
444 (Control-c or
445 .Sy ASCII ETX )
446 generates a
447 .Dv SIGINT
448 signal.
449 .Dv SIGINT
450 is sent to all foreground processes associated with the controlling terminal.
451 Normally, each such process is forced to terminate, but arrangements may be
452 made either to ignore the signal or to receive a trap to an agreed upon
453 location.
454 (See
455 .Xr signal.h 3HEAD ) .
456 .It Sy QUIT
457 (Control-| or
458 .Sy ASCII FS )
459 generates a
460 .Dv SIGQUIT
461 signal.
462 Its treatment
463 is identical to the interrupt signal except that, unless a receiving process
464 has made other arrangements, it will not only be terminated but a core image
465 file (called
466 .Pa core )
467 will be created in the current working directory.
468 .It Sy ERASE
469 (DEL) erases the preceding character.
470 It does not erase beyond
471 the start of a line, as delimited by a
472 .Sy NL ,
473 .Sy EOF ,
474 .Sy EOL ,
475 or
476 .Sy EOL2
477 character.
478 .It Sy ERASE2
479 (Control-h or
480 .Sy ASCII BS )
481 erases the preceding character, with behaviour identical to that of ERASE.
482 .It Sy WERASE
483 (Control-w or
484 .Sy ASCII ETX )
485 erases the preceding
486 .Dq word .
487 It does not erase beyond the start of a line, as delimited by a
488 .Sy NL ,
489 .Sy EOF ,
490 .Sy EOL ,
491 or
492 .Sy EOL2
493 character.
494 .It Sy KILL
495 (Control-u or
496 .Sy ASCII NAK )
497 deletes the entire line, as delimited by a
498 .Sy NL ,
499 .Sy EOF ,
500 .Sy EOL ,
501 or
502 .Sy EOL2
503 character.
504 .It Sy REPRINT
505 (Control-r or
506 .Sy ASCII DC2 )
507 reprints all characters, preceded by a newline, that have not been read.
508 .It Sy EOF
509 (Control-d or
510 .Sy ASCII EOT )
511 may be used to generate an end-of-file from a terminal.
512 When received, all the characters waiting to be read are immediately
513 passed to the program, without waiting for a newline, and the
514 .Sy EOF
515 is discarded.
516 Thus, if no characters are waiting (that is, the
517 .Sy EOF
518 occurred
519 at the beginning of a line) zero characters are passed back, which is the
520 standard end-of-file indication.
521 Unless escaped, the
522 .Sy EOF
523 character is not
524 echoed.
525 Because
526 .Sy EOT
527 is the default
528 .Sy EOF
529 character, this prevents
530 terminals that respond to
531 .Sy EOT
532 from hanging up.
533 .It Sy NL
534 .Pq Sy ASCII LF
535 is the normal line delimiter.
536 It cannot be changed or escaped.
537 .It Sy EOL
538 .Pq Sy ASCII NULL
539 is an additional line delimiter, like
540 .Sy NL .
541 It is not normally used.
542 .It Sy EOL2
543 is another additional line delimiter.
544 .It Sy SWTCH
545 (Control-z or
546 .Sy ASCII EM )
547 Header file symbols related to this special
548 character are present for compatibility purposes only and the kernel takes no
549 special action on matching SWTCH (except to discard the character).
550 .It Sy SUSP
551 (Control-z or
552 .Sy ASCII SUB )
553 generates a
554 .Dv SIGTSTP
555 signal.
556 .Dv SIGTSTP
557 stops all processes in the foreground process group for that terminal.
558 .It Sy DSUSP
559 (Control-y or
560 .Sy ASCII EM ) .
561 It generates a
562 .Dv SIGTSTP
563 signal as
564 .Sy SUSP
565 does, but the signal is sent when a process in the foreground
566 process group attempts to read the
567 .Sy DSUSP
568 character, rather than when it is typed.
569 .It Sy STOP
570 (Control-s or
571 .Sy ASCII DC3 )
572 can be used to suspend output temporarily.
573 It is useful with
574 .Sy CRT
575 terminals to prevent output from disappearing before it can be read.
576 While output is suspended,
577 .Sy STOP
578 characters are ignored and
579 not read.
580 .It Sy START
581 (Control-q or
582 .Sy ASCII DC1 )
583 is used to resume output.
584 Output has been suspended by a
585 .Sy STOP
586 character.
587 While output is not suspended,
588 .Sy START
589 characters are ignored and not read.
590 .It Sy DISCARD
591 (Control-o or
592 .Sy ASCII SI )
593 causes subsequent output to be discarded.
594 Output is discarded until another
595 .Sy DISCARD
596 character is typed, more input
597 arrives, or the condition is cleared by a program.
598 .It Sy STATUS
599 (Control-t or
600 .Sy ASCII DC4 )
601 generates a
602 .Dv SIGINFO
603 signal.
604 Processes with a handler will output status information when they receive
605 .Dv SIGINFO ,
606 for
607 example,
608 .Xr dd 1M .
609 If a process does not have a
610 .Dv SIGINFO
611 handler, the
612 signal will be ignored.
613 .It Sy LNEXT
614 (Control-v or
615 .Sy ASCII SYN )
616 causes the special meaning of the next character to be ignored.
617 This works for all the special characters mentioned above.
618 It
619 allows characters to be input that would otherwise be interpreted by the system
620 (for example
621 .Sy KILL ,
622 .Sy QUIT ) .
623 The character values for
624 .Sy INTR ,
625 .Sy QUIT ,
626 .Sy ERASE ,
627 .Sy ERASE2 ,
628 .Sy WERASE ,
629 .Sy KILL ,
630 .Sy REPRINT ,
631 .Sy EOF ,
632 .Sy EOL ,
633 .Sy EOL2 ,
634 .Sy SWTCH ,
635 .Sy SUSP ,
636 .Sy DSUSP ,
637 .Sy STOP ,
638 .Sy START ,
639 .Sy DISCARD ,
640 .Sy STATUS ,
641 and
642 .Sy LNEXT
643 may be changed to suit individual tastes.
644 If the value of a special control character
645 is
646 .Dv _POSIX_VDISABLE
647 (0), the function of that special control character is disabled.
648 The
649 .Sy ERASE ,
650 .Sy ERASE2 ,
651 .Sy KILL ,
652 and
653 .Sy EOF
654 characters may be
655 escaped by a preceding backslash (\e) character, in which case no special
656 function is done.
657 Any of the special characters may be preceded by the
658 .Sy LNEXT
659 character, in
660 which case no special function is done.
661 .El
662 .Ss "Modem Disconnect"
663 When a modem disconnect is detected, a
664 .Dv SIGHUP
665 signal is sent to the
666 terminal's controlling process.
667 Unless other arrangements have been made, these
668 signals cause the process to terminate.
669 If
670 .Dv SIGHUP
671 is ignored or caught,
672 any subsequent read returns with an end-of-file indication until the terminal
673 is closed.
674 .Pp
675 If the controlling process is not in the foreground process group of the
676 terminal, a
677 .Dv SIGTSTP
678 is sent to the terminal's foreground process group.
679 Unless other arrangements have been made, these signals cause the processes to
680 stop.
681 .Pp
682 Processes in background process groups that attempt to access the controlling
683 terminal after modem disconnect while the terminal is still allocated to the
684 session will receive appropriate
685 .Dv SIGTTOU
686 and
687 .Dv SIGTTIN
688 signals.
689 Unless other arrangements have been made, this signal causes the processes to
690 stop.
691 .Pp
692 The controlling terminal will remain in this state until it is reinitialized
693 with a successful open by the controlling process, or deallocated by the
694 controlling process.
695 .Ss "Terminal Parameters"
696 The parameters that control the behavior of devices and modules providing the
697 .Vt termios
698 interface are specified by the
699 .Vt termios
700 structure defined by
701 .In termios.h .
702 Several
703 .Xr ioctl 2
704 system calls that fetch or change
705 these parameters use this structure that contains the following members:
706 .Bd -literal -offset 2n
707 tcflag_t c_iflag; /* input modes */
708 tcflag_t c_oflag; /* output modes */
709 tcflag_t c_cflag; /* control modes */
710 tcflag_t c_lflag; /* local modes */
711 cc_t c_cc[NCCS]; /* control chars */
712 .Ed
713 .Pp
714 The special control characters are defined by the array
715 .Fa c_cc .
716 The symbolic name
717 .Dv NCCS
718 is the size of the Control-character array and is also
719 defined by
720 .In termios.h .
721 The relative positions, subscript names, and
722 typical default values for each function are as follows:
723 .Bl -column "Relative Position" "Subscript Name" "Typical Default Value"
724 .It Relative Position Ta Subscript Name Ta Typical Default Value
725 .It 0 Ta Dv VINTR Ta Sy ETX
726 .It 1 Ta Dv VQUIT Ta Sy FS
727 .It 2 Ta Dv VERASE Ta Sy DEL
728 .It 3 Ta Dv VKILL Ta Sy NAK
729 .It 4 Ta Dv VEOF Ta Sy EOT
730 .It 5 Ta Dv VEOL Ta Sy NUL
731 .It 6 Ta Dv VEOL2 Ta Sy NUL
732 .It 7 Ta Dv VWSTCH Ta Sy NUL
733 .It 8 Ta Dv VSTART Ta Sy NUL
734 .It 9 Ta Dv VSTOP Ta Sy DC3
735 .It 10 Ta Dv VSUSP Ta Sy SUB
736 .It 11 Ta Dv VDSUSP Ta Sy EM
737 .It 12 Ta Dv VREPRINT Ta Sy DC2
738 .It 13 Ta Dv VDISCARD Ta Sy SI
739 .It 14 Ta Dv VWERASE Ta Sy ETB
740 .It 15 Ta Dv VLNEXT Ta Sy SYN
741 .It 16 Ta Dv VSTATUS Ta Sy DC4
742 .It 17 Ta Dv VERASE2 Ta Sy BS
743 .It 18-19 Ta Reserved Ta
744 .El
745 .Ss "Input Modes"
746 The
747 .Fa c_iflag
748 field describes the basic terminal input control:
749 .Pp
750 .Bl -tag -width "IMAXBEL" -offset 2n -compact
751 .It Dv IGNBRK
752 Ignore break condition.
753 .It Dv BRKINT
754 Signal interrupt on break.
755 .It Dv IGNPAR
756 Ignore characters with parity errors.
757 .It Dv PARMRK
758 Mark parity errors.
759 .It Dv INPCK
760 Enable input parity check.
761 .It Dv ISTRIP
762 Strip character.
763 .It Dv INLCR
764 Map NL to CR on input.
765 .It Dv IGNCR
766 Ignore CR.
767 .It Dv ICRNL
768 Map CR to NL on input.
769 .It Dv IUCLC
770 Map upper-case to lower-case on input.
771 .It Dv IXON
772 Enable start/stop output control.
773 .It Dv IXANY
774 Enable any character to restart output.
775 .It Dv IXOFF
776 Enable start/stop input control.
777 .It Dv IMAXBEL
778 Echo
779 .Sy BEL
780 on input line too long.
781 .El
782 .Pp
783 If
784 .Dv IGNBRK
785 is set, a break condition (a character framing error with data
786 all zeros) detected on input is ignored, that is, not put on the input queue
787 and therefore not read by any process.
788 If
789 .Dv IGNBRK
790 is not set and
791 .Dv BRKINT
792 is set, the break condition shall flush the input and output
793 queues and if the terminal is the controlling terminal of a foreground process
794 group, the break condition generates a single
795 .Dv SIGINT
796 signal to that
797 foreground process group.
798 If neither
799 .Dv IGNBRK
800 nor
801 .Dv BRKINT
802 is set, a
803 break condition is read as a single
804 .Ql \e0
805 .Pq Sy ASCII NULL
806 character, or if
807 .Dv PARMRK
808 is set, as
809 .Ql \e377 ,
810 .Ql \e0 ,
811 .Em c ,
812 where
813 .Ql \e377
814 is a single character
815 with value 377 octal (0xff hex, 255 decimal),
816 .Ql \e0
817 is a single character with value
818 .Sy 0 ,
819 and
820 .Em c
821 is the errored character received.
822 .Pp
823 If
824 .Dv IGNPAR
825 is set, a byte with framing or parity errors (other than
826 break) is ignored.
827 .Pp
828 If
829 .Dv PARMRK
830 is set, and
831 .Dv IGNPAR
832 is not set, a byte with a framing or
833 parity error (other than break) is given to the application as the
834 three-character sequence:
835 .Ql \e377 ,
836 .Ql \e0 ,
837 c, where
838 .Ql \e377
839 is a single character with value 377 octal (0xff hex, 255 decimal),
840 .Ql \e0
841 is a single character with value 0, and c is the errored character received.
842 To avoid ambiguity in this case, if
843 .Dv ISTRIP
844 is not set, a valid character
845 of
846 .Ql \e377
847 is given to the application as
848 .Ql \e377 .
849 If neither
850 .Dv IGNPAR
851 nor
852 .Dv PARMRK
853 is set, a framing or parity error (other than break) is given to
854 the application as a single
855 .Ql \e0
856 .Po
857 .Sy ASCII NULL
858 .Pc
859 character.
860 .Pp
861 If
862 .Dv INPCK
863 is set, input parity checking is enabled.
864 If
865 .Dv INPCK
866 is not
867 set, input parity checking is disabled.
868 This allows output parity generation
869 without input parity errors.
870 Note that whether input parity checking is
871 enabled or disabled is independent of whether parity detection is enabled or
872 disabled.
873 If parity detection is enabled but input parity checking is
874 disabled, the hardware to which the terminal is connected will recognize the
875 parity bit, but the terminal special file will not check whether this is set
876 correctly or not.
877 .Pp
878 If
879 .Dv ISTRIP
880 is set, valid input characters are first stripped to seven
881 bits, otherwise all eight bits are processed.
882 .Pp
883 If
884 .Dv INLCR
885 is set, a received
886 .Sy NL
887 character is translated into a
888 .Sy CR
889 character.
890 If
891 .Dv IGNCR
892 is set, a received
893 .Sy CR
894 character is ignored (not read).
895 Otherwise, if
896 .Dv ICRNL
897 is set, a received
898 .Sy CR
899 character is translated into a
900 .Sy NL
901 character.
902 .Pp
903 If
904 .Dv IUCLC
905 is set, a received upper case, alphabetic character is
906 translated into the corresponding lower case character.
907 .Pp
908 If
909 .Dv IXON
910 is set, start/stop output control is enabled.
911 A received
912 .Sy STOP
913 character suspends output and a received
914 .Sy START
915 character
916 restarts output.
917 The
918 .Sy STOP
919 and
920 .Sy START
921 characters will not be read,
922 but will merely perform flow control functions.
923 If
924 .Dv IXANY
925 is set, any
926 input character restarts output that has been suspended.
927 .Pp
928 If
929 .Dv IXOFF
930 is set, the system transmits a
931 .Sy STOP
932 character when the
933 input queue is nearly full, and a
934 .Sy START
935 character when enough input has
936 been read so that the input queue is nearly empty again.
937 .Pp
938 If
939 .Dv IMAXBEL
940 is set, the
941 .Sy ASCII BEL
942 character is echoed if the input stream overflows.
943 Further input is not stored, but any input already present in
944 the input stream is not disturbed.
945 If
946 .Dv IMAXBEL
947 is not set, no
948 .Sy BEL
949 character is echoed, and all input present in the input queue is discarded if
950 the input stream overflows.
951 .Ss "Output Modes"
952 The
953 .Fa c_oflag
954 field specifies the system treatment of output:
955 .Pp
956 .Bl -tag -width ONLRET -offset 2n -compact
957 .It Dv OPOST
958 Post-process output.
959 .It Dv OLCUC
960 Map lower case to upper on output.
961 .It Dv ONLCR
962 Map NL to CR-NL on output.
963 .It Dv OCRNL
964 Map CR to NL on output.
965 .It Dv ONOCR
966 No
967 .Sy CR
968 output at column 0.
969 .It Dv ONLRET
970 .Sy NL
971 performs
972 .Sy CR
973 function.
974 .It Dv OFILL
975 Use fill characters for delay.
976 .It Dv OFDEL
977 Fill is
978 .Sy DEL ,
979 else
980 .Sy INULL .
981 .It Dv NLDLY
982 Select newline delays:
983 .Bl -tag -width NL0 -compact -offset 2n
984 .It Sy NL0
985 .It Sy NL1
986 .El
987 .It Dv CRDLY
988 Select carriage-return delays:
989 .Bl -tag -width CR0 -compact -offset 2n
990 .It Dv CR0
991 .It Dv CR1
992 .It Dv CR2
993 .It Dv CR3
994 .El
995 .It Dv TABDLY
996 Select horizontal tab delays or tab expansion:
997 .Bl -tag -width XTABS -compact -offset 2n
998 .It Dv TAB0
999 .It Dv TAB1
1000 .It Dv TAB2
1001 .It Dv TAB3
1002 Expand tabs to spaces
1003 .It Dv XTABS
1004 Expand tabs to spaces
1005 .El
1006 .It Dv BSDLY
1007 Select backspace delays:
1008 .Bl -tag -width BS0 -offset 2n -compact
1009 .It Dv BS0
1010 .It Dv BS1
1011 .El
1012 .It Dv VTDLY
1013 Select vertical tab delays:
1014 .Bl -tag -width VT0 -offset 2n -compact
1015 .It Dv VT0
1016 .It Dv VT1
1017 .El
1018 .It Dv FFDLY
1019 Select form feed delays:
1020 .Bl -tag -width FF0 -offset 2n -compact
1021 .It Dv FF0
1022 .It Dv FF1
1023 .El
1024 .El
1025 .Pp
1026 If
1027 .Dv OPOST
1028 is set, output characters are post-processed as indicated by the
1029 remaining flags; otherwise, characters are transmitted without change.
1030 .Pp
1031 If
1032 .Dv OLCUC
1033 is set, a lower case alphabetic character is transmitted as the
1034 corresponding upper case character.
1035 This function is often used in conjunction
1036 with
1037 .Dv IUCLC .
1038 .Pp
1039 If
1040 .Dv ONLCR
1041 is set, the
1042 .Sy NL
1043 character is transmitted as the
1044 .Sy CR-NL
1045 character pair.
1046 If
1047 .Dv OCRNL
1048 is set, the
1049 .Sy CR
1050 character is transmitted as the
1051 .Sy NL
1052 character.
1053 If
1054 .Dv ONOCR
1055 is set, no
1056 .Sy CR
1057 character is transmitted when at column 0 (first position).
1058 If
1059 .Dv ONRET
1060 is set, the
1061 .Sy NL
1062 character is assumed to do the carriage-return function; the column
1063 pointer is set to 0 and the delays specified for
1064 .Sy CR
1065 are used.
1066 Otherwise, the
1067 .Sy NL
1068 character is assumed to do just the line-feed function; the column
1069 pointer remains unchanged.
1070 The column pointer is also set to 0 if the
1071 .Sy CR
1072 character is actually transmitted.
1073 .Pp
1074 The delay bits specify how long transmission stops to allow for mechanical or
1075 other movement when certain characters are sent to the terminal.
1076 In all cases, a value of 0 indicates no delay.
1077 If
1078 .Dv OFILL
1079 is set, fill characters are transmitted for delay instead of a timed delay.
1080 This is useful for high baud rate terminals that need only a minimal delay.
1081 If
1082 .Dv OFDEL
1083 is set, the
1084 fill character is
1085 .Sy DEL ;
1086 otherwise it is
1087 .Sy NULL .
1088 .Pp
1089 If a form-feed or vertical-tab delay is specified, it lasts for about 2
1090 seconds.
1091 .Pp
1092 Newline delay lasts about 0\&.10 seconds.
1093 If
1094 .Dv ONLRET
1095 is set, the carriage-return delays are used instead of the newline delays.
1096 If
1097 .Dv OFILL
1098 is set, two fill characters are transmitted.
1099 .Pp
1100 Carriage-return delay type 1 is dependent on the current column position, type
1101 2 is about 0\&.10 seconds, and type 3 is about 0\&.15 seconds.
1102 If
1103 .Dv OFILL
1104 is set, delay type 1 transmits two fill characters, and type 2 transmits four
1105 fill characters.
1106 .Pp
1107 Horizontal-tab delay type 1 is dependent on the current column position.
1108 Type 2 is about 0\&.10 seconds.
1109 Type 3 specifies that tabs are to be expanded into spaces.
1110 If
1111 .Dv OFILL
1112 is set, two fill characters are transmitted for any delay.
1113 .Pp
1114 Backspace delay lasts about 0\&.05 seconds.
1115 If
1116 .Dv OFILL
1117 is set, one fill character is transmitted.
1118 .Pp
1119 The actual delays depend on line speed and system load.
1120 .Ss "Control Modes"
1121 The
1122 .Fa c_cflag
1123 field describes the hardware control of the terminal:
1124 .Bl -tag -width CIBAUDEXT -offset 2n
1125 .It Dv CBAUD
1126 Baud rate:
1127 .Bl -tag -width B460800 -compact
1128 .It Dv B0
1129 Hang up
1130 .It Dv B50
1131 50 baud
1132 .It Dv B75
1133 75 baud
1134 .It Dv B110
1135 110 baud
1136 .It Dv B134
1137 134 baud
1138 .It Dv B150
1139 150 baud
1140 .It Dv B200
1141 200 baud
1142 .It Dv B300
1143 300 baud
1144 .It Dv B600
1145 600 baud
1146 .It Dv B1200
1147 1200 baud
1148 .It Dv B1800
1149 1800 baud
1150 .It Dv B2400
1151 2400 baud
1152 .It Dv B4800
1153 4800 baud
1154 .It Dv B9600
1155 9600 baud
1156 .It Dv B19200
1157 19200 baud
1158 .It Dv EXTA
1159 External A
1160 .It Dv B38400
1161 38400 baud
1162 .It Dv EXTB
1163 External B
1164 .It Dv B57600
1165 57600 baud
1166 .It Dv B76800
1167 76800 baud
1168 .It Dv B115200
1169 115200 baud
1170 .It Dv B153600
1171 153600 baud
1172 .It Dv B230400
1173 230400 baud
1174 .It Dv B307200
1175 307200 baud
1176 .It Dv B460800
1177 460800 baud
1178 .El
1179 .It Dv CSIZE
1180 Character size:
1181 .Bl -tag -width CIBAUDEXT -compact
1182 .It Dv CS5
1183 5 bits
1184 .It Dv CS6
1185 6 bits
1186 .It Dv CS7
1187 7 bits
1188 .It Dv CS8
1189 8 bits
1190 .It Dv CSTOPB
1191 Send two stop bits, else one
1192 .It Dv CREAD
1193 Enable receiver
1194 .It Dv PARENB
1195 Parity enable
1196 .It Dv PARODD
1197 Odd parity, else even
1198 .It Dv HUPCL
1199 Hang up on last close
1200 .It Dv CLOCAL
1201 Local line, else dial-up
1202 .It Dv CIBAUD
1203 Input baud rate, if different from output rate
1204 .It Dv PAREXT
1205 Extended parity for mark and space parity
1206 .It Dv CRTSXOFF
1207 Enable inbound hardware flow control
1208 .It Dv CRTSCTS
1209 Enable outbound hardware flow control
1210 .It Dv CBAUDEXT
1211 Bit to indicate output speed > B38400
1212 .It Dv CIBAUDEXT
1213 Bit to indicate input speed > B38400
1214 .El
1215 .El
1216 .Pp
1217 The
1218 .Dv CBAUD
1219 bits together with the
1220 .Dv CBAUDEXT
1221 bit specify the output baud rate.
1222 To retrieve the output speed from the
1223 .Vt termios
1224 structure pointed to by
1225 .Fa termios_p
1226 see the following code segment.
1227 .Bd -literal -offset 2n
1228 speed_t ospeed;
1229 if (termios_p->c_cflag & CBAUDEXT)
1230 ospeed = (termios_p->c_cflag & CBAUD) + CBAUD + 1;
1231 else
1232 ospeed = termios_p->c_cflag & CBAUD;
1233 .Ed
1234 .Pp
1235 To store the output speed in the termios structure pointed to by
1236 .Fa termios_p
1237 see the following code segment.
1238 .Bd -literal -offset 2n
1239 speed_t ospeed;
1240 if (ospeed > CBAUD) {
1241 termios_p->c_cflag |= CBAUDEXT;
1242 ospeed -= (CBAUD + 1);
1243 } else {
1244 termios_p->c_cflag &= ~CBAUDEXT;
1245 }
1246 termios_p->c_cflag =
1247 (termios_p->c_cflag & ~CBAUD) | (ospeed & CBAUD);
1248 .Ed
1249 .Pp
1250 The zero baud rate,
1251 .Dv B0 ,
1252 is used to hang up the connection.
1253 If
1254 .Dv B0
1255 is specified, the data-terminal-ready signal is not asserted.
1256 Normally, this disconnects the line.
1257 .Pp
1258 If the
1259 .Dv CIBAUDEXT
1260 or
1261 .Dv CIBAUD
1262 bits are not zero, they specify the input baud rate, with the
1263 .Dv CBAUDEXT
1264 and
1265 .Dv CBAUD
1266 bits specifying the output baud rate; otherwise, the output and input baud
1267 rates are both specified by the
1268 .Dv CBAUDEXT
1269 and
1270 .Dv CBAUD
1271 bits.
1272 The values for the
1273 .Dv CIBAUD
1274 bits are the same as the values for the
1275 .Dv CBAUD
1276 bits, shifted left
1277 .Dv IBSHIFT
1278 bits.
1279 For any particular hardware, impossible speed changes are
1280 ignored.
1281 To retrieve the input speed in the
1282 .Vt termios
1283 structure pointed to
1284 by
1285 .Fa termios_p
1286 see the following code segment.
1287 .Bd -literal -offset 2n
1288 speed_t ispeed;
1289 if (termios_p->c_cflag & CIBAUDEXT) {
1290 ispeed = ((termios_p->c_cflag & CIBAUD) >> IBSHIFT)
1291 + (CIBAUD >> IBSHIFT) + 1;
1292 } else {
1293 ispeed = (termios_p->c_cflag & CIBAUD) >> IBSHIFT;
1294 }
1295 .Ed
1296 .Pp
1297 To store the input speed in the
1298 .Vt termios
1299 structure pointed to by
1300 .Fa termios_p
1301 see the following code segment.
1302 .Bd -literal -offset 2n
1303 speed_t ispeed;
1304 if (ispeed == 0) {
1305 ispeed = termios_p->c_cflag & CBAUD;
1306 if (termios_p->c_cflag & CBAUDEXT)
1307 ispeed += (CBAUD + 1);
1308 }
1309 if ((ispeed << IBSHIFT) > CIBAUD) {
1310 termios_p->c_cflag |= CIBAUDEXT;
1311 ispeed -= ((CIBAUD >> IBSHIFT) + 1);
1312 } else {
1313 termios_p->c_cflag &= ~CIBAUDEXT;
1314 }
1315 termios_p->c_cflag =
1316 (termios_p->c_cflag & ~CIBAUD) | ((ispeed << IBSHIFT) & CIBAUD);
1317 .Ed
1318 .Pp
1319 The
1320 .Dv CSIZE
1321 bits specify the character size in bits for both transmission and reception.
1322 This size does not include the parity bit, if any.
1323 If
1324 .Dv CSTOPB
1325 is set, two stop bits are used; otherwise, one stop bit is used.
1326 For example, at 110 baud, two stops bits are required.
1327 .Pp
1328 If
1329 .Dv PARENB
1330 is set, parity generation and detection is enabled, and a
1331 parity bit is added to each character.
1332 If parity is enabled, the
1333 .Dv PARODD
1334 flag specifies odd parity if set; otherwise, even parity is used.
1335 .Pp
1336 If
1337 .Dv CREAD
1338 is set, the receiver is enabled.
1339 Otherwise, no characters are received.
1340 .Pp
1341 If
1342 .Dv HUPCL
1343 is set, the line is disconnected when the last process with the
1344 line open closes it or terminates.
1345 That is, the data-terminal-ready signal is not asserted.
1346 .Pp
1347 If
1348 .Dv CLOCAL
1349 is set, the line is assumed to be a local, direct connection
1350 with no modem control; otherwise, modem control is assumed.
1351 .Pp
1352 If
1353 .Dv CRTSXOFF
1354 is set, inbound hardware flow control is enabled.
1355 .Pp
1356 If
1357 .Dv CRTSCTS
1358 is set, outbound hardware flow control is enabled.
1359 .Pp
1360 The four possible combinations for the state of
1361 .Dv CRTSCTS
1362 and
1363 .Dv CRTSXOFF
1364 bits and their interactions are described below.
1365 .Bl -tag -width "Case C:"
1366 .It Sy Case A :
1367 .Dv CRTSCTS
1368 off,
1369 .Dv CRTSXOFF
1370 off.
1371 In this case the hardware flow control is disabled.
1372 .It Sy Case B :
1373 .Dv CRTSCTS
1374 on,
1375 .Dv CRTSXOFF
1376 off.
1377 In this case only outbound hardware flow control is enabled.
1378 The state of CTS signal is used to do outbound flow control.
1379 It is expected that output will be suspended if CTS is low and resumed
1380 when CTS is high.
1381 .It Sy Case C :
1382 .Dv CRTSCTS
1383 off,
1384 .Dv CRTSXOFF
1385 on.
1386 In this case only inbound hardware flow control is enabled.
1387 The state of RTS signal is used to do inbound flow control.
1388 It is expected that input will be suspended if RTS is low and resumed when RTS
1389 is high.
1390 .It Sy Case D :
1391 .Dv CRTSCTS
1392 on,
1393 .Dv CRTSXOFF
1394 on.
1395 In this case both inbound and outbound hardware flow control are enabled.
1396 Uses the state of CTS signal to do outbound
1397 flow control and RTS signal to do inbound flow control.
1398 .El
1399 .Ss "Local Modes"
1400 The
1401 .Fa c_lflag
1402 field of the argument structure is used by the line
1403 discipline to control terminal functions.
1404 The basic line discipline provides the following:
1405 .Pp
1406 .Bl -tag -offset 2n -width SIGTTOU -compact
1407 .It Dv ISIG
1408 Enable signals.
1409 .It Dv ICANON
1410 Canonical input (erase and kill processing).
1411 .It Dv XCASE
1412 Canonical upper/lower presentation.
1413 .It Dv ECHO
1414 Enable echo.
1415 .It Dv ECHOE
1416 Echo erase character as
1417 .Sy BS Ns - Ns Sy SP Ns - Ns Sy BS
1418 &.
1419 .It Dv ECHOK
1420 Echo
1421 .Sy NL
1422 after kill character.
1423 .It Dv ECHONL
1424 Echo
1425 .Sy NL .
1426 .It Dv NOFLSH
1427 Disable flush after interrupt or quit.
1428 .It Dv TOSTOP
1429 Send
1430 .It Dv SIGTTOU
1431 for background output.
1432 .It Dv ECHOCTL
1433 Echo control characters as
1434 .Em char ,
1435 delete as ^?.
1436 .It Dv ECHOPRT
1437 Echo erase character as character erased.
1438 .It Dv ECHOKE
1439 .Sy BS Ns - Ns Sy SP Ns - Ns Sy BS
1440 erase entire line on line kill.
1441 .It Dv FLUSHO
1442 Output is being flushed.
1443 .It Dv PENDIN
1444 Retype pending input at next read or input character.
1445 .It Dv IEXTEN
1446 Enable extended (implementation-defined) functions.
1447 .El
1448 .Pp
1449 If
1450 .Dv ISIG
1451 is set, each input character is checked against the special
1452 control characters
1453 .Sy INTR ,
1454 .Sy QUIT ,
1455 .Sy SWTCH ,
1456 .Sy SUSP ,
1457 .Sy STATUS ,
1458 and
1459 .Sy DSUSP .
1460 If an input character matches one of these control characters, the function
1461 associated with that character is performed.
1462 .Po
1463 Note: If
1464 .Sy SWTCH
1465 is set and the character matches, the character is simply discarded.
1466 No other action is taken.
1467 .Pc
1468 If
1469 .Dv ISIG
1470 is not set, no checking is done.
1471 Thus, these special
1472 input functions are possible only if
1473 .Dv ISIG
1474 is set.
1475 .Pp
1476 If
1477 .Dv ICANON
1478 is set, canonical processing is enabled.
1479 This enables the erase
1480 and kill edit functions, and the assembly of input characters into lines
1481 delimited by
1482 .Sy NL-c ,
1483 .Sy EOF ,
1484 .Sy EOL ,
1485 and
1486 .Sy EOL .
1487 If
1488 .Dv ICANON
1489 is not set, read requests are satisfied directly from the input queue.
1490 A read is not satisfied until at least
1491 .Sy MIN
1492 characters have been received or the timeout value
1493 .Sy TIME
1494 has expired between characters.
1495 This allows fast bursts of input to be read efficiently while still allowing
1496 single character input.
1497 The time value represents tenths of seconds.
1498 .Pp
1499 If
1500 .Dv XCASE
1501 is set and
1502 .Dv ICANON
1503 is set, an upper case letter is
1504 accepted on input if preceded by a backslash
1505 .Ql \e
1506 character, and is output preceded by a backslash
1507 .Ql \e
1508 character.
1509 In this mode, the
1510 following escape sequences are generated on output and accepted on input:
1511 .Bl -column "FOR:" "USE:" -offset 2n
1512 .It FOR: Ta USE:
1513 .It ` Ta \e'
1514 .It | Ta \e!
1515 .It \(ap Ta \e^
1516 .It { Ta \e(
1517 .It } Ta \e)
1518 .It \e Ta \e\e
1519 .El
1520 .Pp
1521 For example, input A as \ea, \en as \e\en, and \eN as \e\e\en.
1522 .Pp
1523 If
1524 .Dv ECHO
1525 is set, characters are echoed as received.
1526 .Pp
1527 When
1528 .Dv ICANON
1529 is set, the following echo functions are possible.
1530 .Bl -bullet -offset indent
1531 .It
1532 If
1533 .Dv ECHO
1534 and
1535 .Dv ECHOE
1536 are set, and
1537 .Dv ECHOPRT
1538 is not set, the
1539 .Sy ERASE ,
1540 .Sy ERASE2 ,
1541 and
1542 .Sy WERASE
1543 characters are echoed as one or
1544 more ASCII BS SP BS, which clears the last character(s) from a
1545 .Sy CRT
1546 screen.
1547 .It
1548 If
1549 .Dv ECHO ,
1550 .Dv ECHOPRT ,
1551 and
1552 .Dv IEXTEN
1553 are set, the first
1554 .Sy ERASE ,
1555 .Sy ERASE2 ,
1556 and
1557 .Sy WERASE
1558 character in a sequence echoes as a backslash
1559 .Ql \e ,
1560 followed by the characters being erased.
1561 Subsequent
1562 .Sy ERASE
1563 and
1564 .Sy WERASE
1565 characters echo the characters being erased, in reverse order.
1566 The
1567 next non-erase character causes a
1568 .Ql /
1569 (slash) to be typed before it is echoed.
1570 .Dv ECHOPRT
1571 should be used for hard copy terminals.
1572 .It
1573 If
1574 .Dv ECHOKE
1575 and
1576 .Dv IEXTEN
1577 are set, the kill character is echoed by
1578 erasing each character on the line from the screen (using the mechanism
1579 selected by
1580 .Dv ECHOE
1581 and
1582 .Dv ECHOPR ) .
1583 .It
1584 If
1585 .Dv ECHOK
1586 is set, and
1587 .Dv ECHOKE
1588 is not set, the
1589 .Sy NL
1590 character is
1591 echoed after the kill character to emphasize that the line is deleted.
1592 Note
1593 that a
1594 .Ql \e
1595 (escape) character or an
1596 .Sy LNEXT
1597 character preceding the erase
1598 or kill character removes any special function.
1599 .It
1600 If
1601 .Dv ECHONL
1602 is set, the
1603 .Sy NL
1604 character is echoed even if
1605 .Dv ECHO
1606 is not set.
1607 This is useful for terminals set to local echo (so called
1608 half-duplex).
1609 .El
1610 .Pp
1611 If
1612 .Dv ECHOCTL
1613 and
1614 .Dv IEXTEN
1615 are set, all control characters (characters
1616 with codes between 0 and 37 octal) other than
1617 .Sy ASCII TAB ,
1618 .Sy ASCII NL ,
1619 the
1620 .Sy START
1621 character, and the
1622 .Sy STOP
1623 character,
1624 .Sy ASCII CR ,
1625 and
1626 .Sy ASCII BS
1627 are echoed as
1628 .No ^ Ns Em X ,
1629 where
1630 .Em X
1631 is the character given by adding
1632 .Ql 100
1633 octal to the code of the control character (so
1634 that the character with octal code
1635 .Ql 1
1636 is echoed as
1637 .No ^ Ns Sy A ) ,
1638 and the
1639 .Sy ASCII DEL
1640 character,
1641 with code
1642 .Ql 177
1643 octal, is echoed as
1644 .No ^ Ns Sy \&? .
1645 .Pp
1646 If
1647 .Dv NOFLSH
1648 is set, the normal flush of the input and output queues
1649 associated with the
1650 .Sy INTR ,
1651 .Sy QUIT ,
1652 .Sy STATUS ,
1653 and
1654 .Sy SUSP
1655 characters is not done.
1656 This bit should be set when restarting system calls
1657 that read from or write to a terminal
1658 .Po
1659 see
1660 .Xr sigaction 2
1661 .Pc .
1662 .Pp
1663 If
1664 .Dv TOSTOP
1665 and
1666 .Dv IEXTEN
1667 are set, the signal
1668 .Dv SIGTTOU
1669 is sent to
1670 a process that tries to write to its controlling terminal if it is not in the
1671 foreground process group for that terminal.
1672 This signal normally stops the process.
1673 Otherwise, the output generated by that process is output to the
1674 current output stream.
1675 Processes that are blocking or ignoring
1676 .Dv SIGTTOU
1677 signals are excepted and allowed to produce output, if any.
1678 .Pp
1679 If
1680 .Dv FLUSHO
1681 and
1682 .Dv IEXTEN
1683 are set, data written to the terminal is
1684 discarded.
1685 This bit is set when the
1686 .Sy FLUSH
1687 character is typed.
1688 A program can cancel the effect of typing the
1689 .Sy FLUSH
1690 character by clearing
1691 .Dv FLUSHO .
1692 .Pp
1693 If
1694 .Dv PENDIN
1695 and
1696 .Dv IEXTEN
1697 are set, any input that has not yet been read
1698 is reprinted when the next character arrives as input.
1699 .Dv PENDIN
1700 is then
1701 automatically cleared.
1702 .Pp
1703 If
1704 .Dv IEXTEN
1705 is set, the following implementation-defined functions are
1706 enabled: special characters (
1707 .Sy WERASE ,
1708 .Sy REPRINT ,
1709 .Sy DISCARD ,
1710 and
1711 .Sy LNEXT )
1712 and local flags (
1713 .Dv TOSTOP ,
1714 .Dv ECHOCTL ,
1715 .Dv ECHOPRT ,
1716 .Dv ECHOKE ,
1717 .Dv FLUSHO ,
1718 and
1719 .Dv PENDIN ) .
1720 .Ss "Minimum and Timeout"
1721 The
1722 .Sy MIN
1723 and
1724 .Sy TIME
1725 values were described previously, in the
1726 subsection,
1727 .Sy Non-canonical Mode Input Processing .
1728 The initial value of
1729 .Sy MIN
1730 is 1, and the initial value of
1731 .Sy TIME
1732 is 0.
1733 .Ss "Terminal Size"
1734 The number of lines and columns on the terminal's display is specified in the
1735 .Vt winsize
1736 structure defined by
1737 .In sys/termios.h
1738 and includes the following members:
1739 .Bd -literal -offset 2n
1740 unsigned short ws_row; /* rows, in characters */
1741 unsigned short ws_col; /* columns, in characters */
1742 unsigned short ws_xpixel; /* horizontal size, in pixels */
1743 unsigned short ws_ypixel; /* vertical size, in pixels */
1744 .Ed
1745 .Ss "Termio Structure"
1746 The SunOS/SVR4
1747 .Vt termio
1748 structure is used by some
1749 .Fn ioctl Ns s ;
1750 it is defined by
1751 .In sys/termio.h
1752 and includes the following members:
1753 .Bd -literal -offset 2n
1754 unsigned short c_iflag; /* input modes */
1755 unsigned short c_oflag; /* output modes */
1756 unsigned short c_cflag; /* control modes */
1757 unsigned short c_lflag; /* local modes */
1758 char c_line; /* line discipline */
1759 unsigned char c_cc[NCC]; /* control chars */
1760 .Ed
1761 .Pp
1762 The special control characters are defined by the array
1763 .Fa c_cc .
1764 The symbolic name
1765 .Dv NCC
1766 is the size of the Control-character array and is also
1767 defined by
1768 .In termio.h .
1769 The relative positions, subscript names, and typical
1770 default values for each function are as follows:
1771 .Bl -column "Relative Positions" "Subscript Names" "Typical Default Values"
1772 .It Relative Positions Ta Subscript Names Ta Typical Default Values
1773 .It 0 Ta VINTR Ta EXT
1774 .It 1 Ta VQUIT Ta FS
1775 .It 2 Ta VERASE Ta DEL
1776 .It 3 Ta VKILL Ta NAK
1777 .It 4 Ta VEOF Ta EOT
1778 .It 5 Ta VEOL Ta NUL
1779 .It 6 Ta VEOL2 Ta NUL
1780 .It 7 Ta Reserved Ta
1781 .El
1782 .Pp
1783 The
1784 .Sy MIN
1785 values is stored in the
1786 .Dv VMIN
1787 element of the
1788 .Fa c_cc
1789 array; the
1790 .Sy TIME
1791 value is stored in the
1792 .Dv VTIME
1793 element of the
1794 .Fa c_cc
1795 array.
1796 The
1797 .Dv VMIN
1798 element is the same element as the
1799 .Dv VEOF
1800 element; the
1801 .Dv VTIME
1802 element is the same element as the
1803 .Dv VEOL
1804 element.
1805 .Pp
1806 The calls that use the
1807 .Va termio
1808 structure only affect the flags and control
1809 characters that can be stored in the
1810 .Vt termio
1811 structure; all other flags and control characters are unaffected.
1812 .Ss "Modem Lines"
1813 On special files representing serial ports, modem control lines can be read.
1814 Control lines (if the underlying hardware supports it) may also be changed.
1815 Status lines are read-only.
1816 The following modem control and status lines may be
1817 supported by a device; they are defined by
1818 .In sys/termios.h :
1819 .Pp
1820 .Bl -tag -width "TIOCM_DTR" -compact -offset 2n
1821 .It Dv TIOCM_LE
1822 line enable
1823 .It Dv TIOCM_DTR
1824 data terminal ready
1825 .It Dv TIOCM_RTS
1826 request to send
1827 .It Dv TIOCM_ST
1828 secondary transmit
1829 .It Dv TIOCM_SR
1830 secondary receive
1831 .It Dv TIOCM_CTS
1832 clear to send
1833 .It Dv TIOCM_CAR
1834 carrier detect
1835 .It Dv TIOCM_RNG
1836 ring
1837 .It Dv TIOCM_DSR
1838 data set ready
1839 .El
1840 .Pp
1841 .Dv TIOCM_CD
1842 is a synonym for
1843 .Dv TIOCM_CAR ,
1844 and
1845 .Dv TIOCM_RI
1846 is a synonym for
1847 .Dv TIOCM_RNG .
1848 Not all of these are necessarily supported by any
1849 particular device; check the manual page for the device in question.
1850 .Pp
1851 The software carrier mode can be enabled or disabled using the
1852 .Dv TIOCSSOFTCAR
1853 .Fn ioctl .
1854 If the software carrier flag for a line is off,
1855 the line pays attention to the hardware carrier detect (DCD) signal.
1856 The
1857 .Sy tty
1858 device associated with the line cannot be opened until
1859 .Sy DCD
1860 is asserted.
1861 If the software carrier flag is on, the line behaves as if
1862 .Sy DCD
1863 is always asserted.
1864 .Pp
1865 The software carrier flag is usually turned on for locally connected terminals
1866 or other devices, and is off for lines with modems.
1867 .Pp
1868 To be able to issue the
1869 .Dv TIOCGSOFTCAR
1870 and
1871 .Dv TIOCSSOFTCAR
1872 .Fn ioctl
1873 calls, the
1874 .Sy tty
1875 line should be opened with
1876 .Dv O_NDELAY
1877 so that the
1878 .Xr open 2
1879 will not wait for the carrier.
1880 .Ss "Default Values"
1881 The initial
1882 .Vt termios
1883 values upon driver open is configurable.
1884 This is accomplished by setting the "ttymodes" property in the file
1885 .Pa /kernel/drv/options.conf .
1886 Since this property is assigned during system
1887 initialization, any change to the "ttymodes" property will not take effect
1888 until the next reboot.
1889 The string value assigned to this property should be in
1890 the same format as the output of the
1891 .Xr stty 1
1892 command with the -g option.
1893 .Pp
1894 If this property is undefined, the following
1895 .Vt termios
1896 modes are in effect.
1897 The initial input control value is
1898 .Dv BRKINT ,
1899 .Dv ICRNL ,
1900 .Dv IXON ,
1901 .Dv IMAXBEL .
1902 The initial output control value is
1903 .Dv OPOST ,
1904 .Dv ONLCR ,
1905 .Dv TAB3 .
1906 The initial hardware control value is
1907 .Dv B9600 ,
1908 .Dv CS8 ,
1909 .Dv CREAD .
1910 The initial line-discipline control value is
1911 .Dv ISIG ,
1912 .Dv ICANON ,
1913 .Dv IEXTEN ,
1914 .Dv ECHO ,
1915 .Dv ECHOK ,
1916 .Dv ECHOE ,
1917 .Dv ECHOKE ,
1918 .Dv ECHOCTL .
1919 .Sh IOCTLS
1920 The
1921 .Fn ioctl Ns s
1922 supported by devices and
1923 .Sy STREAMS
1924 modules providing the
1925 .Xr termios 3C
1926 interface are listed below.
1927 Some calls may not be supported by all devices or modules.
1928 The functionality provided by these calls is also
1929 available through the preferred function call interface specified on
1930 .Nm termios .
1931 .Bl -tag -width TIOCSSOFTCAR
1932 .It Dv TCGETS
1933 The argument is a pointer to a
1934 .Vt termios
1935 structure.
1936 The current terminal parameters are fetched and stored into that structure.
1937 .It Dv TCSETS
1938 The argument is a pointer to a
1939 .Vt termios
1940 structure.
1941 The current terminal parameters are set from the values stored in that structure.
1942 The change is immediate.
1943 .It Dv TCSETSW
1944 The argument is a pointer to a
1945 .Vt termios
1946 structure.
1947 The current terminal parameters are set from the values stored in that structure.
1948 The change occurs after all characters queued for output have been transmitted.
1949 This form should be used when changing parameters that affect output.
1950 .It Dv TCSETSF
1951 The argument is a pointer to a
1952 .Vt termios
1953 structure.
1954 The current terminal parameters are set from the values stored in that structure.
1955 The change occurs after all characters queued for output have been transmitted;
1956 all characters queued for input are discarded and then the change occurs.
1957 .It Dv TCGETA
1958 The argument is a pointer to a
1959 .Vt termio
1960 structure.
1961 The current terminal parameters are fetched, and those parameters that can be
1962 stored in a
1963 .Vt termio
1964 structure are stored into that structure.
1965 .It Dv TCSETA
1966 The argument is a pointer to a
1967 .Vt termio
1968 structure.
1969 Those terminal parameters that can be stored in a
1970 .Vt termio
1971 structure are set from the values stored in that structure.
1972 The change is immediate.
1973 .It Dv TCSETAW
1974 The argument is a pointer to a
1975 .Vt termio
1976 structure.
1977 Those terminal parameters that can be stored in a
1978 .Vt termio
1979 structure are set from
1980 the values stored in that structure.
1981 The change occurs after all characters queued for output have been transmitted.
1982 This form should be used when changing parameters that affect output.
1983 .It Dv TCSETAF
1984 The argument is a pointer to a
1985 .Vt termio
1986 structure.
1987 Those terminal parameters that can be stored in a
1988 .Vt termio
1989 structure are set from the values stored in that structure.
1990 The change occurs after all characters queued
1991 for output have been transmitted; all characters queued for input are discarded
1992 and then the change occurs.
1993 .It Dv TCSBRK
1994 The argument is an
1995 .Vt int
1996 value.
1997 Wait for the output to drain.
1998 If the argument is
1999 .Sy 0 ,
2000 then send a break (zero valued bits for 0\&.25 seconds).
2001 .It Dv TCXONC
2002 Start/stop control.
2003 The argument is an
2004 .Vt int
2005 value.
2006 If the argument is
2007 .Sy 0 ,
2008 suspend output; if
2009 .Sy 1 ,
2010 restart suspended output; if
2011 .Sy 2 ,
2012 suspend input; if
2013 .Sy 3 ,
2014 restart suspended input.
2015 .It Dv TCFLSH
2016 The argument is an
2017 .Vt int
2018 value.
2019 If the argument is
2020 .Sy 0 ,
2021 flush the input queue; if
2022 .Sy 1 ,
2023 flush the output queue; if
2024 .Sy 2 ,
2025 flush both the input and output queues.
2026 .It Dv TIOCGPGRP
2027 The argument is a pointer to a
2028 .Vt pid_t .
2029 Set the value of that
2030 .Vt pid_t
2031 to the process group
2032 .Sy ID
2033 of the foreground process group associated with the terminal.
2034 See
2035 .Xr termios 3C
2036 for a description of
2037 .Dv TCGETPGRP .
2038 .It Dv TIOCSPGRP
2039 The argument is a pointer to a
2040 .Vt pid_t .
2041 Associate the process group whose
2042 process group
2043 .Sy ID
2044 is specified by the value of that
2045 .Vt pid_t
2046 with the terminal.
2047 The new process group value must be in the range of valid process
2048 group
2049 .Sy ID
2050 values.
2051 Otherwise, the error
2052 .Er EPERM
2053 is returned.
2054 .It Dv TIOCGSID
2055 The argument is a pointer to a
2056 .Vt pid_t .
2057 The session ID of the terminal is fetched and stored in the
2058 .Vt pid_t .
2059 .It Dv TIOCGWINSZ
2060 The argument is a pointer to a
2061 .Vt winsize
2062 structure.
2063 The terminal driver's
2064 notion of the terminal size is stored into that structure.
2065 .It Dv TIOCSWINSZ
2066 The argument is a pointer to a
2067 .Vt winsize
2068 structure.
2069 The terminal driver's
2070 notion of the terminal size is set from the values specified in that structure.
2071 If the new sizes are different from the old sizes, a
2072 .Dv SIGWINCH
2073 signal is set to the process group of the terminal.
2074 .It Dv TIOCMBIS
2075 The argument is a pointer to an
2076 .Vt int
2077 whose value is a mask containing modem control lines to be turned on.
2078 The control lines whose bits are set in
2079 the argument are turned on; no other control lines are affected.
2080 .It Dv TIOCMBIC
2081 The argument is a pointer to an
2082 .Vt int
2083 whose value is a mask containing modem control lines to be turned off.
2084 The control lines whose bits are set in
2085 the argument are turned off; no other control lines are affected.
2086 .It Dv TIOCMGET
2087 The argument is a pointer to an
2088 .Vt int .
2089 The current state of the modem
2090 status lines is fetched and stored in the
2091 .Vt int
2092 pointed to by the argument.
2093 .It Dv TIOCMSET
2094 The argument is a pointer to an
2095 .Vt int
2096 containing a new set of modem control lines.
2097 The modem control lines are turned on or off, depending on
2098 whether the bit for that mode is set or clear.
2099 .It Dv TIOCSPPS
2100 The argument is a pointer to an
2101 .Vt int
2102 that determines whether pulse-per-second event handling is to be enabled
2103 (non-zero) or disabled (zero).
2104 If a one-pulse-per-second reference clock is attached to the serial line's data
2105 carrier detect input, the local system clock will be calibrated to it.
2106 A clock with a high error, that is, a deviation of more than 25 microseconds
2107 per tick, is ignored.
2108 .It Dv TIOCGPPS
2109 The argument is a pointer to an
2110 .Vt int ,
2111 in which the state of the even handling is returned.
2112 The
2113 .Vt int
2114 is set to a non-zero value if pulse-per-second (PPS) handling has been enabled.
2115 Otherwise, it is set to zero.
2116 .It Dv TIOCGSOFTCAR
2117 The argument is a pointer to an
2118 .Vt int
2119 whose value is
2120 .Sy 1
2121 or
2122 .Sy 0 ,
2123 depending on whether the software carrier detect is turned on or off.
2124 .It Dv TIOCSSOFTCAR
2125 The argument is a pointer to an
2126 .Vt int
2127 whose value is
2128 .Sy 1
2129 or
2130 .Sy 0 .
2131 The value of the integer should be
2132 .Sy 0
2133 to turn off software carrier, or
2134 .Sy 1
2135 to turn it on.
2136 .It Dv TIOCGPPSEV
2137 The argument is a pointer to a
2138 .Vt "struct ppsclockev" .
2139 This structure contains the following members:
2140 .Bd -literal -offset 2n
2141 struct timeval tv;
2142 uint32_t serial;
2143 .Ed
2144 .Pp
2145 .Fa tv
2146 is the system clock timestamp when the event (pulse on the
2147 .Sy DCD
2148 pin) occurred.
2149 .Fa serial
2150 is the ordinal of the event, which each consecutive event
2151 being assigned the next ordinal.
2152 The first event registered gets a
2153 .Fa serial
2154 value of
2155 .Sy 1 .
2156 The
2157 .Dv TIOCGPPSEV
2158 returns the last event registered; multiple calls will persistently return the
2159 same event until a new one is registered.
2160 In addition to time stamping and saving the event, if it is of
2161 one-second period and of consistently high accuracy, the local system clock
2162 will automatically calibrate to it.
2163 .El
2164 .Sh FILES
2165 Files in or under
2166 .Pa /dev
2167 .Sh SEE ALSO
2168 .Xr stty 1 ,
2169 .Xr fork 2 ,
2170 .Xr getpgid 2 ,
2171 .Xr getsid 2 ,
2172 .Xr ioctl 2 ,
2173 .Xr setsid 2 ,
2174 .Xr sigaction 2 ,
2175 .Xr signal 3C ,
2176 .Xr tcsetpgrp 3C ,
2177 .Xr termios 3C ,
2178 .Xr signal.h 3HEAD ,
2179 .Xr streamio 7I