| blob | ba225db401bdbb5293062f0657a5676a0aec3a62 |
1 .\" $NetBSD: termios.4,v 1.32 2006/10/13 20:31:27 wiz Exp $
2 .\"
3 .\" Copyright (c) 1991, 1992, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)termios.4 8.4 (Berkeley) 4/19/94
31 .\"
32 .Dd October 7, 2006
33 .Dt TERMIOS 4
34 .Os
35 .Sh NAME
36 .Nm termios
37 .Nd general terminal line discipline
38 .Sh SYNOPSIS
39 .In termios.h
40 .Sh DESCRIPTION
41 This describes a general terminal line discipline that is
42 supported on tty asynchronous communication ports.
43 .Ss Opening a Terminal Device File
44 When a terminal file is opened, it normally causes the process to wait
45 until a connection is established.
46 For most hardware, the presence
47 of a connection is indicated by the assertion of the hardware
48 .Em CARRIER DETECT
49 (CD) line.
50 If the
51 .Nm
52 structure associated with the terminal file has the
53 .Dv CLOCAL
54 flag set in the cflag, or if the
55 .Dv O_NONBLOCK
56 flag is set in the
57 .Xr open 2
58 call, then the open will succeed even without a connection being present.
59 .Pp
60 In practice, applications seldom open these files; they are opened
61 by special programs, such as
62 .Xr getty 8
63 or
64 .Xr rlogind 8 ,
65 and become an application's standard input, output, and error files.
66 .Ss Job Control in a Nutshell
67 Every process is associated with a particular process group and session.
68 The grouping is hierarchical: every member of a particular process group is a
69 member of the same session.
70 This structuring is used in managing groups
71 of related processes for purposes of
72 .\" .Gw "job control" ;
73 .Em "job control" ;
74 that is, the
75 ability from the keyboard (or from program control) to simultaneously
76 stop or restart
77 a complex command (a command composed of one or more related
78 processes).
79 .Pp
80 The grouping into process groups allows delivering
81 of signals that stop or start the group as a whole, along with
82 arbitrating which process group has access to the single controlling
83 terminal.
84 The grouping at a higher layer into sessions is to restrict
85 the job control related signals and system calls to within processes
86 resulting from a particular instance of a "login".
87 .Pp
88 Typically, a session is created when a user logs in, and the login
89 terminal is set up to be the controlling terminal; all processes
90 spawned from that login shell are in the same session, and inherit
91 the controlling terminal.
92 A job control shell operating interactively (that is, reading
93 commands from a terminal) normally groups related processes together
94 by placing them into the same process group.
95 A set of processes in the same process group
96 is collectively referred to as a "job".
97 .Pp
98 When the foreground process group of the terminal is the same as
99 the process group of a particular job, that job is said to be in the
100 .Em foreground .
101 When the process group of the terminal is different than the process
102 group of a job (but is still the controlling terminal), that job
103 is said to be in the
104 .Em background .
105 .Pp
106 Normally the shell reads a command and starts the job that implements
107 that command.
108 If the command is to be started in the foreground (typical), it
109 sets the process group of the terminal to the process group
110 of the started job, waits for the job to complete, and then
111 sets the process group of the terminal back to its own process
112 group (it puts itself into the foreground).
113 .Pp
114 If the job is to be started in the background (as denoted by the
115 shell operator "\*[Am]"), it never changes the process group of the
116 terminal and doesn't wait for the job to complete (that is, it
117 immediately attempts to read the next command).
118 .Pp
119 If the job is started in the foreground, the user may
120 type a character (usually
121 .Ql \&^Z )
122 which generates the terminal stop signal
123 .Pq Dv SIGTSTP
124 and has the affect of stopping the entire job.
125 The shell will notice that the job stopped (see
126 .Xr wait 2 ) ,
127 and will resume running after placing itself in the foreground.
128 .Pp
129 The shell also has commands for placing stopped jobs in the background,
130 and for placing stopped or background jobs into the foreground.
131 .Ss Orphaned Process Groups
132 An orphaned process group is a process group that has no process
133 whose parent is in a different process group, yet is in the same
134 session.
135 Conceptually it means a process group that doesn't have
136 a parent that could do anything if it were to be stopped.
137 For example,
138 the initial login shell is typically in an orphaned process group.
139 Orphaned process groups are immune to keyboard generated stop
140 signals and job control signals resulting from reads or writes to the
141 controlling terminal.
142 .Ss The Controlling Terminal
143 A terminal may belong to a process as its controlling terminal.
144 Each
145 process of a session that has a controlling terminal has the same
146 controlling terminal.
147 A terminal may be the controlling terminal for at
148 most one session.
149 The controlling terminal for a session is allocated by
150 the session leader by issuing the
151 .Dv TIOCSCTTY
152 ioctl.
153 A controlling terminal
154 is never acquired by merely opening a terminal device file.
155 When a controlling terminal becomes
156 associated with a session, its foreground process group is set to
157 the process group of the session leader.
158 .Pp
159 The controlling terminal is inherited by a child process during a
160 .Xr fork 2
161 function call.
162 A process relinquishes its controlling terminal when it
163 creates a new session with the
164 .Xr setsid 2
165 function; other processes
166 remaining in the old session that had this terminal as their controlling
167 terminal continue to have it.
168 A process does not relinquish its
169 controlling terminal simply by closing all of its file descriptors
170 associated with the controlling terminal if other processes continue to
171 have it open.
172 .Pp
173 When a controlling process terminates, the controlling terminal is
174 disassociated from the current session, allowing it to be acquired by a
175 new session leader.
176 Subsequent access to the terminal by other processes
177 in the earlier session will be denied, with attempts to access the
178 terminal treated as if modem disconnect had been sensed.
179 .Ss Terminal Access Control
180 If a process is in the foreground process group of its controlling
181 terminal, read operations are allowed.
182 Any attempts by a process
183 in a background process group to read from its controlling terminal
184 causes a
185 .Dv SIGTTIN
186 signal to be sent to
187 the process's group
188 unless one of the
189 following special cases apply: If the reading process is ignoring or
190 blocking the
191 .Dv SIGTTIN
192 signal, or if the process group of the reading process is orphaned,
193 the
194 .Xr read 2
195 returns -1 with
196 .Va errno set to
197 .Er EIO
198 and no signal is sent.
199 The default action of the
200 .Dv SIGTTIN
201 signal is to stop the
202 process to which it is sent.
203 .Pp
204 If a process is in the foreground process group of its controlling
205 terminal, write operations are allowed.
206 Attempts by a process in a background process group to write to its
207 controlling terminal will cause the process group to be sent a
208 .Dv SIGTTOU
209 signal unless one of the following special cases apply: If
210 .Dv TOSTOP
211 is not
212 set, or if
213 .Dv TOSTOP
214 is set and the process is ignoring or blocking the
215 .Dv SIGTTOU
216 signal, the process is allowed to write to the terminal and the
217 .Dv SIGTTOU
218 signal is not sent.
219 If
220 .Dv TOSTOP
221 is set, and the process group of
222 the writing process is orphaned, and the writing process is not ignoring
223 or blocking
224 .Dv SIGTTOU ,
225 the
226 .Xr write 2
227 returns -1 with
228 errno set to
229 .Er EIO
230 and no signal is sent.
231 .Pp
232 Certain calls that set terminal parameters are treated in the same
233 fashion as write, except that
234 .Dv TOSTOP
235 is ignored; that is, the effect is
236 identical to that of terminal writes when
237 .Dv TOSTOP
238 is set.
239 .Ss Input Processing and Reading Data
240 A terminal device associated with a terminal device file may operate in
241 full-duplex mode, so that data may arrive even while output is occurring.
242 Each terminal device file has associated with it an input queue, into
243 which incoming data is stored by the system before being read by a
244 process.
245 The system imposes a limit,
246 .Pf \&{ Dv MAX_INPUT Ns \&} ,
247 on the number of
248 bytes that may be stored in the input queue.
249 The behavior of the system
250 when this limit is exceeded depends on the setting of the
251 .Dv IMAXBEL
252 flag in the
253 .Nm
254 .Fa c_iflag .
255 If this flag is set, the terminal
256 is sent an
257 .Tn ASCII
258 .Dv BEL
259 character each time a character is received
260 while the input queue is full.
261 Otherwise, the input queue is flushed
262 upon receiving the character.
263 .Pp
264 Two general kinds of input processing are available, determined by
265 whether the terminal device file is in canonical mode or noncanonical mode.
266 Additionally,
267 input characters are processed according to the
268 .Fa c_iflag
269 and
270 .Fa c_lflag
271 fields.
272 Such processing can include echoing, which
273 in general means transmitting input characters immediately back to the
274 terminal when they are received from the terminal.
275 This is useful for terminals that can operate in full-duplex mode.
276 .Pp
277 The manner in which data is provided to a process reading from a terminal
278 device file is dependent on whether the terminal device file is in
279 canonical or noncanonical mode.
280 .Pp
281 Another dependency is whether the
282 .Dv O_NONBLOCK
283 flag is set by
284 .Xr open 2
285 or
286 .Xr fcntl 2 .
287 If the
288 .Dv O_NONBLOCK
289 flag is clear, then the read request is
290 blocked until data is available or a signal has been received.
291 If the
292 .Dv O_NONBLOCK
293 flag is set, then the read request is completed, without
294 blocking, in one of three ways:
295 .Bl -enum -offset indent
296 .It
297 If there is enough data available to satisfy the entire request,
298 and the read completes successfully the number of
299 bytes read is returned.
300 .It
301 If there is not enough data available to satisfy the entire
302 request, and the read completes successfully, having read as
303 much data as possible, the number of bytes read is returned.
304 .It
305 If there is no data available, the read returns -1, with
306 errno set to
307 .Er EAGAIN .
308 .El
309 .Pp
310 When data is available depends on whether the input processing mode is
311 canonical or noncanonical.
312 .Ss Canonical Mode Input Processing
313 In canonical mode input processing, terminal input is processed in units
314 of lines.
315 A line is delimited by a newline
316 .Ql \&\en
317 character, an end-of-file
318 .Pq Dv EOF
319 character, or an end-of-line
320 .Pq Dv EOL
321 character.
322 See the
323 .Sx "Special Characters"
324 section for
325 more information on
326 .Dv EOF
327 and
328 .Dv EOL .
329 This means that a read request will
330 not return until an entire line has been typed, or a signal has been
331 received.
332 Also, no matter how many bytes are requested in the read call,
333 at most one line is returned.
334 It is not, however, necessary to
335 read a whole line at once; any number of bytes, even one, may be
336 requested in a read without losing information.
337 .Pp
338 .Pf \&{ Dv MAX_CANON Ns \&}
339 is a limit on the
340 number of bytes in a line.
341 The behavior of the system when this limit is
342 exceeded is the same as when the input queue limit
343 .Pf \&{ Dv MAX_INPUT Ns \&} ,
344 is exceeded.
345 .Pp
346 Erase and kill processing occur when either of two special characters,
347 the
348 .Dv ERASE
349 and
350 .Dv KILL
351 characters (see the
352 .Sx "Special Characters section" ) ,
353 is received.
354 This processing affects data in the input queue that has not yet been
355 delimited by a newline
356 .Dv NL ,
357 .Dv EOF ,
358 or
359 .Dv EOL
360 character.
361 This un-delimited data makes up the current line.
362 The
363 .Dv ERASE
364 character deletes the last
365 character in the current line, if there is any.
366 The
367 .Dv KILL
368 character deletes all data in the current line, if there is any.
369 The
370 .Dv ERASE
371 and
372 .Dv KILL
373 characters have no effect if there is no data in the current line.
374 The
375 .Dv ERASE
376 and
377 .Dv KILL
378 characters themselves are not placed in the input
379 queue.
380 .Ss Noncanonical Mode Input Processing
381 In noncanonical mode input processing, input bytes are not assembled into
382 lines, and erase and kill processing does not occur.
383 The values of the
384 .Dv VMIN
385 and
386 .Dv VTIME
387 members of the
388 .Fa c_cc
389 array are used to determine how to
390 process the bytes received.
391 .Pp
392 .Dv VMIN
393 represents the minimum number of bytes that should be received when the
394 .Xr read 2
395 system call successfully returns.
396 .Dv VTIME
397 is a timer of 0.1 second
398 granularity that is used to time out bursty and short term data
399 transmissions.
400 If
401 .Dv VMIN
402 is greater than
403 .Dv \&{ Dv MAX_INPUT Ns \&} ,
404 the response to the
405 request is undefined.
406 The four possible values for
407 .Dv VMIN
408 and
409 .Dv VTIME
410 and
411 their interactions are described below.
412 .Ss "Case A: VMIN \*[Gt] 0, VTIME \*[Gt] 0"
413 In this case
414 .Dv VTIME
415 serves as an inter-byte timer and is activated after
416 the first byte is received.
417 Since it is an inter-byte timer, it is reset
418 after a byte is received.
419 The interaction between
420 .Dv VMIN
421 and
422 .Dv VTIME
423 is as
424 follows: as soon as one byte is received, the inter-byte timer is
425 started.
426 If
427 .Dv VMIN
428 bytes are received before the inter-byte timer expires
429 (remember that the timer is reset upon receipt of each byte), the read is
430 satisfied.
431 If the timer expires before
432 .Dv VMIN
433 bytes are received, the
434 characters received to that point are returned to the user.
435 Note that if
436 .Dv VTIME
437 expires at least one byte is returned because the timer would
438 not have been enabled unless a byte was received.
439 In this case
440 .Pf \&( Dv VMIN
441 \*[Gt] 0,
442 .Dv VTIME
443 \*[Gt] 0) the read blocks until the
444 .Dv VMIN
445 and
446 .Dv VTIME
447 mechanisms are
448 activated by the receipt of the first byte, or a signal is received.
449 If data is in the buffer at the time of the
450 .Xr read 2 ,
451 the result is as if data had been received immediately after the
452 .Xr read 2 .
453 .Ss "Case B: VMIN \*[Gt] 0, VTIME = 0"
454 In this case, since the value of
455 .Dv VTIME
456 is zero, the timer plays no role
457 and only
458 .Dv VMIN
459 is significant.
460 A pending read is not satisfied until
461 .Dv VMIN
462 bytes are received (i.e., the pending read blocks until
463 .Dv VMIN
464 bytes
465 are received), or a signal is received.
466 A program that uses this case to
467 read record-based terminal
468 .Dv I/O
469 may block indefinitely in the read
470 operation.
471 .Ss "Case C: VMIN = 0, VTIME \*[Gt] 0"
472 In this case, since
473 .Dv VMIN
474 = 0,
475 .Dv VTIME
476 no longer represents an inter-byte timer.
477 It now serves as a read timer that is activated as soon as the
478 read function is processed.
479 A read is satisfied as soon as a single byte is received or the
480 read timer expires.
481 Note that in this case if the timer expires, no bytes are returned.
482 If the timer does not
483 expire, the only way the read can be satisfied is if a byte is received.
484 In this case the read will not block indefinitely waiting for a
485 byte; if no byte is received within
486 .Dv VTIME Ns *0.1
487 seconds after the read is initiated, the read returns a value of
488 zero, having read no data.
489 If data is in the buffer at the time of the read, the timer is
490 started as if data had been received immediately after the read.
491 .Ss Case D: VMIN = 0, VTIME = 0
492 The minimum of either the number of bytes requested or the number of
493 bytes currently available is returned without waiting for more
494 bytes to be input.
495 If no characters are available, read returns a
496 value of zero, having read no data.
497 .Ss Writing Data and Output Processing
498 When a process writes one or more bytes to a terminal device file, they
499 are processed according to the
500 .Fa c_oflag
501 field (see the
502 .Sx "Output Modes"
503 section).
504 The implementation may provide a buffering mechanism; as such, when
505 a call to
506 .Xr write 2
507 completes, all of the bytes written have been scheduled for
508 transmission to the device, but the transmission will not necessarily
509 have been completed.
510 .\" See also .Sx "6.4.2" for the effects of
511 .\" .Dv O_NONBLOCK
512 .\" on write.
513 .Ss Special Characters
514 Certain characters have special functions on input or output or both.
515 These functions are summarized as follows:
516 .Bl -tag -width indent
517 .It Dv INTR
518 Special character on input and is recognized if the
519 .Dv ISIG
520 flag (see the
521 .Sx "Local Modes"
522 section) is enabled.
523 Generates a
524 .Dv SIGINT
525 signal which is sent to all processes in the foreground
526 process group for which the terminal is the controlling
527 terminal.
528 If
529 .Dv ISIG
530 is set, the
531 .Dv INTR
532 character is
533 discarded when processed.
534 .It Dv QUIT
535 Special character on input and is recognized if the
536 .Dv ISIG
537 flag is enabled.
538 Generates a
539 .Dv SIGQUIT
540 signal which is
541 sent to all processes in the foreground process group
542 for which the terminal is the controlling terminal.
543 If
544 .Dv ISIG
545 is set, the
546 .Dv QUIT
547 character is discarded when
548 processed.
549 .It Dv ERASE
550 Special character on input and is recognized if the
551 .Dv ICANON
552 flag is set.
553 Erases the last character in the
554 current line; see
555 .Sx "Canonical Mode Input Processing" .
556 It does not erase beyond
557 the start of a line, as delimited by an
558 .Dv NL ,
559 .Dv EOF ,
560 or
561 .Dv EOL
562 character.
563 If
564 .Dv ICANON
565 is set, the
566 .Dv ERASE
567 character is
568 discarded when processed.
569 .It Dv KILL
570 Special character on input and is recognized if the
571 .Dv ICANON
572 flag is set.
573 Deletes the entire line, as
574 delimited by a
575 .Dv NL ,
576 .Dv EOF ,
577 or
578 .Dv EOL
579 character.
580 If
581 .Dv ICANON
582 is set, the
583 .Dv KILL
584 character is discarded when processed.
585 .It Dv EOF
586 Special character on input and is recognized if the
587 .Dv ICANON
588 flag is set.
589 When received, all the bytes
590 waiting to be read are immediately passed to the
591 process, without waiting for a newline, and the
592 .Dv EOF
593 is discarded.
594 Thus, if there are no bytes waiting (that
595 is, the
596 .Dv EOF
597 occurred at the beginning of a line), a byte
598 count of zero is returned from the
599 .Xr read 2 ,
600 representing an end-of-file indication.
601 If
602 .Dv ICANON
603 is
604 set, the
605 .Dv EOF
606 character is discarded when processed.
607 .It Dv NL
608 Special character on input and is recognized if the
609 .Dv ICANON
610 flag is set.
611 It is the line delimiter
612 .Ql \&\en .
613 .It Dv EOL
614 Special character on input and is recognized if the
615 .Dv ICANON
616 flag is set.
617 Is an additional line delimiter,
618 like
619 .Dv NL .
620 .It Dv SUSP
621 If the
622 .Dv ISIG
623 flag is enabled, receipt of the
624 .Dv SUSP
625 character causes a
626 .Dv SIGTSTP
627 signal to be sent to all processes in the
628 foreground process group for which the terminal is the
629 controlling terminal, and the
630 .Dv SUSP
631 character is
632 discarded when processed.
633 .It Dv STOP
634 Special character on both input and output and is
635 recognized if the
636 .Dv IXON
637 (output control) or
638 .Dv IXOFF
639 (input control) flag is set.
640 Can be used to temporarily suspend output.
641 It is useful with fast terminals to
642 prevent output from disappearing before it can be read.
643 If
644 .Dv IXON
645 is set, the
646 .Dv STOP
647 character is discarded when
648 processed.
649 .It Dv START
650 Special character on both input and output and is
651 recognized if the
652 .Dv IXON
653 (output control) or
654 .Dv IXOFF
655 (input
656 control) flag is set.
657 Can be used to resume output that
658 has been suspended by a
659 .Dv STOP
660 character.
661 If
662 .Dv IXON
663 is set, the
664 .Dv START
665 character is discarded when processed.
666 .It Dv CR
667 Special character on input and is recognized if the
668 .Dv ICANON
669 flag is set; it is the
670 .Ql \&\er ,
671 as denoted in the
672 .Tn \&C
673 Standard {2}.
674 When
675 .Dv ICANON
676 and
677 .Dv ICRNL
678 are set and
679 .Dv IGNCR
680 is not set, this character is translated into a
681 .Dv NL ,
682 and
683 has the same effect as a
684 .Dv NL
685 character.
686 .El
687 .Pp
688 The following special characters are extensions defined by this
689 system and are not a part of
690 .St -p1003.1
691 .Nm .
692 .Bl -tag -width indent
693 .It Dv EOL2
694 Secondary
695 .Dv EOL
696 character.
697 Same function as
698 .Dv EOL .
699 .It Dv WERASE
700 Special character on input and is recognized if the
701 .Dv ICANON
702 flag is set.
703 Erases the last word in the current
704 line according to one of two algorithms.
705 If the
706 .Dv ALTWERASE
707 flag is not set, first any preceding whitespace is
708 erased, and then the maximal sequence of non-whitespace
709 characters.
710 If
711 .Dv ALTWERASE
712 is set, first any preceding whitespace is erased, and then the
713 maximal sequence of alphabetic/underscores or non alphabetic/underscores.
714 As a special case in this second algorithm, the first previous
715 non-whitespace character is skipped in determining whether the
716 preceding word is a sequence of alphabetic/underscores.
717 This sounds confusing but turns out to be quite practical.
718 .It Dv REPRINT
719 Special character on input and is recognized if the
720 .Dv ICANON
721 flag is set.
722 Causes the current input edit line
723 to be retyped.
724 .It Dv DSUSP
725 Has similar actions to the
726 .Dv SUSP
727 character, except that
728 the
729 .Dv SIGTSTP
730 signal is delivered when one of the processes
731 in the foreground process group issues a
732 .Xr read 2
733 to the controlling terminal.
734 .It Dv LNEXT
735 Special character on input and is recognized if the
736 .Dv IEXTEN
737 flag is set.
738 Receipt of this character causes the next
739 character to be taken literally.
740 .It Dv DISCARD
741 Special character on input and is recognized if the
742 .Dv IEXTEN
743 flag is set.
744 Receipt of this character toggles the flushing
745 of terminal output.
746 .It Dv STATUS
747 Special character on input and is recognized if the
748 .Dv ICANON
749 flag is set.
750 Receipt of this character causes a
751 .Dv SIGINFO
752 signal to be sent to the foreground process group of the
753 terminal.
754 Also, if the
755 .Dv NOKERNINFO
756 flag is not set, it
757 causes the kernel to write a status message to the terminal
758 that displays the current load average, the name of the
759 command in the foreground, its process ID, the symbolic
760 wait channel, the number of user and system seconds used,
761 the percentage of CPU the process is getting, and the resident
762 set size of the process.
763 .El
764 .Pp
765 The
766 .Dv NL
767 and
768 .Dv CR
769 characters cannot be changed.
770 The values for all the remaining characters can be set and are
771 described later in the document under
772 Special Control Characters.
773 .Pp
774 Special
775 character functions associated with changeable special control characters
776 can be disabled individually by setting their value to
777 .Dv {_POSIX_VDISABLE};
778 see
779 .Sx "Special Control Characters" .
780 .Pp
781 If two or more special characters have the same value, the function
782 performed when that character is received is undefined.
783 .Ss Modem Disconnect
784 If a modem disconnect is detected by the terminal interface for a
785 controlling terminal, and if
786 .Dv CLOCAL
787 is not set in the
788 .Fa c_cflag
789 field for
790 the terminal, the
791 .Dv SIGHUP
792 signal is sent to the controlling
793 process associated with the terminal.
794 Unless other arrangements have
795 been made, this causes the controlling process to terminate.
796 Any subsequent call to the
797 .Xr read 2
798 function returns the value zero, indicating end of file.
799 Thus, processes that read a terminal file and test for end-of-file
800 can terminate appropriately after a disconnect.
801 .\" If the
802 .\" .Er EIO
803 .\" condition specified in 6.1.1.4 that applies
804 .\" when the implementation supports job control also exists, it is
805 .\" unspecified whether the
806 .\" .Dv EOF
807 .\" condition or the
808 .\" .Pf [ Dv EIO
809 .\" ] is returned.
810 Any subsequent
811 .Xr write 2
812 to the terminal device returns -1, with
813 .Va errno
814 set to
815 .Er EIO ,
816 until the device is closed.
817 .Sh GENERAL TERMINAL INTERFACE
818 .Ss Closing a Terminal Device File
819 The last process to close a terminal device file causes any output
820 to be sent to the device and any input to be discarded.
821 Then, if
822 .Dv HUPCL
823 is set in the control modes, and the communications port supports a
824 disconnect function, the terminal device performs a disconnect.
825 .Ss Parameters That Can Be Set
826 Routines that need to control certain terminal
827 .Tn I/O
828 characteristics
829 do so by using the
830 .Nm
831 structure as defined in the header
832 .Aq Pa termios.h .
833 This structure contains minimally four scalar elements of bit flags
834 and one array of special characters.
835 The scalar flag elements are named:
836 .Fa c_iflag ,
837 .Fa c_oflag ,
838 .Fa c_cflag ,
839 and
840 .Fa c_lflag .
841 The character array is named
842 .Fa c_cc ,
843 and its maximum index is
844 .Dv NCCS .
845 .Ss Input Modes
846 Values of the
847 .Fa c_iflag
848 field describe the basic
849 terminal input control, and are composed of
850 following masks:
851 .Pp
852 .Bl -tag -width IMAXBEL -offset indent -compact
853 .It Dv IGNBRK
854 /* ignore BREAK condition */
855 .It Dv BRKINT
856 /* map BREAK to SIGINT */
857 .It Dv IGNPAR
858 /* ignore (discard) parity errors */
859 .It Dv PARMRK
860 /* mark parity and framing errors */
861 .It Dv INPCK
862 /* enable checking of parity errors */
863 .It Dv ISTRIP
864 /* strip 8th bit off chars */
865 .It Dv INLCR
866 /* map NL into CR */
867 .It Dv IGNCR
868 /* ignore CR */
869 .It Dv ICRNL
870 /* map CR to NL (ala CRMOD) */
871 .It Dv IXON
872 /* enable output flow control */
873 .It Dv IXOFF
874 /* enable input flow control */
875 .It Dv IXANY
876 /* any char will restart after stop */
877 .It Dv IMAXBEL
878 /* ring bell on input queue full */
879 .El
880 .Pp
881 In the context of asynchronous serial data transmission, a break
882 condition is defined as a sequence of zero-valued bits that continues for
883 more than the time to send one byte.
884 The entire sequence of zero-valued
885 bits is interpreted as a single break condition, even if it continues for
886 a time equivalent to more than one byte.
887 In contexts other than
888 asynchronous serial data transmission the definition of a break condition
889 is implementation defined.
890 .Pp
891 If
892 .Dv IGNBRK
893 is set, a break condition detected on input is ignored, that
894 is, not put on the input queue and therefore not read by any process.
895 If
896 .Dv IGNBRK
897 is not set and
898 .Dv BRKINT
899 is set, the break condition flushes the
900 input and output queues and if the terminal is the controlling terminal
901 of a foreground process group, the break condition generates a
902 single
903 .Dv SIGINT
904 signal to that foreground process group.
905 If neither
906 .Dv IGNBRK
907 nor
908 .Dv BRKINT
909 is set, a break condition is read as a single
910 .Ql \&\e0 ,
911 or if
912 .Dv PARMRK
913 is set, as
914 .Ql \&\e377 ,
915 .Ql \&\e0 ,
916 .Ql \&\e0 .
917 .Pp
918 If
919 .Dv IGNPAR
920 is set, a byte with a framing or parity error (other than
921 break) is ignored.
922 .Pp
923 If
924 .Dv PARMRK
925 is set, and
926 .Dv IGNPAR
927 is not set, a byte with a framing or parity
928 error (other than break) is given to the application as the
929 three-character sequence
930 .Ql \&\e377 ,
931 .Ql \&\e0 ,
932 X, where
933 .Ql \&\e377 ,
934 .Ql \&\e0
935 is a two-character
936 flag preceding each sequence and X is the data of the character received
937 in error.
938 To avoid ambiguity in this case, if
939 .Dv ISTRIP
940 is not set, a valid
941 character of
942 .Ql \&\e377
943 is given to the application as
944 .Ql \&\e377 ,
945 .Ql \&\e377 .
946 If
947 neither
948 .Dv PARMRK
949 nor
950 .Dv IGNPAR
951 is set, a framing or parity error (other than
952 break) is given to the application as a single character
953 .Ql \&\e0 .
954 .Pp
955 If
956 .Dv INPCK
957 is set, input parity checking is enabled.
958 If
959 .Dv INPCK
960 is not set, input parity checking is disabled, allowing output
961 parity generation without input parity errors.
962 Note that whether input parity checking is
963 enabled or disabled is independent of whether parity detection is enabled
964 or disabled (see
965 .Sx "Control Modes" ) .
966 If parity detection is enabled but input
967 parity checking is disabled, the hardware to which the terminal is
968 connected recognizes the parity bit, but the terminal special file
969 does not check whether this bit is set correctly or not.
970 .Pp
971 If
972 .Dv ISTRIP
973 is set, valid input bytes are first stripped to seven bits,
974 otherwise all eight bits are processed.
975 .Pp
976 If
977 .Dv INLCR
978 is set, a received
979 .Dv NL
980 character is translated into a
981 .Dv CR
982 character.
983 If
984 .Dv IGNCR
985 is set, a received
986 .Dv CR
987 character is ignored (not
988 read).
989 If
990 .Dv IGNCR
991 is not set and
992 .Dv ICRNL
993 is set, a received
994 .Dv CR
995 character is
996 translated into a
997 .Dv NL
998 character.
999 .Pp
1000 If
1001 .Dv IXON
1002 is set, start/stop output control is enabled.
1003 A received
1004 .Dv STOP
1005 character suspends output and a received
1006 .Dv START
1007 character
1008 restarts output.
1009 If
1010 .Dv IXANY
1011 is also set, then any character may restart output.
1012 When
1013 .Dv IXON
1014 is set,
1015 .Dv START
1016 and
1017 .Dv STOP
1018 characters are not
1019 read, but merely perform flow control functions.
1020 When
1021 .Dv IXON
1022 is not set,
1023 the
1024 .Dv START
1025 and
1026 .Dv STOP
1027 characters are read.
1028 .Pp
1029 If
1030 .Dv IXOFF
1031 is set, start/stop input control is enabled.
1032 The system shall transmit one or more
1033 .Dv STOP
1034 characters, which are intended to cause the
1035 terminal device to stop transmitting data, as needed to prevent the input
1036 queue from overflowing and causing the undefined behavior described in
1037 .Sx "Input Processing and Reading Data" ,
1038 and shall transmit one or more
1039 .Dv START
1040 characters, which are
1041 intended to cause the terminal device to resume transmitting data, as
1042 soon as the device can continue transmitting data without risk of
1043 overflowing the input queue.
1044 The precise conditions under which
1045 .Dv STOP
1046 and
1047 START
1048 characters are transmitted are implementation defined.
1049 .Pp
1050 If
1051 .Dv IMAXBEL
1052 is set and the input queue is full, subsequent input shall cause an
1053 .Tn ASCII
1054 .Dv BEL
1055 character to be transmitted to the output queue.
1056 .Pp
1057 The initial input control value after
1058 .Xr open 2
1059 is implementation defined.
1060 .Ss Output Modes
1061 Values of the
1062 .Fa c_oflag
1063 field describe the basic terminal output control,
1064 and are composed of the following masks:
1065 .Pp
1066 .Bl -tag -width OXTABS -offset indent -compact
1067 .It Dv OPOST
1068 /* enable following output processing */
1069 .It Dv ONLCR
1070 /* map NL to CR-NL (ala
1071 .Dv CRMOD )
1072 */
1073 .It Dv OCRNL
1074 /* map CR to NL */
1075 .It Dv OXTABS
1076 /* expand tabs to spaces */
1077 .It Dv ONOEOT
1078 /* discard
1079 .Dv EOT Ns 's
1080 .Pq ^D
1081 on output */
1082 .It Dv ONOCR
1083 /* do not transmit CRs on column 0 */
1084 .It Dv ONLRET
1085 /* on the terminal NL performs the CR function */
1086 .El
1087 .Pp
1088 If
1089 .Dv OPOST
1090 is set, the remaining flag masks are interpreted as follows;
1091 otherwise characters are transmitted without change.
1092 .Pp
1093 If
1094 .Dv ONLCR
1095 is set, newlines are translated to carriage return, linefeeds.
1096 .Pp
1097 If
1098 .Dv OCRNL
1099 is set, carriage returns are translated to newlines.
1100 .Pp
1101 If
1102 .Dv OXTABS
1103 is set, tabs are expanded to the appropriate number of
1104 spaces (assuming 8 column tab stops).
1105 .Pp
1106 If
1107 .Dv ONOEOT
1108 is set,
1109 .Tn ASCII
1110 .Dv EOT Ns 's
1111 are discarded on output.
1112 .Pp
1113 If
1114 .Dv ONOCR
1115 is set, no CR character is transmitted when at column 0 (first position).
1116 .Pp
1117 If
1118 .Dv ONLRET
1119 is set, the NL character is assumed to do the carriage-return function;
1120 the column pointer will be set to 0.
1121 .Ss Control Modes
1122 Values of the
1123 .Fa c_cflag
1124 field describe the basic
1125 terminal hardware control, and are composed of the
1126 following masks.
1127 Not all values
1128 specified are supported by all hardware.
1129 .Pp
1130 .Bl -tag -width CRTSXIFLOW -offset indent -compact
1131 .It Dv CSIZE
1132 /* character size mask */
1133 .It Dv CS5
1134 /* 5 bits (pseudo) */
1135 .It Dv CS6
1136 /* 6 bits */
1137 .It Dv CS7
1138 /* 7 bits */
1139 .It Dv CS8
1140 /* 8 bits */
1141 .It Dv CSTOPB
1142 /* send 2 stop bits */
1143 .It Dv CREAD
1144 /* enable receiver */
1145 .It Dv PARENB
1146 /* parity enable */
1147 .It Dv PARODD
1148 /* odd parity, else even */
1149 .It Dv HUPCL
1150 /* hang up on last close */
1151 .It Dv CLOCAL
1152 /* ignore modem status lines */
1153 .It Dv CCTS_OFLOW
1154 /*
1155 .Dv CTS
1156 flow control of output */
1157 .It Dv CRTSCTS
1158 /* logically the same as
1159 .Dv CCTS_OFLOW \&|
1160 .Dv CCTS_IFLOW
1161 */
1162 .It Dv CRTS_IFLOW
1163 /* RTS flow control of input */
1164 .It Dv MDMBUF
1165 /* flow control output via Carrier */
1166 .El
1167 .Pp
1168 The
1169 .Dv CSIZE
1170 bits specify the byte size in bits for both transmission and
1171 reception.
1172 The
1173 .Fa c_cflag
1174 is masked with
1175 .Dv CSIZE
1176 and compared with the
1177 values
1178 .Dv CS5 ,
1179 .Dv CS6 ,
1180 .Dv CS7 ,
1181 or
1182 .Dv CS8 .
1183 This size does not include the parity bit, if any.
1184 If
1185 .Dv CSTOPB
1186 is set, two stop bits are used, otherwise one stop bit.
1187 For example, at 110 baud, two stop bits are normally used.
1188 .Pp
1189 If
1190 .Dv CREAD
1191 is set, the receiver is enabled.
1192 Otherwise, no character is received.
1193 Not all hardware supports this bit.
1194 In fact, this flag is pretty silly and if it were not part of the
1195 .Nm
1196 specification it would be omitted.
1197 .Pp
1198 If
1199 .Dv PARENB
1200 is set, parity generation and detection are enabled and a parity
1201 bit is added to each character.
1202 If parity is enabled,
1203 .Dv PARODD
1204 specifies odd parity if set, otherwise even parity is used.
1205 .Pp
1206 If
1207 .Dv HUPCL
1208 is set, the modem control lines for the port are lowered when the
1209 last process with the port open closes the port or the process terminates.
1210 The modem connection is broken.
1211 .Pp
1212 If
1213 .Dv CLOCAL
1214 is set, a connection does not depend on the state of the modem
1215 status lines.
1216 If
1217 .Dv CLOCAL
1218 is clear, the modem status lines are monitored.
1219 .Pp
1220 Under normal circumstances, a call to the
1221 .Xr open 2
1222 function waits for the modem connection to complete.
1223 However, if the
1224 .Dv O_NONBLOCK
1225 flag is set
1226 or if
1227 .Dv CLOCAL
1228 has been set, the
1229 .Xr open 2
1230 function returns immediately without waiting for the connection.
1231 .Pp
1232 If the
1233 .Xr tty 4
1234 .Dv TIOCFLAG_CLOCAL
1235 flag has been set on the port then the
1236 .Dv CLOCAL
1237 flag will automatically be set on every open.
1238 .Pp
1239 The
1240 .Dv CCTS_OFLOW
1241 and
1242 .Dv CRTS_IFLOW
1243 flags are currently unused.
1244 Only
1245 .Dv CRTSCTS ,
1246 which has the combined effect, is implemented.
1247 Note that
1248 .Dv CRTSCTS
1249 support is hardware and driver dependent.
1250 Check the specific port driver manual page to see if hardware flow
1251 control is supported on the port you are using.
1252 .Pp
1253 If the
1254 .Xr tty 4
1255 .Dv TIOCFLAG_CRTSCTS
1256 flag has been set on the port then the
1257 .Dv CRTSCTS
1258 flag will automatically be set on every open.
1259 .Pp
1260 If
1261 .Dv MDMBUF
1262 is set then output flow control is controlled by the state
1263 of Carrier Detect.
1264 .Pp
1265 If the
1266 .Xr tty 4
1267 .Dv TIOCFLAG_MDMBUF
1268 flag has been set on the port then the
1269 .Dv MDMBUF
1270 flag will automatically be set on every open.
1271 .Pp
1272 If the object for which the control modes are set is not an asynchronous
1273 serial connection, some of the modes may be ignored; for example, if an
1274 attempt is made to set the baud rate on a network connection to a
1275 terminal on another host, the baud rate may or may not be set on the
1276 connection between that terminal and the machine it is directly connected
1277 to.
1278 .Ss Local Modes
1279 Values of the
1280 .Fa c_lflag
1281 field describe the control of
1282 various functions, and are composed of the following
1283 masks.
1284 .Pp
1285 .Bl -tag -width NOKERNINFO -offset indent -compact
1286 .It Dv ECHOKE
1287 /* visual erase for line kill */
1288 .It Dv ECHOE
1289 /* visually erase chars */
1290 .It Dv ECHO
1291 /* enable echoing */
1292 .It Dv ECHONL
1293 /* echo
1294 .Dv NL
1295 even if
1296 .Dv ECHO
1297 is off */
1298 .It Dv ECHOPRT
1299 /* visual erase mode for hardcopy */
1300 .It Dv ECHOCTL
1301 /* echo control chars as ^(Char) */
1302 .It Dv ISIG
1303 /* enable signals
1304 .Dv INTR ,
1305 .Dv QUIT ,
1306 .Dv [D]SUSP
1307 */
1308 .It Dv ICANON
1309 /* canonicalize input lines */
1310 .It Dv ALTWERASE
1311 /* use alternative
1312 .Dv WERASE
1313 algorithm */
1314 .It Dv IEXTEN
1315 /* enable
1316 .Dv DISCARD
1317 and
1318 .Dv LNEXT
1319 */
1320 .It Dv EXTPROC
1321 /* external processing */
1322 .It Dv TOSTOP
1323 /* stop background jobs from output */
1324 .It Dv FLUSHO
1325 /* output being flushed (state) */
1326 .It Dv NOKERNINFO
1327 /* no kernel output from
1328 .Dv VSTATUS
1329 */
1330 .It Dv PENDIN
1331 /* re-echo input buffer at next read */
1332 .It Dv NOFLSH
1333 /* don't flush output on signal */
1334 .El
1335 .Pp
1336 If
1337 .Dv ECHO
1338 is set, input characters are echoed back to the terminal.
1339 If
1340 .Dv ECHO
1341 is not set, input characters are not echoed.
1342 .Pp
1343 If
1344 .Dv ECHOE
1345 and
1346 .Dv ICANON
1347 are set, the
1348 .Dv ERASE
1349 character causes the terminal to erase the last character in the
1350 current line from the display, if possible.
1351 If there is no character to erase, an implementation may echo
1352 an indication that this was the case or do nothing.
1353 .Pp
1354 If
1355 .Dv ECHOK
1356 and
1357 .Dv ICANON
1358 are set, the
1359 .Dv KILL
1360 character causes
1361 the current line to be discarded and the system echoes the
1362 .Ql \&\en
1363 character after the
1364 .Dv KILL
1365 character.
1366 .Pp
1367 If
1368 .Dv ECHOKE
1369 and
1370 .Dv ICANON
1371 are set, the
1372 .Dv KILL
1373 character causes
1374 the current line to be discarded and the system causes
1375 the terminal
1376 to erase the line from the display.
1377 .Pp
1378 If
1379 .Dv ECHOPRT
1380 and
1381 .Dv ICANON
1382 are set, the system assumes
1383 that the display is a printing device and prints a
1384 backslash and the erased characters when processing
1385 .Dv ERASE
1386 characters, followed by a forward slash.
1387 .Pp
1388 If
1389 .Dv ECHOCTL
1390 is set, the system echoes control characters
1391 in a visible fashion using a caret followed by the control character.
1392 .Pp
1393 If
1394 .Dv ALTWERASE
1395 is set, the system uses an alternative algorithm
1396 for determining what constitutes a word when processing
1397 .Dv WERASE
1398 characters (see
1399 .Dv WERASE ) .
1400 .Pp
1401 If
1402 .Dv ECHONL
1403 and
1404 .Dv ICANON
1405 are set, the
1406 .Ql \&\en
1407 character echoes even if
1408 .Dv ECHO
1409 is not set.
1410 .Pp
1411 If
1412 .Dv ICANON
1413 is set, canonical processing is enabled.
1414 This enables the
1415 erase and kill edit functions, and the assembly of input characters into
1416 lines delimited by
1417 .Dv NL ,
1418 .Dv EOF ,
1419 and
1420 .Dv EOL ,
1421 as described in
1422 .Sx "Canonical Mode Input Processing" .
1423 .Pp
1424 If
1425 .Dv ICANON
1426 is not set, read requests are satisfied directly from the input
1427 queue.
1428 A read is not satisfied until at least
1429 .Dv VMIN
1430 bytes have been
1431 received or the timeout value
1432 .Dv VTIME
1433 expired between bytes.
1434 The time value represents tenths of seconds.
1435 See
1436 .Sx "Noncanonical Mode Input Processing"
1437 for more details.
1438 .Pp
1439 If
1440 .Dv ISIG
1441 is set, each input character is checked against the special
1442 control characters
1443 .Dv INTR ,
1444 .Dv QUIT ,
1445 and
1446 .Dv SUSP
1447 (job control only).
1448 If an input character matches one of these control characters, the
1449 function associated with that character is performed.
1450 If
1451 .Dv ISIG
1452 is not set, no checking is done.
1453 Thus these special input functions are possible only if
1454 .Dv ISIG
1455 is set.
1456 .Pp
1457 If
1458 .Dv IEXTEN
1459 is set, implementation-defined functions are recognized
1460 from the input data.
1461 How
1462 .Dv IEXTEN
1463 being set interacts with
1464 .Dv ICANON ,
1465 .Dv ISIG ,
1466 .Dv IXON ,
1467 or
1468 .Dv IXOFF
1469 is implementation defined.
1470 If
1471 .Dv IEXTEN
1472 is not set, then
1473 implementation-defined functions are not recognized, and the
1474 corresponding input characters are not processed as described for
1475 .Dv ICANON ,
1476 .Dv ISIG ,
1477 .Dv IXON ,
1478 and
1479 .Dv IXOFF .
1480 .Pp
1481 If
1482 .Dv NOFLSH
1483 is set, the normal flush of the input and output queues
1484 associated with the
1485 .Dv INTR ,
1486 .Dv QUIT ,
1487 and
1488 .Dv SUSP
1489 characters
1490 are not be done.
1491 .Pp
1492 If
1493 .Dv TOSTOP
1494 is set, the signal
1495 .Dv SIGTTOU
1496 is sent to the process group of a process that tries to write to
1497 its controlling terminal if it is not in the foreground process group for
1498 that terminal.
1499 This signal, by default, stops the members of the process group.
1500 Otherwise, the output generated by that process is output to the
1501 current output stream.
1502 Processes that are blocking or ignoring
1503 .Dv SIGTTOU
1504 signals are excepted and allowed to produce output and the
1505 .Dv SIGTTOU
1506 signal
1507 is not sent.
1508 .Pp
1509 If
1510 .Dv NOKERNINFO
1511 is set, the kernel does not produce a status message
1512 when processing
1513 .Dv STATUS
1514 characters (see
1515 .Dv STATUS ) .
1516 .Ss Special Control Characters
1517 The special control characters values are defined by the array
1518 .Fa c_cc .
1519 This table lists the array index, the corresponding special character,
1520 and the system default value.
1521 For an accurate list of
1522 the system defaults, consult the header file
1523 .Aq Pa ttydefaults.h .
1524 .Pp
1525 .Bl -column "Index Name" "Special Character" -offset indent -compact
1526 .It Em "Index Name Special Character Default Value"
1527 .It Dv VEOF Ta EOF Ta \&^D
1528 .It Dv VEOL Ta EOL Ta _POSIX_VDISABLE
1529 .It Dv VEOL2 Ta EOL2 Ta _POSIX_VDISABLE
1530 .It Dv VERASE Ta ERASE Ta \&^? Ql \&\e177
1531 .It Dv VWERASE Ta WERASE Ta \&^W
1532 .It Dv VKILL Ta KILL Ta \&^U
1533 .It Dv VREPRINT Ta REPRINT Ta \&^R
1534 .It Dv VINTR Ta INTR Ta \&^C
1535 .It Dv VQUIT Ta QUIT Ta \&^\e\e Ql \&\e34
1536 .It Dv VSUSP Ta SUSP Ta \&^Z
1537 .It Dv VDSUSP Ta DSUSP Ta \&^Y
1538 .It Dv VSTART Ta START Ta \&^Q
1539 .It Dv VSTOP Ta STOP Ta \&^S
1540 .It Dv VLNEXT Ta LNEXT Ta \&^V
1541 .It Dv VDISCARD Ta DISCARD Ta \&^O
1542 .It Dv VMIN Ta --- Ta \&1
1543 .It Dv VTIME Ta --- Ta \&0
1544 .It Dv VSTATUS Ta STATUS Ta \&^T
1545 .El
1546 .Pp
1547 If the
1548 value of one of the changeable special control characters (see
1549 .Sx "Special Characters" )
1550 is
1551 .Dv {_POSIX_VDISABLE} ,
1552 that function is disabled; that is, no input
1553 data is recognized as the disabled special character.
1554 If
1555 .Dv ICANON
1556 is
1557 not set, the value of
1558 .Dv {_POSIX_VDISABLE}
1559 has no special meaning for the
1560 .Dv VMIN
1561 and
1562 .Dv VTIME
1563 entries of the
1564 .Fa c_cc
1565 array.
1566 .Pp
1567 The initial values of the flags and control characters
1568 after
1569 .Xr open 2
1570 is set according to the values in the header
1571 .Aq Pa sys/ttydefaults.h .
1572 .Sh SEE ALSO
1573 .Xr tcsendbreak 3 ,
1574 .Xr tcsetattr 3