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