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