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