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