1.\" $NetBSD: tty.4,v 1.28 2011/09/24 00:06:20 christos 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.\" @(#)tty.4 8.3 (Berkeley) 4/19/94 31.\" 32.Dd September 9, 2011 33.Dt TTY 4 34.Os 35.Sh NAME 36.Nm tty 37.Nd general terminal interface 38.Sh SYNOPSIS 39.In sys/ioctl.h 40.Sh DESCRIPTION 41This section describes the interface to the terminal drivers 42in the system. 43.Ss Terminal Special Files 44Each hardware terminal port on the system usually has two terminal special 45device files associated with it in the directory 46.Pa /dev/ 47(for example, 48.Pa /dev/tty03 49and 50.Pa /dev/dty03 ) . 51.Pp 52The 53.Pa /dev/ttyXX 54special file is used for dial-in modems and terminals. 55When a user logs into 56the system on one of these hardware terminal ports, the system has already 57opened the associated device and prepared the line for normal interactive 58use (see 59.Xr getty 8 ) . 60.Pp 61The 62.Pa /dev/dtyXX 63special file is a SunOS-compatible dial-out device. 64Unlike the dial-in device, opening the dial-out device never blocks. 65If the corresponding dial-in device is already opened (not blocked 66in the open waiting for carrier), then the dial-out open will fail 67immediately; otherwise it will succeed immediately. 68While the dial-out device is open, the dial-in device may not be opened. 69If the dial-in open is blocking, it will wait until the dial-out 70device is closed (and carrier is detected); otherwise it will fail immediately. 71.Pp 72There is also a special case of a terminal file that connects not to 73a hardware terminal port, but to another program on the other side. 74These special terminal devices are called 75.Em ptys 76(pseudo terminals) 77and provide the mechanism necessary to give users the same interface to the 78system when logging in over a network (using 79.Xr rlogin 1 , 80or 81.Xr telnet 1 82for example.) Even in these cases the details of how the terminal 83file was opened and set up is already handled by special software 84in the system. 85Thus, users do not normally need to worry about the details of 86how these lines are opened or used. 87Also, these lines are often used for dialing out of a system (through 88an out-calling modem), but again the system provides programs that 89hide the details of accessing these terminal special files (see 90.Xr tip 1 ) . 91.Pp 92When an interactive user logs in, the system prepares the line to 93behave in a certain way (called a 94.Em line discipline ) , 95the particular details of which is described in 96.Xr stty 1 97at the command level, and in 98.Xr termios 4 99at the programming level. 100A user may be concerned with changing settings associated with his 101particular login terminal and should refer to the preceding man 102pages for the common cases. 103The remainder of this man page is concerned 104with describing details of using and controlling terminal devices 105at a low level, such as that possibly required by a program wishing 106to provide features similar to those provided by the system. 107.Ss Line disciplines 108A terminal file is used like any other file in the system in that 109it can be opened, read, and written to using standard system calls. 110For each existing terminal file, there is a software processing module 111called a 112.Em line discipline 113associated with it. 114The 115.Em line discipline 116essentially glues the low level device driver code with the high 117level generic interface routines (such as 118.Xr read 2 119and 120.Xr write 2 ) , 121and is responsible for implementing the semantics associated 122with the device. 123When a terminal file is first opened by a program, the default 124.Em line discipline 125called the 126.Dv termios 127line discipline is associated with the file. 128This is the primary line discipline that is used in most cases and 129provides the semantics that users normally associate with a terminal. 130When the 131.Dv termios 132line discipline is in effect, the terminal file behaves and is 133operated according to the rules described in 134.Xr termios 4 . 135Please refer to that man page for a full description of the terminal 136semantics. 137The operations described here 138generally represent features common 139across all 140.Em line disciplines , 141however some of these calls may not 142make sense in conjunction with a line discipline other than 143.Dv termios , 144and some may not be supported by the underlying 145hardware (or lack thereof, as in the case of ptys). 146.Ss Terminal File Operations 147All of the following operations are invoked using the 148.Xr ioctl 2 149system call. 150Refer to that man page for a description of the 151.Em request 152and 153.Em argp 154parameters. 155In addition to the ioctl 156.Em requests 157defined here, the specific line discipline 158in effect will define other 159.Em requests 160specific to it (actually 161.Xr termios 4 162defines them as function calls, not ioctl 163.Em requests . ) 164The following section lists the available ioctl requests. 165The name of the request, a description of its purpose, and the typed 166.Em argp 167parameter (if any) are listed. 168For example, the first entry says 169.Pp 170.D1 Em TIOCSLINED char name[32] 171.Pp 172and would be called on the terminal associated with 173file descriptor zero by the following code fragment: 174.Bd -literal 175 ioctl(0, TIOCSLINED, "termios"); 176.Ed 177.Ss Terminal File Request Descriptions 178.Bl -tag -width TIOCGWINSZ 179.It Dv TIOCSLINED Fa char name[32] 180Change to the new line discipline called 181.Fa name . 182.Pp 183.It Dv TIOCGLINED Fa char name[32] 184Return the current line discipline in the string pointed to by 185.Fa name . 186.It Dv TIOCSBRK Fa void 187Set the terminal hardware into BREAK condition. 188.It Dv TIOCCBRK Fa void 189Clear the terminal hardware BREAK condition. 190.It Dv TIOCSDTR Fa void 191Assert data terminal ready (DTR). 192.It Dv TIOCCDTR Fa void 193Clear data terminal ready (DTR). 194.It Dv TIOCGPGRP Fa int *tpgrp 195Return the current process group the terminal is associated 196with in the integer pointed to by 197.Fa tpgrp . 198This is the underlying call that implements the 199.Xr tcgetpgrp 3 200call. 201.It Dv TIOCSPGRP Fa int *tpgrp 202Associate the terminal with the process group (as an integer) pointed to by 203.Fa tpgrp . 204This is the underlying call that implements the 205.Xr tcsetpgrp 3 206call. 207.It Dv TIOCGETA Fa struct termios *term 208Place the current value of the termios state associated with the 209device in the termios structure pointed to by 210.Fa term . 211This is the underlying call that implements the 212.Xr tcgetattr 3 213call. 214.It Dv TIOCSETA Fa struct termios *term 215Set the termios state associated with the device immediately. 216This is the underlying call that implements the 217.Xr tcsetattr 3 218call with the 219.Dv TCSANOW 220option. 221.It Dv TIOCSETAW Fa struct termios *term 222First wait for any output to complete, then set the termios state 223associated with the device. 224This is the underlying call that implements the 225.Xr tcsetattr 3 226call with the 227.Dv TCSADRAIN 228option. 229.It Dv TIOCSETAF Fa struct termios *term 230First wait for any output to complete, clear any pending input, 231then set the termios state associated with the device. 232This is the underlying call that implements the 233.Xr tcsetattr 3 234call with the 235.Dv TCSAFLUSH 236option. 237.It Dv TIOCOUTQ Fa int *num 238Place the current number of characters in the output queue in the 239integer pointed to by 240.Fa num . 241.It Dv TIOCSTI Fa char *cp 242Simulate typed input. 243Pretend as if the terminal received the character pointed to by 244.Fa cp . 245.It Dv TIOCNOTTY Fa void 246This call is obsolete but left for compatibility. 247In the past, when a process that didn't have a controlling terminal 248(see 249.Em The Controlling Terminal 250in 251.Xr termios 4 ) 252first opened a terminal device, it acquired that terminal as its 253controlling terminal. 254For some programs this was a hazard as they didn't want a controlling 255terminal in the first place, and this provided a mechanism to 256disassociate the controlling terminal from the calling process. 257It 258.Em must 259be called by opening the file 260.Pa /dev/tty 261and calling 262.Dv TIOCNOTTY 263on that file descriptor. 264.Pp 265The current system does not allocate a controlling terminal to 266a process on an 267.Fn open 268call: there is a specific ioctl called 269.Dv TIOCSCTTY 270to make a terminal the controlling 271terminal. 272In addition, a program can 273.Fn fork 274and call the 275.Fn setsid 276system call which will place the process into its own session - which 277has the effect of disassociating it from the controlling terminal. 278This is the new and preferred method for programs to lose their 279controlling terminal. 280.It Dv TIOCSTOP Fa void 281Stop output on the terminal (like typing ^S at the keyboard). 282.It Dv TIOCSTART Fa void 283Start output on the terminal (like typing ^Q at the keyboard). 284.It Dv TIOCSCTTY Fa void 285Make the terminal the controlling terminal for the process (the process 286must not currently have a controlling terminal). 287.It Dv TIOCDRAIN Fa void 288Wait until all output is drained. 289.It Dv TIOCEXCL Fa void 290Set exclusive use on the terminal. 291No further opens are permitted except by root. 292Of course, this means that programs that are run by root (or setuid) 293will not obey the exclusive setting - which limits the usefulness 294of this feature. 295.It Dv TIOCNXCL Fa void 296Clear exclusive use of the terminal. 297Further opens are permitted. 298.It Dv TIOCFLUSH Fa int *what 299If the value of the int pointed to by 300.Fa what 301contains the 302.Dv FREAD 303bit as defined in 304.In sys/fcntl.h , 305then all characters in the input queue are cleared. 306If it contains the 307.Dv FWRITE 308bit, then all characters in the output queue are cleared. 309If the value of the integer is zero, then it behaves as if both the 310.Dv FREAD 311and 312.Dv FWRITE 313bits were set (i.e. clears both queues). 314.It Dv TIOCGWINSZ Fa struct winsize *ws 315Put the window size information associated with the terminal in the 316.Va winsize 317structure pointed to by 318.Fa ws . 319The window size structure contains the number of rows and columns (and pixels 320if appropriate) of the devices attached to the terminal. 321It is set by user software and is the means by which most full\&-screen 322oriented programs determine the screen size. 323The 324.Va winsize 325structure is defined in 326.In sys/ioctl.h . 327.It Dv TIOCSWINSZ Fa struct winsize *ws 328Set the window size associated with the terminal to be the value in 329the 330.Va winsize 331structure pointed to by 332.Fa ws 333(see above). 334.It Dv TIOCGQSIZE Fa int *qsize 335Get the current size of the tty input and output queues. 336.It Dv TIOCSQSIZE Fa int *qsize 337Set the size of the tty input and output queues. 338Valid sizes are between 339.Dv 1024 340and 341.Dv 65536 342and input values are converted to a power of two. 343All pending input and output is dropped. 344.It Dv TIOCCONS Fa int *on 345If 346.Fa on 347points to a non-zero integer, redirect kernel console output (kernel printf's) 348to this terminal. 349If 350.Fa on 351points to a zero integer, redirect kernel console output back to the normal 352console. 353This is usually used on workstations to redirect kernel messages 354to a particular window. 355.It Dv TIOCMSET Fa int *state 356The integer pointed to by 357.Fa state 358contains bits that correspond to modem state. 359Following is a list of defined variables and the modem state they represent: 360.Pp 361.Bl -tag -width TIOCMXCTS -compact 362.It TIOCM_LE 363Line Enable. 364.It TIOCM_DTR 365Data Terminal Ready. 366.It TIOCM_RTS 367Request To Send. 368.It TIOCM_ST 369Secondary Transmit. 370.It TIOCM_SR 371Secondary Receive. 372.It TIOCM_CTS 373Clear To Send. 374.It TIOCM_CAR 375Carrier Detect. 376.It TIOCM_CD 377Carrier Detect (synonym). 378.It TIOCM_RNG 379Ring Indication. 380.It TIOCM_RI 381Ring Indication (synonym). 382.It TIOCM_DSR 383Data Set Ready. 384.El 385.Pp 386This call sets the terminal modem state to that represented by 387.Fa state . 388Not all terminals may support this. 389.It Dv TIOCMGET Fa int *state 390Return the current state of the terminal modem lines as represented 391above in the integer pointed to by 392.Fa state . 393.It Dv TIOCMBIS Fa int *state 394The bits in the integer pointed to by 395.Fa state 396represent modem state as described above, however the state is OR-ed 397in with the current state. 398.It Dv TIOCMBIC Fa int *state 399The bits in the integer pointed to by 400.Fa state 401represent modem state as described above, however each bit which is on 402in 403.Fa state 404is cleared in the terminal. 405.It Dv TIOCSFLAGS Fa int *state 406The bits in the integer pointed to by 407.Fa state 408contain bits that correspond to serial port state. 409Following is a list of defined flag values and the serial port state they 410represent: 411.Pp 412.Bl -tag -width TIOCFLAG_SOFTCAR -compact 413.It TIOCFLAG_SOFTCAR 414Ignore hardware carrier. 415.It TIOCFLAG_CLOCAL 416Set the 417.Xr termios 4 418.Dv CLOCAL 419flag on open. 420.It TIOCFLAG_CRTSCTS 421Set the 422.Xr termios 4 423.Dv CRTSCTS 424flag on open. 425.It TIOCFLAG_MDMBUF 426Set the 427.Xr termios 4 428.Dv MDMBUF 429flag on open. 430.El 431.Pp 432This call sets the serial port state to that represented by 433.Fa state . 434Not all serial ports may support this. 435.It Dv TIOCGFLAGS Fa int *state 436Return the current state of the serial port as represented 437above in the integer pointed to by 438.Fa state . 439.El 440.Sh COMPATIBILITY 441Two ioctls are maintained for backwards compatibility. 442They provide methods to get and set the current line discipline, 443but are not extensible. 444.Bl -tag -width TIOCGWINSZ 445.It Dv TIOCSETD Fa int *ldisc 446Change to the new line discipline pointed to by 447.Fa ldisc . 448The old list of available line disciplines are listed in 449.In sys/ttycom.h 450and are: 451.Pp 452.Bl -tag -width TIOCGWINSZ -compact 453.It TTYDISC 454Termios interactive line discipline. 455.It TABLDISC 456Tablet line discipline. 457.It SLIPDISC 458Serial IP line discipline. 459.It PPPDISC 460Point to Point Protocol line discipline. 461.It STRIPDISC 462Starmode Radio IP line discipline. 463.El 464.Pp 465.It Dv TIOCGETD Fa int *ldisc 466Return the current line discipline in the integer pointed to by 467.Fa ldisc . 468.El 469.Sh SEE ALSO 470.Xr stty 1 , 471.Xr ioctl 2 , 472.Xr tcgetattr 3 , 473.Xr tcsetattr 3 , 474.Xr ttyaction 3 , 475.Xr pty 4 , 476.Xr termios 4 , 477.Xr ttys 5 , 478.Xr getty 8 , 479.Xr linedisc 9 480.Sh HISTORY 481Separate dial-out device files were implemented in SunOS 4. 482They were cloned by 483.An Charles M. Hannum 484for 485.Nx 1.4 . 486