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