1.\" $NetBSD: termios.4,v 1.20 2002/02/13 08:17:48 ross 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 \*[Lt]termios.h\*[Gt] 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 "\*[Am]"), 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 \*[Gt] 0, VTIME \*[Gt] 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\*[Gt] 0, 445.Dv VTIME 446\*[Gt] 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 \*[Gt] 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 \*[Gt] 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.Ss Closing a Terminal Device File 822The last process to close a terminal device file causes any output 823to be sent to the device and any input to be discarded. 824Then, if 825.Dv HUPCL 826is set in the control modes, and the communications port supports a 827disconnect function, the terminal device performs a disconnect. 828.Ss Parameters That Can Be Set 829Routines that need to control certain terminal 830.Tn I/O 831characteristics 832do so by using the 833.Nm 834structure as defined in the header 835.Aq Pa termios.h . 836This structure contains minimally four scalar elements of bit flags 837and one array of special characters. 838The scalar flag elements are named: 839.Fa c_iflag , 840.Fa c_oflag , 841.Fa c_cflag , 842and 843.Fa c_lflag . 844The character array is named 845.Fa c_cc , 846and its maximum index is 847.Dv NCCS . 848.Ss Input Modes 849Values of the 850.Fa c_iflag 851field describe the basic 852terminal input control, and are composed of 853following masks: 854.Pp 855.Bl -tag -width IMAXBEL -offset indent -compact 856.It Dv IGNBRK 857/* ignore BREAK condition */ 858.It Dv BRKINT 859/* map BREAK to SIGINTR */ 860.It Dv IGNPAR 861/* ignore (discard) parity errors */ 862.It Dv PARMRK 863/* mark parity and framing errors */ 864.It Dv INPCK 865/* enable checking of parity errors */ 866.It Dv ISTRIP 867/* strip 8th bit off chars */ 868.It Dv INLCR 869/* map NL into CR */ 870.It Dv IGNCR 871/* ignore CR */ 872.It Dv ICRNL 873/* map CR to NL (ala CRMOD) */ 874.It Dv IXON 875/* enable output flow control */ 876.It Dv IXOFF 877/* enable input flow control */ 878.It Dv IXANY 879/* any char will restart after stop */ 880.It Dv IMAXBEL 881/* ring bell on input queue full */ 882.El 883.Pp 884In the context of asynchronous serial data transmission, a break 885condition is defined as a sequence of zero-valued bits that continues for 886more than the time to send one byte. 887The entire sequence of zero-valued 888bits is interpreted as a single break condition, even if it continues for 889a time equivalent to more than one byte. 890In contexts other than 891asynchronous serial data transmission the definition of a break condition 892is implementation defined. 893.Pp 894If 895.Dv IGNBRK 896is set, a break condition detected on input is ignored, that 897is, not put on the input queue and therefore not read by any process. 898If 899.Dv IGNBRK 900is not set and 901.Dv BRKINT 902is set, the break condition flushes the 903input and output queues and if the terminal is the controlling terminal 904of a foreground process group, the break condition generates a 905single 906.Dv SIGINT 907signal to that foreground process group. 908If neither 909.Dv IGNBRK 910nor 911.Dv BRKINT 912is set, a break condition is read as a single 913.Ql \&\e0 , 914or if 915.Dv PARMRK 916is set, as 917.Ql \&\e377 , 918.Ql \&\e0 , 919.Ql \&\e0 . 920.Pp 921If 922.Dv IGNPAR 923is set, a byte with a framing or parity error (other than 924break) is ignored. 925.Pp 926If 927.Dv PARMRK 928is set, and 929.Dv IGNPAR 930is not set, a byte with a framing or parity 931error (other than break) is given to the application as the 932three-character sequence 933.Ql \&\e377 , 934.Ql \&\e0 , 935X, where 936.Ql \&\e377 , 937.Ql \&\e0 938is a two-character 939flag preceding each sequence and X is the data of the character received 940in error. 941To avoid ambiguity in this case, if 942.Dv ISTRIP 943is not set, a valid 944character of 945.Ql \&\e377 946is given to the application as 947.Ql \&\e377 , 948.Ql \&\e377 . 949If 950neither 951.Dv PARMRK 952nor 953.Dv IGNPAR 954is set, a framing or parity error (other than 955break) is given to the application as a single character 956.Ql \&\e0 . 957.Pp 958If 959.Dv INPCK 960is set, input parity checking is enabled. 961If 962.Dv INPCK 963is not set, input parity checking is disabled, allowing output 964parity generation without input parity errors. 965Note that whether input parity checking is 966enabled or disabled is independent of whether parity detection is enabled 967or disabled (see 968.Sx "Control Modes" ) . 969If parity detection is enabled but input 970parity checking is disabled, the hardware to which the terminal is 971connected recognizes the parity bit, but the terminal special file 972does not check whether this bit is set correctly or not. 973.Pp 974If 975.Dv ISTRIP 976is set, valid input bytes are first stripped to seven bits, 977otherwise all eight bits are processed. 978.Pp 979If 980.Dv INLCR 981is set, a received 982.Dv NL 983character is translated into a 984.Dv CR 985character. 986If 987.Dv IGNCR 988is set, a received 989.Dv CR 990character is ignored (not 991read). 992If 993.Dv IGNCR 994is not set and 995.Dv ICRNL 996is set, a received 997.Dv CR 998character is 999translated into a 1000.Dv NL 1001character. 1002.Pp 1003If 1004.Dv IXON 1005is set, start/stop output control is enabled. 1006A received 1007.Dv STOP 1008character suspends output and a received 1009.Dv START 1010character 1011restarts output. 1012If 1013.Dv IXANY 1014is also set, then any character may restart output. 1015When 1016.Dv IXON 1017is set, 1018.Dv START 1019and 1020.Dv STOP 1021characters are not 1022read, but merely perform flow control functions. 1023When 1024.Dv IXON 1025is not set, 1026the 1027.Dv START 1028and 1029.Dv STOP 1030characters are read. 1031.Pp 1032If 1033.Dv IXOFF 1034is set, start/stop input control is enabled. 1035The system shall transmit one or more 1036.Dv STOP 1037characters, which are intended to cause the 1038terminal device to stop transmitting data, as needed to prevent the input 1039queue from overflowing and causing the undefined behavior described in 1040.Sx "Input Processing and Reading Data" , 1041and shall transmit one or more 1042.Dv START 1043characters, which are 1044intended to cause the terminal device to resume transmitting data, as 1045soon as the device can continue transmitting data without risk of 1046overflowing the input queue. 1047The precise conditions under which 1048.Dv STOP 1049and 1050START 1051characters are transmitted are implementation defined. 1052.Pp 1053If 1054.Dv IMAXBEL 1055is set and the input queue is full, subsequent input shall cause an 1056.Tn ASCII 1057.Dv BEL 1058character to be transmitted to the output queue. 1059.Pp 1060The initial input control value after 1061.Xr open 2 1062is implementation defined. 1063.Ss Output Modes 1064Values of the 1065.Fa c_oflag 1066field describe the basic terminal output control, 1067and are composed of the following masks: 1068.Pp 1069.Bl -tag -width OXTABS -offset indent -compact 1070.It Dv OPOST 1071/* enable following output processing */ 1072.It Dv ONLCR 1073/* map NL to CR-NL (ala 1074.Dv CRMOD ) 1075*/ 1076.It Dv OCRNL 1077/* map CR to NL */ 1078.It Dv OXTABS 1079/* expand tabs to spaces */ 1080.It Dv ONOEOT 1081/* discard 1082.Dv EOT Ns 's 1083.Ql \&^D 1084on output) */ 1085.It Dv ONOCR 1086/* do not transmit CRs on column 0 */ 1087.It Dv ONLRET 1088/* on the terminal NL performs the CR function */ 1089.El 1090.Pp 1091If 1092.Dv OPOST 1093is set, the remaining flag masks are interpreted as follows; 1094otherwise characters are transmitted without change. 1095.Pp 1096If 1097.Dv ONLCR 1098is set, newlines are translated to carriage return, linefeeds. 1099.Pp 1100If 1101.Dv OCRNL 1102is set, carriage returns are translated to newlines. 1103.Pp 1104If 1105.Dv OXTABS 1106is set, tabs are expanded to the appropriate number of 1107spaces (assuming 8 column tab stops). 1108.Pp 1109If 1110.Dv ONOEOT 1111is set, 1112.Tn ASCII 1113.Dv EOT Ns 's 1114are discarded on output. 1115.Pp 1116If 1117.Dv ONOCR 1118is set, no CR character is transmitted when at column 0 (first position). 1119.Pp 1120If 1121.Dv ONLRET 1122is set, the NL character is assumed to do the carriage-return function; 1123the column pointer will be set to 0. 1124.Ss Control Modes 1125Values of the 1126.Fa c_cflag 1127field describe the basic 1128terminal hardware control, and are composed of the 1129following masks. 1130Not all values 1131specified are supported by all hardware. 1132.Pp 1133.Bl -tag -width CRTSXIFLOW -offset indent -compact 1134.It Dv CSIZE 1135/* character size mask */ 1136.It Dv CS5 1137/* 5 bits (pseudo) */ 1138.It Dv CS6 1139/* 6 bits */ 1140.It Dv CS7 1141/* 7 bits */ 1142.It Dv CS8 1143/* 8 bits */ 1144.It Dv CSTOPB 1145/* send 2 stop bits */ 1146.It Dv CREAD 1147/* enable receiver */ 1148.It Dv PARENB 1149/* parity enable */ 1150.It Dv PARODD 1151/* odd parity, else even */ 1152.It Dv HUPCL 1153/* hang up on last close */ 1154.It Dv CLOCAL 1155/* ignore modem status lines */ 1156.It Dv CCTS_OFLOW 1157/* 1158.Dv CTS 1159flow control of output */ 1160.It Dv CRTSCTS 1161/* same as 1162.Dv CCTS_OFLOW 1163*/ 1164.It Dv CRTS_IFLOW 1165/* RTS flow control of input */ 1166.It Dv MDMBUF 1167/* flow control output via Carrier */ 1168.El 1169.Pp 1170The 1171.Dv CSIZE 1172bits specify the byte size in bits for both transmission and 1173reception. 1174The 1175.Fa c_cflag 1176is masked with 1177.Dv CSIZE 1178and compared with the 1179values 1180.Dv CS5 , 1181.Dv CS6 , 1182.Dv CS7 , 1183or 1184.Dv CS8 . 1185This size does not include the parity bit, if any. 1186If 1187.Dv CSTOPB 1188is set, two stop bits are used, otherwise one stop bit. 1189For example, at 110 baud, two stop bits are normally used. 1190.Pp 1191If 1192.Dv CREAD 1193is set, the receiver is enabled. 1194Otherwise, no character is received. 1195Not all hardware supports this bit. 1196In fact, this flag is pretty silly and if it were not part of the 1197.Nm 1198specification it would be omitted. 1199.Pp 1200If 1201.Dv PARENB 1202is set, parity generation and detection are enabled and a parity 1203bit is added to each character. 1204If parity is enabled, 1205.Dv PARODD 1206specifies odd parity if set, otherwise even parity is used. 1207.Pp 1208If 1209.Dv HUPCL 1210is set, the modem control lines for the port are lowered when the 1211last process with the port open closes the port or the process terminates. 1212The modem connection is broken. 1213.Pp 1214If 1215.Dv CLOCAL 1216is set, a connection does not depend on the state of the modem 1217status lines. 1218If 1219.Dv CLOCAL 1220is clear, the modem status lines are monitored. 1221.Pp 1222Under normal circumstances, a call to the 1223.Xr open 2 1224function waits for the modem connection to complete. 1225However, if the 1226.Dv O_NONBLOCK 1227flag is set 1228or if 1229.Dv CLOCAL 1230has been set, the 1231.Xr open 2 1232function returns immediately without waiting for the connection. 1233.Pp 1234The 1235.Dv CCTS_OFLOW 1236.Pf ( Dv CRTSCTS ) 1237flag is currently unused. 1238.Pp 1239If 1240.Dv MDMBUF 1241is set then output flow control is controlled by the state 1242of Carrier Detect. 1243.Pp 1244If the object for which the control modes are set is not an asynchronous 1245serial connection, some of the modes may be ignored; for example, if an 1246attempt is made to set the baud rate on a network connection to a 1247terminal on another host, the baud rate may or may not be set on the 1248connection between that terminal and the machine it is directly connected 1249to. 1250.Ss Local Modes 1251Values of the 1252.Fa c_lflag 1253field describe the control of 1254various functions, and are composed of the following 1255masks. 1256.Pp 1257.Bl -tag -width NOKERNINFO -offset indent -compact 1258.It Dv ECHOKE 1259/* visual erase for line kill */ 1260.It Dv ECHOE 1261/* visually erase chars */ 1262.It Dv ECHO 1263/* enable echoing */ 1264.It Dv ECHONL 1265/* echo 1266.Dv NL 1267even if 1268.Dv ECHO 1269is off */ 1270.It Dv ECHOPRT 1271/* visual erase mode for hardcopy */ 1272.It Dv ECHOCTL 1273/* echo control chars as ^(Char) */ 1274.It Dv ISIG 1275/* enable signals 1276.Dv INTR , 1277.Dv QUIT , 1278.Dv [D]SUSP 1279*/ 1280.It Dv ICANON 1281/* canonicalize input lines */ 1282.It Dv ALTWERASE 1283/* use alternative 1284.Dv WERASE 1285algorithm */ 1286.It Dv IEXTEN 1287/* enable 1288.Dv DISCARD 1289and 1290.Dv LNEXT 1291*/ 1292.It Dv EXTPROC 1293/* external processing */ 1294.It Dv TOSTOP 1295/* stop background jobs from output */ 1296.It Dv FLUSHO 1297/* output being flushed (state) */ 1298.It Dv NOKERNINFO 1299/* no kernel output from 1300.Dv VSTATUS 1301*/ 1302.It Dv PENDIN 1303/* re-echo input buffer at next read */ 1304.It Dv NOFLSH 1305/* don't flush output on signal */ 1306.El 1307.Pp 1308If 1309.Dv ECHO 1310is set, input characters are echoed back to the terminal. 1311If 1312.Dv ECHO 1313is not set, input characters are not echoed. 1314.Pp 1315If 1316.Dv ECHOE 1317and 1318.Dv ICANON 1319are set, the 1320.Dv ERASE 1321character causes the terminal to erase the last character in the 1322current line from the display, if possible. 1323If there is no character to erase, an implementation may echo 1324an indication that this was the case or do nothing. 1325.Pp 1326If 1327.Dv ECHOK 1328and 1329.Dv ICANON 1330are set, the 1331.Dv KILL 1332character causes 1333the current line to be discarded and the system echoes the 1334.Ql \&\en 1335character after the 1336.Dv KILL 1337character. 1338.Pp 1339If 1340.Dv ECHOKE 1341and 1342.Dv ICANON 1343are set, the 1344.Dv KILL 1345character causes 1346the current line to be discarded and the system causes 1347the terminal 1348to erase the line from the display. 1349.Pp 1350If 1351.Dv ECHOPRT 1352and 1353.Dv ICANON 1354are set, the system assumes 1355that the display is a printing device and prints a 1356backslash and the erased characters when processing 1357.Dv ERASE 1358characters, followed by a forward slash. 1359.Pp 1360If 1361.Dv ECHOCTL 1362is set, the system echoes control characters 1363in a visible fashion using a caret followed by the control character. 1364.Pp 1365If 1366.Dv ALTWERASE 1367is set, the system uses an alternative algorithm 1368for determining what constitutes a word when processing 1369.Dv WERASE 1370characters (see 1371.Dv WERASE ) . 1372.Pp 1373If 1374.Dv ECHONL 1375and 1376.Dv ICANON 1377are set, the 1378.Ql \&\en 1379character echoes even if 1380.Dv ECHO 1381is not set. 1382.Pp 1383If 1384.Dv ICANON 1385is set, canonical processing is enabled. 1386This enables the 1387erase and kill edit functions, and the assembly of input characters into 1388lines delimited by 1389.Dv NL , 1390.Dv EOF , 1391and 1392.Dv EOL , 1393as described in 1394.Sx "Canonical Mode Input Processing" . 1395.Pp 1396If 1397.Dv ICANON 1398is not set, read requests are satisfied directly from the input 1399queue. 1400A read is not satisfied until at least 1401.Dv VMIN 1402bytes have been 1403received or the timeout value 1404.Dv VTIME 1405expired between bytes. 1406The time value represents tenths of seconds. 1407See 1408.Sx "Noncanonical Mode Input Processing" 1409for more details. 1410.Pp 1411If 1412.Dv ISIG 1413is set, each input character is checked against the special 1414control characters 1415.Dv INTR , 1416.Dv QUIT , 1417and 1418.Dv SUSP 1419(job control only). 1420If an input character matches one of these control characters, the 1421function associated with that character is performed. 1422If 1423.Dv ISIG 1424is not set, no checking is done. 1425Thus these special input functions are possible only if 1426.Dv ISIG 1427is set. 1428.Pp 1429If 1430.Dv IEXTEN 1431is set, implementation-defined functions are recognized 1432from the input data. 1433How 1434.Dv IEXTEN 1435being set interacts with 1436.Dv ICANON , 1437.Dv ISIG , 1438.Dv IXON , 1439or 1440.Dv IXOFF 1441is implementation defined. 1442If 1443.Dv IEXTEN 1444is not set, then 1445implementation-defined functions are not recognized, and the 1446corresponding input characters are not processed as described for 1447.Dv ICANON , 1448.Dv ISIG , 1449.Dv IXON , 1450and 1451.Dv IXOFF . 1452.Pp 1453If 1454.Dv NOFLSH 1455is set, the normal flush of the input and output queues 1456associated with the 1457.Dv INTR , 1458.Dv QUIT , 1459and 1460.Dv SUSP 1461characters 1462are not be done. 1463.Pp 1464If 1465.Dv TOSTOP 1466is set, the signal 1467.Dv SIGTTOU 1468is sent to the process group of a process that tries to write to 1469its controlling terminal if it is not in the foreground process group for 1470that terminal. 1471This signal, by default, stops the members of the process group. 1472Otherwise, the output generated by that process is output to the 1473current output stream. 1474Processes that are blocking or ignoring 1475.Dv SIGTTOU 1476signals are excepted and allowed to produce output and the 1477.Dv SIGTTOU 1478signal 1479is not sent. 1480.Pp 1481If 1482.Dv NOKERNINFO 1483is set, the kernel does not produce a status message 1484when processing 1485.Dv STATUS 1486characters (see 1487.Dv STATUS ) . 1488.Ss Special Control Characters 1489The special control characters values are defined by the array 1490.Fa c_cc . 1491This table lists the array index, the corresponding special character, 1492and the system default value. 1493For an accurate list of 1494the system defaults, consult the header file 1495.Aq Pa ttydefaults.h . 1496.Pp 1497.Bl -column "Index Name" "Special Character" -offset indent -compact 1498.It Em "Index Name Special Character Default Value" 1499.It Dv VEOF Ta EOF Ta \&^D 1500.It Dv VEOL Ta EOL Ta _POSIX_VDISABLE 1501.It Dv VEOL2 Ta EOL2 Ta _POSIX_VDISABLE 1502.It Dv VERASE Ta ERASE Ta \&^? Ql \&\e177 1503.It Dv VWERASE Ta WERASE Ta \&^W 1504.It Dv VKILL Ta KILL Ta \&^U 1505.It Dv VREPRINT Ta REPRINT Ta \&^R 1506.It Dv VINTR Ta INTR Ta \&^C 1507.It Dv VQUIT Ta QUIT Ta \&^\e\e Ql \&\e34 1508.It Dv VSUSP Ta SUSP Ta \&^Z 1509.It Dv VDSUSP Ta DSUSP Ta \&^Y 1510.It Dv VSTART Ta START Ta \&^Q 1511.It Dv VSTOP Ta STOP Ta \&^S 1512.It Dv VLNEXT Ta LNEXT Ta \&^V 1513.It Dv VDISCARD Ta DISCARD Ta \&^O 1514.It Dv VMIN Ta --- Ta \&1 1515.It Dv VTIME Ta --- Ta \&0 1516.It Dv VSTATUS Ta STATUS Ta \&^T 1517.El 1518.Pp 1519If the 1520value of one of the changeable special control characters (see 1521.Sx "Special Characters" ) 1522is 1523.Dv {_POSIX_VDISABLE} , 1524that function is disabled; that is, no input 1525data is recognized as the disabled special character. 1526If 1527.Dv ICANON 1528is 1529not set, the value of 1530.Dv {_POSIX_VDISABLE} 1531has no special meaning for the 1532.Dv VMIN 1533and 1534.Dv VTIME 1535entries of the 1536.Fa c_cc 1537array. 1538.Pp 1539The initial values of the flags and control characters 1540after 1541.Xr open 2 1542is set according to the values in the header 1543.Aq Pa sys/ttydefaults.h . 1544.Sh SEE ALSO 1545.Xr tcsendbreak 3 , 1546.Xr tcsetattr 3 1547