diff options
Diffstat (limited to 'share/man/man4/termios.4')
| -rw-r--r-- | share/man/man4/termios.4 | 1583 |
1 files changed, 1583 insertions, 0 deletions
diff --git a/share/man/man4/termios.4 b/share/man/man4/termios.4 new file mode 100644 index 0000000..6f38cf3 --- /dev/null +++ b/share/man/man4/termios.4 @@ -0,0 +1,1583 @@ +.\" Copyright (c) 1991, 1992, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)termios.4 8.4 (Berkeley) 4/19/94 +.\" $FreeBSD$ +.\" +.Dd December 26, 2009 +.Dt TERMIOS 4 +.Os +.Sh NAME +.Nm termios +.Nd general terminal line discipline +.Sh SYNOPSIS +.In termios.h +.Sh DESCRIPTION +This describes a general terminal line discipline that is +supported on tty asynchronous communication ports. +.Ss Opening a Terminal Device File +When a terminal file is opened, it normally causes the process to wait +until a connection is established. +For most hardware, the presence +of a connection is indicated by the assertion of the hardware +.Dv CARRIER +line. +If the termios structure associated with the terminal file has the +.Dv CLOCAL +flag set in the cflag, or if the +.Dv O_NONBLOCK +flag is set +in the +.Xr open 2 +call, then the open will succeed even without +a connection being present. +In practice, applications +seldom open these files; they are opened by special programs, such +as +.Xr getty 8 +or +.Xr rlogind 8 , +and become +an application's standard input, output, and error files. +.Ss Job Control in a Nutshell +Every process is associated with a particular process group and session. +The grouping is hierarchical: every member of a particular process group is a +member of the same session. +This structuring is used in managing groups +of related processes for purposes of +.\" .Gw "job control" ; +.Em "job control" ; +that is, the +ability from the keyboard (or from program control) to simultaneously +stop or restart +a complex command (a command composed of one or more related +processes). +The grouping into process groups allows delivering +of signals that stop or start the group as a whole, along with +arbitrating which process group has access to the single controlling +terminal. +The grouping at a higher layer into sessions is to restrict +the job control related signals and system calls to within processes +resulting from a particular instance of a +.Dq login . +Typically, a session +is created when a user logs in, and the login terminal is setup +to be the controlling terminal; all processes spawned from that +login shell are in the same session, and inherit the controlling +terminal. +.Pp +A job control shell +operating interactively (that is, reading commands from a terminal) +normally groups related processes together by placing them into the +same process group. +A set of processes in the same process group +is collectively referred to as a +.Dq job . +When the foreground process +group of the terminal is the same as the process group of a particular +job, that job is said to be in the +.Dq foreground . +When the process group of the terminal is different from the process group of +a job (but is still the controlling terminal), that job is said +to be in the +.Dq background . +Normally the +shell reads a command and starts the job that implements that +command. +If the command is to be started in the foreground (typical), it +sets the process group of the terminal to the process group +of the started job, waits for the job to complete, and then +sets the process group of the terminal back to its own process +group (it puts itself into the foreground). +If the job is to +be started in the background (as denoted by the shell operator "&"), +it never changes the process group of the terminal and does not +wait for the job to complete (that is, it immediately attempts to read the next +command). +If the job is started in the foreground, the user may +type a key (usually +.Ql \&^Z ) +which generates the terminal stop signal +.Pq Dv SIGTSTP +and has the effect of stopping the entire job. +The shell will notice that the job stopped, and will resume running after +placing itself in the foreground. +The shell also has commands for placing stopped jobs in the background, +and for placing stopped or background jobs into the foreground. +.Ss Orphaned Process Groups +An orphaned process group is a process group that has no process +whose parent is in a different process group, yet is in the same +session. +Conceptually it means a process group that does not have +a parent that could do anything if it were to be stopped. +For example, +the initial login shell is typically in an orphaned process group. +Orphaned process groups are immune to keyboard generated stop +signals and job control signals resulting from reads or writes to the +controlling terminal. +.Ss The Controlling Terminal +A terminal may belong to a process as its controlling terminal. +Each +process of a session that has a controlling terminal has the same +controlling terminal. +A terminal may be the controlling terminal for at +most one session. +The controlling terminal for a session is allocated by +the session leader by issuing the +.Dv TIOCSCTTY +ioctl. +A controlling terminal +is never acquired by merely opening a terminal device file. +When a controlling terminal becomes +associated with a session, its foreground process group is set to +the process group of the session leader. +.Pp +The controlling terminal is inherited by a child process during a +.Xr fork 2 +function call. +A process relinquishes its controlling terminal when it +creates a new session with the +.Xr setsid 2 +function; other processes +remaining in the old session that had this terminal as their controlling +terminal continue to have it. +A process does not relinquish its +controlling terminal simply by closing all of its file descriptors +associated with the controlling terminal if other processes continue to +have it open. +.Pp +When a controlling process terminates, the controlling terminal is +disassociated from the current session, allowing it to be acquired by a +new session leader. +Subsequent access to the terminal by other processes +in the earlier session will be denied, with attempts to access the +terminal treated as if modem disconnect had been sensed. +.Ss Terminal Access Control +If a process is in the foreground process group of its controlling +terminal, read operations are allowed. +Any attempts by a process +in a background process group to read from its controlling terminal +causes a +.Dv SIGTTIN +signal to be sent to +the process's group +unless one of the +following special cases apply: if the reading process is ignoring or +blocking the +.Dv SIGTTIN +signal, or if the process group of the reading +process is orphaned, the +.Xr read 2 +returns -1 with +.Va errno +set to +.Er EIO +and no +signal is sent. +The default action of the +.Dv SIGTTIN +signal is to stop the +process to which it is sent. +.Pp +If a process is in the foreground process group of its controlling +terminal, write operations are allowed. +Attempts by a process in a background process group to write to its +controlling terminal will cause the process group to be sent a +.Dv SIGTTOU +signal unless one of the following special cases apply: if +.Dv TOSTOP +is not +set, or if +.Dv TOSTOP +is set and the process is ignoring or blocking the +.Dv SIGTTOU +signal, the process is allowed to write to the terminal and the +.Dv SIGTTOU +signal is not sent. +If +.Dv TOSTOP +is set, and the process group of +the writing process is orphaned, and the writing process is not ignoring +or blocking +.Dv SIGTTOU , +the +.Xr write 2 +returns -1 with +errno set to +.Er EIO +and no signal is sent. +.Pp +Certain calls that set terminal parameters are treated in the same +fashion as write, except that +.Dv TOSTOP +is ignored; that is, the effect is +identical to that of terminal writes when +.Dv TOSTOP +is set. +.Ss Input Processing and Reading Data +A terminal device associated with a terminal device file may operate in +full-duplex mode, so that data may arrive even while output is occurring. +Each terminal device file has associated with it an input queue, into +which incoming data is stored by the system before being read by a +process. +The system imposes a limit, +.Pf \&{ Dv MAX_INPUT Ns \&} , +on the number of +bytes that may be stored in the input queue. +The behavior of the system +when this limit is exceeded depends on the setting of the +.Dv IMAXBEL +flag in the termios +.Fa c_iflag . +If this flag is set, the terminal +is sent an +.Tn ASCII +.Dv BEL +character each time a character is received +while the input queue is full. +Otherwise, the input queue is flushed upon receiving the character. +.Pp +Two general kinds of input processing are available, determined by +whether the terminal device file is in canonical mode or noncanonical +mode. +Additionally, +input characters are processed according to the +.Fa c_iflag +and +.Fa c_lflag +fields. +Such processing can include echoing, which +in general means transmitting input characters immediately back to the +terminal when they are received from the terminal. +This is useful for terminals that can operate in full-duplex mode. +.Pp +The manner in which data is provided to a process reading from a terminal +device file is dependent on whether the terminal device file is in +canonical or noncanonical mode. +.Pp +Another dependency is whether the +.Dv O_NONBLOCK +flag is set by +.Xr open 2 +or +.Xr fcntl 2 . +If the +.Dv O_NONBLOCK +flag is clear, then the read request is +blocked until data is available or a signal has been received. +If the +.Dv O_NONBLOCK +flag is set, then the read request is completed, without +blocking, in one of three ways: +.Bl -enum -offset indent +.It +If there is enough data available to satisfy the entire request, +and the read completes successfully the number of +bytes read is returned. +.It +If there is not enough data available to satisfy the entire +request, and the read completes successfully, having read as +much data as possible, the number of bytes read is returned. +.It +If there is no data available, the read returns -1, with +errno set to +.Er EAGAIN . +.El +.Pp +When data is available depends on whether the input processing mode is +canonical or noncanonical. +.Ss Canonical Mode Input Processing +In canonical mode input processing, terminal input is processed in units +of lines. +A line is delimited by a newline +.Ql \&\en +character, an end-of-file +.Pq Dv EOF +character, or an end-of-line +.Pq Dv EOL +character. +See the +.Sx "Special Characters" +section for +more information on +.Dv EOF +and +.Dv EOL . +This means that a read request will +not return until an entire line has been typed, or a signal has been +received. +Also, no matter how many bytes are requested in the read call, +at most one line is returned. +It is not, however, necessary to +read a whole line at once; any number of bytes, even one, may be +requested in a read without losing information. +.Pp +.Pf \&{ Dv MAX_CANON Ns \&} +is a limit on the +number of bytes in a line. +The behavior of the system when this limit is +exceeded is the same as when the input queue limit +.Pf \&{ Dv MAX_INPUT Ns \&} , +is exceeded. +.Pp +Erase and kill processing occur when either of two special characters, +the +.Dv ERASE +and +.Dv KILL +characters (see the +.Sx "Special Characters" +section), is received. +This processing affects data in the input queue that has not yet been +delimited by a newline +.Dv NL , +.Dv EOF , +or +.Dv EOL +character. +This un-delimited +data makes up the current line. +The +.Dv ERASE +character deletes the last +character in the current line, if there is any. +The +.Dv KILL +character +deletes all data in the current line, if there is any. +The +.Dv ERASE +and +.Dv KILL +characters have no effect if there is no data in the current line. +The +.Dv ERASE +and +.Dv KILL +characters themselves are not placed in the input +queue. +.Ss Noncanonical Mode Input Processing +In noncanonical mode input processing, input bytes are not assembled into +lines, and erase and kill processing does not occur. +The values of the +.Dv VMIN +and +.Dv VTIME +members of the +.Fa c_cc +array are used to determine how to +process the bytes received. +.Pp +.Dv MIN +represents the minimum number of bytes that should be received when +the +.Xr read 2 +function successfully returns. +.Dv TIME +is a timer of 0.1 second +granularity that is used to time out bursty and short term data +transmissions. +If +.Dv MIN +is greater than +.Dv \&{ Dv MAX_INPUT Ns \&} , +the response to the +request is undefined. +The four possible values for +.Dv MIN +and +.Dv TIME +and +their interactions are described below. +.Ss "Case A: MIN > 0, TIME > 0" +In this case +.Dv TIME +serves as an inter-byte timer and is activated after +the first byte is received. +Since it is an inter-byte timer, it is reset +after a byte is received. +The interaction between +.Dv MIN +and +.Dv TIME +is as +follows: as soon as one byte is received, the inter-byte timer is +started. +If +.Dv MIN +bytes are received before the inter-byte timer expires +(remember that the timer is reset upon receipt of each byte), the read is +satisfied. +If the timer expires before +.Dv MIN +bytes are received, the +characters received to that point are returned to the user. +Note that if +.Dv TIME +expires at least one byte is returned because the timer would +not have been enabled unless a byte was received. +In this case +.Pf \&( Dv MIN +> 0, +.Dv TIME +> 0) the read blocks until the +.Dv MIN +and +.Dv TIME +mechanisms are +activated by the receipt of the first byte, or a signal is received. +If data is in the buffer at the time of the +.Fn read , +the result is as +if data had been received immediately after the +.Fn read . +.Ss "Case B: MIN > 0, TIME = 0" +In this case, since the value of +.Dv TIME +is zero, the timer plays no role +and only +.Dv MIN +is significant. +A pending read is not satisfied until +.Dv MIN +bytes are received (i.e., the pending read blocks until +.Dv MIN +bytes +are received), or a signal is received. +A program that uses this case to read record-based terminal +.Dv I/O +may block indefinitely in the read +operation. +.Ss "Case C: MIN = 0, TIME > 0" +In this case, since +.Dv MIN += 0, +.Dv TIME +no longer represents an inter-byte +timer. +It now serves as a read timer that is activated as soon as the +read function is processed. +A read is satisfied as soon as a single +byte is received or the read timer expires. +Note that in this case if the timer expires, no bytes are returned. +If the timer does not +expire, the only way the read can be satisfied is if a byte is received. +In this case the read will not block indefinitely waiting for a byte; if +no byte is received within +.Dv TIME Ns *0.1 +seconds after the read is initiated, +the read returns a value of zero, having read no data. +If data is +in the buffer at the time of the read, the timer is started as if +data had been received immediately after the read. +.Ss Case D: MIN = 0, TIME = 0 +The minimum of either the number of bytes requested or the number of +bytes currently available is returned without waiting for more +bytes to be input. +If no characters are available, read returns a +value of zero, having read no data. +.Ss Writing Data and Output Processing +When a process writes one or more bytes to a terminal device file, they +are processed according to the +.Fa c_oflag +field (see the +.Sx "Output Modes" +section). +The +implementation may provide a buffering mechanism; as such, when a call to +.Fn write +completes, all of the bytes written have been scheduled for +transmission to the device, but the transmission will not necessarily +have been completed. +.\" See also .Sx "6.4.2" for the effects of +.\" .Dv O_NONBLOCK +.\" on write. +.Ss Special Characters +Certain characters have special functions on input or output or both. +These functions are summarized as follows: +.Bl -tag -width indent +.It Dv INTR +Special character on input and is recognized if the +.Dv ISIG +flag (see the +.Sx "Local Modes" +section) is enabled. +Generates a +.Dv SIGINT +signal which is sent to all processes in the foreground +process group for which the terminal is the controlling +terminal. +If +.Dv ISIG +is set, the +.Dv INTR +character is +discarded when processed. +.It Dv QUIT +Special character on input and is recognized if the +.Dv ISIG +flag is enabled. +Generates a +.Dv SIGQUIT +signal which is +sent to all processes in the foreground process group +for which the terminal is the controlling terminal. +If +.Dv ISIG +is set, the +.Dv QUIT +character is discarded when +processed. +.It Dv ERASE +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Erases the last character in the +current line; see +.Sx "Canonical Mode Input Processing" . +It does not erase beyond +the start of a line, as delimited by an +.Dv NL , +.Dv EOF , +or +.Dv EOL +character. +If +.Dv ICANON +is set, the +.Dv ERASE +character is +discarded when processed. +.It Dv KILL +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Deletes the entire line, as +delimited by a +.Dv NL , +.Dv EOF , +or +.Dv EOL +character. +If +.Dv ICANON +is set, the +.Dv KILL +character is discarded when processed. +.It Dv EOF +Special character on input and is recognized if the +.Dv ICANON +flag is set. +When received, all the bytes +waiting to be read are immediately passed to the +process, without waiting for a newline, and the +.Dv EOF +is discarded. +Thus, if there are no bytes waiting (that is, the +.Dv EOF +occurred at the beginning of a line), a byte +count of zero is returned from the +.Fn read , +representing an end-of-file indication. +If +.Dv ICANON +is +set, the +.Dv EOF +character is discarded when processed. +.It Dv NL +Special character on input and is recognized if the +.Dv ICANON +flag is set. +It is the line delimiter +.Ql \&\en . +.It Dv EOL +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Is an additional line delimiter, like +.Dv NL . +.It Dv SUSP +If the +.Dv ISIG +flag is enabled, receipt of the +.Dv SUSP +character causes a +.Dv SIGTSTP +signal to be sent to all processes in the +foreground process group for which the terminal is the +controlling terminal, and the +.Dv SUSP +character is +discarded when processed. +.It Dv STOP +Special character on both input and output and is +recognized if the +.Dv IXON +(output control) or +.Dv IXOFF +(input +control) flag is set. +Can be used to temporarily suspend output. +It is useful with fast terminals to +prevent output from disappearing before it can be read. +If +.Dv IXON +is set, the +.Dv STOP +character is discarded when +processed. +.It Dv START +Special character on both input and output and is +recognized if the +.Dv IXON +(output control) or +.Dv IXOFF +(input +control) flag is set. +Can be used to resume output that has been suspended by a +.Dv STOP +character. +If +.Dv IXON +is set, the +.Dv START +character is discarded when processed. +.It Dv CR +Special character on input and is recognized if the +.Dv ICANON +flag is set; it is the +.Ql \&\er , +as denoted in the +.Tn \&C +Standard {2}. +When +.Dv ICANON +and +.Dv ICRNL +are set and +.Dv IGNCR +is not set, this character is translated into a +.Dv NL , +and +has the same effect as a +.Dv NL +character. +.El +.Pp +The following special characters are extensions defined by this +system and are not a part of +.St -p1003.1 +termios. +.Bl -tag -width indent +.It Dv EOL2 +Secondary +.Dv EOL +character. +Same function as +.Dv EOL . +.It Dv WERASE +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Erases the last word in the current line according to one of two algorithms. +If the +.Dv ALTWERASE +flag is not set, first any preceding whitespace is +erased, and then the maximal sequence of non-whitespace +characters. +If +.Dv ALTWERASE +is set, first any preceding +whitespace is erased, and then the maximal sequence +of alphabetic/underscores or non alphabetic/underscores. +As a special case in this second algorithm, the first previous +non-whitespace character is skipped in determining +whether the preceding word is a sequence of +alphabetic/underscores. +This sounds confusing but turns out to be quite practical. +.It Dv REPRINT +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Causes the current input edit line to be retyped. +.It Dv DSUSP +Has similar actions to the +.Dv SUSP +character, except that +the +.Dv SIGTSTP +signal is delivered when one of the processes +in the foreground process group issues a +.Fn read +to the +controlling terminal. +.It Dv LNEXT +Special character on input and is recognized if the +.Dv IEXTEN +flag is set. +Receipt of this character causes the next character to be taken literally. +.It Dv DISCARD +Special character on input and is recognized if the +.Dv IEXTEN +flag is set. +Receipt of this character toggles the flushing of terminal output. +.It Dv STATUS +Special character on input and is recognized if the +.Dv ICANON +flag is set. +Receipt of this character causes a +.Dv SIGINFO +signal to be sent to the foreground process group of the +terminal. +Also, if the +.Dv NOKERNINFO +flag is not set, it +causes the kernel to write a status message to the terminal +that displays the current load average, the name of the +command in the foreground, its process ID, the symbolic +wait channel, the number of user and system seconds used, +the percentage of cpu the process is getting, and the resident +set size of the process. +.El +.Pp +The +.Dv NL +and +.Dv CR +characters cannot be changed. +The values for all the remaining characters can be set and are +described later in the document under +Special Control Characters. +.Pp +Special +character functions associated with changeable special control characters +can be disabled individually by setting their value to +.Dv {_POSIX_VDISABLE} ; +see +.Sx "Special Control Characters" . +.Pp +If two or more special characters have the same value, the function +performed when that character is received is undefined. +.Ss Modem Disconnect +If a modem disconnect is detected by the terminal interface for a +controlling terminal, and if +.Dv CLOCAL +is not set in the +.Fa c_cflag +field for +the terminal, the +.Dv SIGHUP +signal is sent to the controlling +process associated with the terminal. +Unless other arrangements have +been made, this causes the controlling process to terminate. +Any subsequent call to the +.Fn read +function returns the value zero, +indicating end of file. +Thus, processes that read a terminal +file and test for end-of-file can terminate appropriately after a +disconnect. +.\" If the +.\" .Er EIO +.\" condition specified in 6.1.1.4 that applies +.\" when the implementation supports job control also exists, it is +.\" unspecified whether the +.\" .Dv EOF +.\" condition or the +.\" .Pf [ Dv EIO +.\" ] is returned. +Any +subsequent +.Fn write +to the terminal device returns -1, with +.Va errno +set to +.Er EIO , +until the device is closed. +.Sh General Terminal Interface +.Ss Closing a Terminal Device File +The last process to close a terminal device file causes any output +to be sent to the device and any input to be discarded. +Then, if +.Dv HUPCL +is set in the control modes, and the communications port supports a +disconnect function, the terminal device performs a disconnect. +.Ss Parameters That Can Be Set +Routines that need to control certain terminal +.Tn I/O +characteristics +do so by using the termios structure as defined in the header +.In termios.h . +This structure contains minimally four scalar elements of bit flags +and one array of special characters. +The scalar flag elements are named: +.Fa c_iflag , +.Fa c_oflag , +.Fa c_cflag , +and +.Fa c_lflag . +The character array is named +.Fa c_cc , +and its maximum index is +.Dv NCCS . +.Ss Input Modes +Values of the +.Fa c_iflag +field describe the basic +terminal input control, and are composed of +following masks: +.Pp +.Bl -tag -width IMAXBEL -offset indent -compact +.It Dv IGNBRK +/* ignore BREAK condition */ +.It Dv BRKINT +/* map BREAK to SIGINTR */ +.It Dv IGNPAR +/* ignore (discard) parity errors */ +.It Dv PARMRK +/* mark parity and framing errors */ +.It Dv INPCK +/* enable checking of parity errors */ +.It Dv ISTRIP +/* strip 8th bit off chars */ +.It Dv INLCR +/* map NL into CR */ +.It Dv IGNCR +/* ignore CR */ +.It Dv ICRNL +/* map CR to NL (ala CRMOD) */ +.It Dv IXON +/* enable output flow control */ +.It Dv IXOFF +/* enable input flow control */ +.It Dv IXANY +/* any char will restart after stop */ +.It Dv IMAXBEL +/* ring bell on input queue full */ +.El +.Pp +In the context of asynchronous serial data transmission, a break +condition is defined as a sequence of zero-valued bits that continues for +more than the time to send one byte. +The entire sequence of zero-valued +bits is interpreted as a single break condition, even if it continues for +a time equivalent to more than one byte. +In contexts other than +asynchronous serial data transmission the definition of a break condition +is implementation defined. +.Pp +If +.Dv IGNBRK +is set, a break condition detected on input is ignored, that +is, not put on the input queue and therefore not read by any process. +If +.Dv IGNBRK +is not set and +.Dv BRKINT +is set, the break condition flushes the +input and output queues and if the terminal is the controlling terminal +of a foreground process group, the break condition generates a +single +.Dv SIGINT +signal to that foreground process group. +If neither +.Dv IGNBRK +nor +.Dv BRKINT +is set, a break condition is read as a single +.Ql \&\e0 , +or if +.Dv PARMRK +is set, as +.Ql \&\e377 , +.Ql \&\e0 , +.Ql \&\e0 . +.Pp +If +.Dv IGNPAR +is set, a byte with a framing or parity error (other than +break) is ignored. +.Pp +If +.Dv PARMRK +is set, and +.Dv IGNPAR +is not set, a byte with a framing or parity +error (other than break) is given to the application as the +three-character sequence +.Ql \&\e377 , +.Ql \&\e0 , +X, where +.Ql \&\e377 , +.Ql \&\e0 +is a two-character +flag preceding each sequence and X is the data of the character received +in error. +To avoid ambiguity in this case, if +.Dv ISTRIP +is not set, a valid +character of +.Ql \&\e377 +is given to the application as +.Ql \&\e377 , +.Ql \&\e377 . +If +neither +.Dv PARMRK +nor +.Dv IGNPAR +is set, a framing or parity error (other than +break) is given to the application as a single character +.Ql \&\e0 . +.Pp +If +.Dv INPCK +is set, input parity checking is enabled. +If +.Dv INPCK +is not set, +input parity checking is disabled, allowing output parity generation +without input parity errors. +Note that whether input parity checking is +enabled or disabled is independent of whether parity detection is enabled +or disabled (see +.Sx "Control Modes" ) . +If parity detection is enabled but input +parity checking is disabled, the hardware to which the terminal is +connected recognizes the parity bit, but the terminal special file +does not check whether this bit is set correctly or not. +.Pp +If +.Dv ISTRIP +is set, valid input bytes are first stripped to seven bits, +otherwise all eight bits are processed. +.Pp +If +.Dv INLCR +is set, a received +.Dv NL +character is translated into a +.Dv CR +character. +If +.Dv IGNCR +is set, a received +.Dv CR +character is ignored (not +read). +If +.Dv IGNCR +is not set and +.Dv ICRNL +is set, a received +.Dv CR +character is +translated into a +.Dv NL +character. +.Pp +If +.Dv IXON +is set, start/stop output control is enabled. +A received +.Dv STOP +character suspends output and a received +.Dv START +character +restarts output. +If +.Dv IXANY +is also set, then any character may +restart output. +When +.Dv IXON +is set, +.Dv START +and +.Dv STOP +characters are not +read, but merely perform flow control functions. +When +.Dv IXON +is not set, +the +.Dv START +and +.Dv STOP +characters are read. +.Pp +If +.Dv IXOFF +is set, start/stop input control is enabled. +The system shall transmit one or more +.Dv STOP +characters, which are intended to cause the +terminal device to stop transmitting data, as needed to prevent the input +queue from overflowing and causing the undefined behavior described in +.Sx "Input Processing and Reading Data" , +and shall transmit one or more +.Dv START +characters, which are +intended to cause the terminal device to resume transmitting data, as +soon as the device can continue transmitting data without risk of +overflowing the input queue. +The precise conditions under which +.Dv STOP +and +.Dv START +characters are transmitted are implementation defined. +.Pp +If +.Dv IMAXBEL +is set and the input queue is full, subsequent input shall cause an +.Tn ASCII +.Dv BEL +character to be transmitted to +the output queue. +.Pp +The initial input control value after +.Fn open +is implementation defined. +.Ss Output Modes +Values of the +.Fa c_oflag +field describe the basic terminal output control, +and are composed of the following masks: +.Pp +.Bl -tag -width ONOEOT -offset indent -compact +.It Dv OPOST +/* enable following output processing */ +.It Dv ONLCR +/* map NL to CR-NL (ala +.Dv CRMOD ) +*/ +.It Dv OCRNL +/* map CR to NL */ +.It Dv TABDLY +/* tab delay mask */ +.It Dv TAB0 +/* no tab delay and expansion */ +.It Dv TAB3 +/* expand tabs to spaces */ +.It Dv ONOEOT +/* discard +.Dv EOT Ns 's +.Ql \&^D +on output) */ +.It Dv ONOCR +/* do not transmit CRs on column 0 */ +.It Dv ONLRET +/* on the terminal NL performs the CR function */ +.El +.Pp +If +.Dv OPOST +is set, the remaining flag masks are interpreted as follows; +otherwise characters are transmitted without change. +.Pp +If +.Dv ONLCR +is set, newlines are translated to carriage return, linefeeds. +.Pp +If +.Dv OCRNL +is set, carriage returns are translated to newlines. +.Pp +The +.Dv TABDLY +bits specify the tab delay. +The +.Fa c_oflag +is masked with +.Dv TABDLY +and compared with the +values +.Dv TAB0 +or +.Dv TAB3 . +If +.Dv TAB3 +is set, tabs are expanded to the appropriate number of +spaces (assuming 8 column tab stops). +.Pp +If +.Dv ONOEOT +is set, +.Tn ASCII +.Dv EOT Ns 's +are discarded on output. +.Pp +If +.Dv ONOCR +is set, no CR character is transmitted when at column 0 (first position). +.Pp +If +.Dv ONLRET +is set, the NL character is assumed to do the carriage-return function; +the column pointer will be set to 0. +.Ss Control Modes +Values of the +.Fa c_cflag +field describe the basic +terminal hardware control, and are composed of the +following masks. +Not all values +specified are supported by all hardware. +.Pp +.Bl -tag -width CRTSXIFLOW -offset indent -compact +.It Dv CSIZE +/* character size mask */ +.It Dv CS5 +/* 5 bits (pseudo) */ +.It Dv CS6 +/* 6 bits */ +.It Dv CS7 +/* 7 bits */ +.It Dv CS8 +/* 8 bits */ +.It Dv CSTOPB +/* send 2 stop bits */ +.It Dv CREAD +/* enable receiver */ +.It Dv PARENB +/* parity enable */ +.It Dv PARODD +/* odd parity, else even */ +.It Dv HUPCL +/* hang up on last close */ +.It Dv CLOCAL +/* ignore modem status lines */ +.It Dv CCTS_OFLOW +/* +.Dv CTS +flow control of output */ +.It Dv CRTSCTS +/* same as +.Dv CCTS_OFLOW +*/ +.It Dv CRTS_IFLOW +/* RTS flow control of input */ +.It Dv MDMBUF +/* flow control output via Carrier */ +.El +.Pp +The +.Dv CSIZE +bits specify the byte size in bits for both transmission and +reception. +The +.Fa c_cflag +is masked with +.Dv CSIZE +and compared with the +values +.Dv CS5 , +.Dv CS6 , +.Dv CS7 , +or +.Dv CS8 . +This size does not include the parity bit, if any. +If +.Dv CSTOPB +is set, two stop bits are used, otherwise one stop bit. +For example, at 110 baud, two stop bits are normally used. +.Pp +If +.Dv CREAD +is set, the receiver is enabled. +Otherwise, no character is received. +Not all hardware supports this bit. +In fact, this flag is pretty silly and if it were not part of the +.Nm +specification +it would be omitted. +.Pp +If +.Dv PARENB +is set, parity generation and detection are enabled and a parity +bit is added to each character. +If parity is enabled, +.Dv PARODD +specifies +odd parity if set, otherwise even parity is used. +.Pp +If +.Dv HUPCL +is set, the modem control lines for the port are lowered +when the last process with the port open closes the port or the process +terminates. +The modem connection is broken. +.Pp +If +.Dv CLOCAL +is set, a connection does not depend on the state of the modem +status lines. +If +.Dv CLOCAL +is clear, the modem status lines are +monitored. +.Pp +Under normal circumstances, a call to the +.Fn open +function waits for +the modem connection to complete. +However, if the +.Dv O_NONBLOCK +flag is set +or if +.Dv CLOCAL +has been set, the +.Fn open +function returns +immediately without waiting for the connection. +.Pp +The +.Dv CCTS_OFLOW +.Pf ( Dv CRTSCTS ) +flag is currently unused. +.Pp +If +.Dv MDMBUF +is set then output flow control is controlled by the state +of Carrier Detect. +.Pp +If the object for which the control modes are set is not an asynchronous +serial connection, some of the modes may be ignored; for example, if an +attempt is made to set the baud rate on a network connection to a +terminal on another host, the baud rate may or may not be set on the +connection between that terminal and the machine it is directly connected +to. +.Ss Local Modes +Values of the +.Fa c_lflag +field describe the control of +various functions, and are composed of the following +masks. +.Pp +.Bl -tag -width NOKERNINFO -offset indent -compact +.It Dv ECHOKE +/* visual erase for line kill */ +.It Dv ECHOE +/* visually erase chars */ +.It Dv ECHO +/* enable echoing */ +.It Dv ECHONL +/* echo +.Dv NL +even if +.Dv ECHO +is off */ +.It Dv ECHOPRT +/* visual erase mode for hardcopy */ +.It Dv ECHOCTL +/* echo control chars as ^(Char) */ +.It Dv ISIG +/* enable signals +.Dv INTR , +.Dv QUIT , +.Dv [D]SUSP +*/ +.It Dv ICANON +/* canonicalize input lines */ +.It Dv ALTWERASE +/* use alternate +.Dv WERASE +algorithm */ +.It Dv IEXTEN +/* enable +.Dv DISCARD +and +.Dv LNEXT +*/ +.It Dv EXTPROC +/* external processing */ +.It Dv TOSTOP +/* stop background jobs from output */ +.It Dv FLUSHO +/* output being flushed (state) */ +.It Dv NOKERNINFO +/* no kernel output from +.Dv VSTATUS +*/ +.It Dv PENDIN +/* XXX retype pending input (state) */ +.It Dv NOFLSH +/* don't flush after interrupt */ +.El +.Pp +If +.Dv ECHO +is set, input characters are echoed back to the terminal. +If +.Dv ECHO +is not set, input characters are not echoed. +.Pp +If +.Dv ECHOE +and +.Dv ICANON +are set, the +.Dv ERASE +character causes the terminal +to erase the last character in the current line from the display, if +possible. +If there is no character to erase, an implementation may echo +an indication that this was the case or do nothing. +.Pp +If +.Dv ECHOK +and +.Dv ICANON +are set, the +.Dv KILL +character causes +the current line to be discarded and the system echoes the +.Ql \&\en +character after the +.Dv KILL +character. +.Pp +If +.Dv ECHOKE +and +.Dv ICANON +are set, the +.Dv KILL +character causes +the current line to be discarded and the system causes +the terminal +to erase the line from the display. +.Pp +If +.Dv ECHOPRT +and +.Dv ICANON +are set, the system assumes +that the display is a printing device and prints a +backslash and the erased characters when processing +.Dv ERASE +characters, followed by a forward slash. +.Pp +If +.Dv ECHOCTL +is set, the system echoes control characters +in a visible fashion using a caret followed by the control character. +.Pp +If +.Dv ALTWERASE +is set, the system uses an alternative algorithm +for determining what constitutes a word when processing +.Dv WERASE +characters (see +.Dv WERASE ) . +.Pp +If +.Dv ECHONL +and +.Dv ICANON +are set, the +.Ql \&\en +character echoes even if +.Dv ECHO +is not set. +.Pp +If +.Dv ICANON +is set, canonical processing is enabled. +This enables the +erase and kill edit functions, and the assembly of input characters into +lines delimited by +.Dv NL , +.Dv EOF , +and +.Dv EOL , +as described in +.Sx "Canonical Mode Input Processing" . +.Pp +If +.Dv ICANON +is not set, read requests are satisfied directly from the input +queue. +A read is not satisfied until at least +.Dv MIN +bytes have been +received or the timeout value +.Dv TIME +expired between bytes. +The time value +represents tenths of seconds. +See +.Sx "Noncanonical Mode Input Processing" +for more details. +.Pp +If +.Dv ISIG +is set, each input character is checked against the special +control characters +.Dv INTR , +.Dv QUIT , +and +.Dv SUSP +(job control only). +If an input +character matches one of these control characters, the function +associated with that character is performed. +If +.Dv ISIG +is not set, no +checking is done. +Thus these special input functions are possible only +if +.Dv ISIG +is set. +.Pp +If +.Dv IEXTEN +is set, implementation-defined functions are recognized +from the input data. +How +.Dv IEXTEN +being set +interacts with +.Dv ICANON , +.Dv ISIG , +.Dv IXON , +or +.Dv IXOFF +is implementation defined. +If +.Dv IEXTEN +is not set, then +implementation-defined functions are not recognized, and the +corresponding input characters are not processed as described for +.Dv ICANON , +.Dv ISIG , +.Dv IXON , +and +.Dv IXOFF . +.Pp +If +.Dv NOFLSH +is set, the normal flush of the input and output queues +associated with the +.Dv INTR , +.Dv QUIT , +and +.Dv SUSP +characters +are not be done. +.Pp +If +.Dv TOSTOP +is set, the signal +.Dv SIGTTOU +is sent to the process group of a process that tries to write to +its controlling terminal if it is not in the foreground process group for +that terminal. +This signal, by default, stops the members of the process group. +Otherwise, the output generated by that process is output to the +current output stream. +Processes that are blocking or ignoring +.Dv SIGTTOU +signals are excepted and allowed to produce output and the +.Dv SIGTTOU +signal +is not sent. +.Pp +If +.Dv NOKERNINFO +is set, the kernel does not produce a status message +when processing +.Dv STATUS +characters (see +.Dv STATUS ) . +.Ss Special Control Characters +The special control characters values are defined by the array +.Fa c_cc . +This table lists the array index, the corresponding special character, +and the system default value. +For an accurate list of +the system defaults, consult the header file +.In sys/ttydefaults.h . +.Pp +.Bl -column "Index Name" "Special Character" -offset indent -compact +.It Em "Index Name Special Character Default Value" +.It Dv VEOF Ta EOF Ta \&^D +.It Dv VEOL Ta EOL Ta _POSIX_VDISABLE +.It Dv VEOL2 Ta EOL2 Ta _POSIX_VDISABLE +.It Dv VERASE Ta ERASE Ta \&^? Ql \&\e177 +.It Dv VWERASE Ta WERASE Ta \&^W +.It Dv VKILL Ta KILL Ta \&^U +.It Dv VREPRINT Ta REPRINT Ta \&^R +.It Dv VINTR Ta INTR Ta \&^C +.It Dv VQUIT Ta QUIT Ta \&^\e\e Ql \&\e34 +.It Dv VSUSP Ta SUSP Ta \&^Z +.It Dv VDSUSP Ta DSUSP Ta \&^Y +.It Dv VSTART Ta START Ta \&^Q +.It Dv VSTOP Ta STOP Ta \&^S +.It Dv VLNEXT Ta LNEXT Ta \&^V +.It Dv VDISCARD Ta DISCARD Ta \&^O +.It Dv VMIN Ta --- Ta \&1 +.It Dv VTIME Ta --- Ta \&0 +.It Dv VSTATUS Ta STATUS Ta \&^T +.El +.Pp +If the +value of one of the changeable special control characters (see +.Sx "Special Characters" ) +is +.Dv {_POSIX_VDISABLE} , +that function is disabled; that is, no input +data is recognized as the disabled special character. +If +.Dv ICANON +is +not set, the value of +.Dv {_POSIX_VDISABLE} +has no special meaning for the +.Dv VMIN +and +.Dv VTIME +entries of the +.Fa c_cc +array. +.Pp +The initial values of the flags and control characters +after +.Fn open +is set according to +the values in the header +.In sys/ttydefaults.h . +.Sh SEE ALSO +.Xr stty 1 , +.Xr tcgetsid 3 , +.Xr tcsendbreak 3 , +.Xr tcsetattr 3 , +.Xr tcsetsid 3 , +.Xr tty 4 |
