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