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