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