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