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