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