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