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