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