/share/man/man4/termios.4

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