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