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