1.\" $OpenBSD: tty.4,v 1.16 2001/06/23 08:01:54 pjanzen Exp $ 2.\" $NetBSD: tty.4,v 1.4 1996/03/19 04:26:01 paulus Exp $ 3.\" 4.\" Copyright (c) 1991, 1992, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)tty.4 8.3 (Berkeley) 4/19/94 36.\" 37.Dd August 14, 1992 38.Dt TTY 4 39.Os 40.Sh NAME 41.Nm tty 42.Nd general terminal interface 43.Sh SYNOPSIS 44.Fd #include <sys/ioctl.h> 45.Sh DESCRIPTION 46This section describes the interface to the terminal drivers 47in the system. 48.Ss Terminal Special Files 49Each hardware terminal port on the system usually has a terminal special device 50file associated with it in the directory 51.Pa /dev/ 52(for 53example, 54.Pa /dev/tty03 ) . 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 ) . 60There is also a special case of a terminal file that connects not to 61a hardware terminal port, but to another program on the other side. 62These special terminal devices are called 63.Em ptys 64and provide the mechanism necessary to give users the same interface to the 65system when logging in over a network (using 66.Xr rlogin 1 , 67or 68.Xr telnet 1 69for example). Even in these cases the details of how the terminal 70file was opened and set up is already handled by special software 71in the system. 72Thus, users do not normally need to worry about the details of 73how these lines are opened or used. 74.Pp 75For hardware terminal ports, dial-out is supported through matching 76device nodes called calling units. For instance, the terminal called 77.Pa /dev/tty03 78would have a matching calling unit called 79.Pa /dev/cua03 . 80These two devices are normally differentiated by creating the calling 81unit device node with a minor number 128 greater than the dial-in 82device node. Whereas the dial-in device (the 83.Em tty ) 84normally 85requires a hardware signal to indicate to the system that it is active, 86the dial-out device (the 87.Em cua ) 88does not, and hence can communicate unimpeded 89with a device such as a modem. This means that a process like 90.Xr getty 8 91will wait on a dial-in device until a connection is established. 92Meanwhile, a dial-out connection can be established on the dial-out 93device (for the very same hardware terminal port) without disturbing 94anything else on the system. The 95.Xr getty 8 96process does not even notice that anything is happening on the terminal 97port. If a connecting call comes in after the dial-out connection has 98finished, the 99.Xr getty 8 100process will deal with it properly, without having noticed the 101intervening dial-out action. 102For more information on dial-out, see 103.Xr tip 1 , 104.Xr cu 1 , 105and 106.Xr uucp 1 . 107.Pp 108When an interactive user logs in, the system prepares the line to 109behave in a certain way (called a 110.Em "line discipline" ) , 111the particular details of which is described in 112.Xr stty 1 113at the command level, and in 114.Xr termios 4 115at the programming level. A user may be concerned with changing 116settings associated with his particular login terminal and should refer 117to the preceding man pages for the common cases. The remainder of 118this man page is concerned 119with describing details of using and controlling terminal devices 120at a low level, such as that possibly required by a program wishing 121to provide features similar to those provided by the system. 122.Ss Line disciplines 123A terminal file is used like any other file in the system in that 124it can be opened, read, and written to using standard system 125calls. For each existing terminal file, there is a software processing module 126called a 127.Em "line discipline" 128is associated with it. The 129.Em "line discipline" 130essentially glues the low level device driver code with the high 131level generic interface routines (such as 132.Xr read 2 133and 134.Xr write 2 ), 135and is responsible for implementing the semantics associated 136with the device. When a terminal file is first opened by a program, 137the default 138.Em "line discipline" 139called the 140.Dv termios 141line discipline is associated with the file. This is the primary 142line discipline that is used in most cases and provides the semantics 143that users normally associate with a terminal. When the 144.Dv termios 145line discipline is in effect, the terminal file behaves and is 146operated according to the rules described in 147.Xr termios 4 . 148Please refer to that man page for a full description of the terminal 149semantics. 150The operations described here 151generally represent features common 152across all 153.Em "line disciplines" , 154although some of these calls may not 155make sense in conjunction with a line discipline other than 156.Dv termios , 157and some may not be supported by the underlying 158hardware (or lack thereof, as in the case of ptys). 159.Ss Terminal File Operations 160All of the following operations are invoked using the 161.Xr ioctl 2 162system call. Refer to that man page for a description of 163the 164.Em request 165and 166.Em argp 167parameters. 168In addition to the ioctl 169.Em requests 170defined here, the specific line discipline 171in effect will define other 172.Em requests 173specific to it (actually 174.Xr termios 4 175defines them as function calls, not ioctl 176.Em requests . ) 177The following section lists the available ioctl requests. The 178name of the request, a description of its purpose, and the typed 179.Em argp 180parameter (if any) 181are listed. For example, the first entry says 182.Pp 183.D1 Em "TIOCSETD int *ldisc" 184.Pp 185and would be called on the terminal associated with 186file descriptor zero by the following code fragment: 187.Bd -literal 188 int ldisc; 189 190 ldisc = TTYDISC; 191 ioctl(0, TIOCSETD, &ldisc); 192.Ed 193.Ss Terminal File Request Descriptions 194.Bl -tag -width TIOCGWINSZ 195.It Dv TIOCSETD Fa int *ldisc 196Change to the new line discipline pointed to by 197.Fa ldisc . 198The available line disciplines are listed in 199.Pa Aq sys/ttycom.h 200and currently are: 201.Pp 202.Bl -tag -width TIOCGWINSZ -compact 203.It TTYDISC 204Termios interactive line discipline. 205.It TABLDISC 206Tablet line discipline. 207.It SLIPDISC 208Serial IP line discipline. 209.It PPPDISC 210Point to Point Protocol line discipline. 211.It STRIPDISC 212Starmode Radio IP line discipline. 213.El 214.Pp 215.It Dv TIOCGETD Fa int *ldisc 216Return the current line discipline in the integer pointed to by 217.Fa ldisc . 218.It Dv TIOCSBRK Fa void 219Set the terminal hardware into BREAK condition. 220.It Dv TIOCCBRK Fa void 221Clear the terminal hardware BREAK condition. 222.It Dv TIOCSDTR Fa void 223Assert data terminal ready (DTR). 224.It Dv TIOCCDTR Fa void 225Clear data terminal ready (DTR). 226.It Dv TIOCGPGRP Fa int *tpgrp 227Return the current process group the terminal is associated 228with in the integer pointed to by 229.Fa tpgrp . 230This is the underlying call that implements the 231.Xr termios 4 232.Fn tcgetattr 233call. 234.It Dv TIOCSPGRP Fa int *tpgrp 235Associate the terminal with the process group (as an integer) pointed to by 236.Fa tpgrp . 237This is the underlying call that implements the 238.Xr termios 4 239.Fn tcsetattr 240call. 241.It Dv TIOCGETA Fa struct termios *term 242Place the current value of the termios state associated with the 243device in the termios structure pointed to by 244.Fa term . 245This is the underlying call that implements the 246.Xr termios 4 247.Fn tcgetattr 248call. 249.It Dv TIOCSETA Fa struct termios *term 250Set the termios state associated with the device immediately. 251This is the underlying call that implements the 252.Xr termios 4 253.Fn tcsetattr 254call with the 255.Dv TCSANOW 256option. 257.It Dv TIOCSETAW Fa struct termios *term 258First wait for any output to complete, then set the termios state 259associated with the device. 260This is the underlying call that implements the 261.Xr termios 4 262.Fn tcsetattr 263call with the 264.Dv TCSADRAIN 265option. 266.It Dv TIOCSETAF Fa struct termios *term 267First wait for any output to complete, clear any pending input, 268then set the termios state associated with the device. 269This is the underlying call that implements the 270.Xr termios 4 271.Fn tcsetattr 272call with the 273.Dv TCSAFLUSH 274option. 275.It Dv TIOCOUTQ Fa int *num 276Place the current number of characters in the output queue in the 277integer pointed to by 278.Fa num . 279.It Dv TIOCSTI Fa char *cp 280Simulate typed input. Pretend as if the terminal received the 281character pointed to by 282.Fa cp . 283.It Dv TIOCNOTTY Fa void 284This call is obsolete but left for compatibility. In the past, when 285a process that didn't have a controlling terminal (see 286.Em The Controlling Terminal 287in 288.Xr termios 4 ) 289first opened a terminal device, it acquired that terminal as its 290controlling terminal. For some programs this was a hazard as they 291didn't want a controlling terminal in the first place, and this 292provided a mechanism to disassociate the controlling terminal from 293the calling process. It 294.Em must 295be called by opening the file 296.Pa /dev/tty 297and calling 298.Dv TIOCNOTTY 299on that file descriptor. 300.Pp 301The current system does not allocate a controlling terminal to 302a process on an 303.Fn open 304call: there is a specific ioctl called 305.Dv TIOCSCTTY 306to make a terminal the controlling 307terminal. 308In addition, a program can 309.Fn fork 310and call the 311.Fn setsid 312system call which will place the process into its own session - which 313has the effect of disassociating it from the controlling terminal. This 314is the new and preferred method for programs to lose their controlling 315terminal. 316.It Dv TIOCSTOP Fa void 317Stop output on the terminal (like typing ^S at the keyboard). 318.It Dv TIOCSTART Fa void 319Start output on the terminal (like typing ^Q at the keyboard). 320.It Dv TIOCSCTTY Fa void 321Make the terminal the controlling terminal for the process (the process 322must not currently have a controlling terminal). 323.It Dv TIOCDRAIN Fa void 324Wait until all output is drained. 325.It Dv TIOCEXCL Fa void 326Set exclusive use on the terminal. No further opens are permitted 327except by root. Of course, this means that programs that are run by 328root (or setuid) will not obey the exclusive setting - which limits 329the usefulness of this feature. 330.It Dv TIOCNXCL Fa void 331Clear exclusive use of the terminal. Further opens are permitted. 332.It Dv TIOCFLUSH Fa int *what 333If the value of the int pointed to by 334.Fa what 335contains the 336.Dv FREAD 337bit as defined in 338.Pa Aq sys/fcntl.h , 339then all characters in the input queue are cleared. If it contains 340the 341.Dv FWRITE 342bit, then all characters in the output queue are cleared. If the 343value of the integer is zero, then it behaves as if both the 344.Dv FREAD 345and 346.Dv FWRITE 347bits were set (i.e. clears both queues). 348.It Dv TIOCGWINSZ Fa struct winsize *ws 349Put the window size information associated with the terminal in the 350.Va winsize 351structure pointed to by 352.Fa ws . 353The window size structure contains the number of rows and columns (and pixels 354if appropriate) of the devices attached to the terminal. It is set by user software 355and is the means by which most full\&-screen oriented programs determine the 356screen size. The 357.Va winsize 358structure is defined in 359.Pa Aq sys/ioctl.h . 360.It Dv TIOCSWINSZ Fa struct winsize *ws 361Set the window size associated with the terminal to be the value in 362the 363.Va winsize 364structure pointed to by 365.Fa ws 366(see above). 367.It Dv TIOCCONS Fa int *on 368If 369.Fa on 370points to a non-zero integer, redirect kernel console output 371.Po 372kernel 373.Fn printf Ns s 374.Pc 375to this terminal. 376If 377.Fa on 378points to a zero integer, redirect kernel console output back to the normal 379console. This is usually used on workstations to redirect kernel messages 380to a particular window. 381.It Dv TIOCMSET Fa int *state 382The integer pointed to by 383.Fa state 384contains bits that correspond to modem state. Following is a list 385of defined variables and the modem state they represent: 386.Pp 387.Bl -tag -width TIOCMXCTS -compact 388.It TIOCM_LE 389Line Enable. 390.It TIOCM_DTR 391Data Terminal Ready. 392.It TIOCM_RTS 393Request To Send. 394.It TIOCM_ST 395Secondary Transmit. 396.It TIOCM_SR 397Secondary Receive. 398.It TIOCM_CTS 399Clear To Send. 400.It TIOCM_CAR 401Carrier Detect. 402.It TIOCM_CD 403Carrier Detect (synonym). 404.It TIOCM_RNG 405Ring Indication. 406.It TIOCM_RI 407Ring Indication (synonym). 408.It TIOCM_DSR 409Data Set Ready. 410.El 411.Pp 412This call sets the terminal modem state to that represented by 413.Fa state . 414Not all terminals may support this. 415.It Dv TIOCMGET Fa int *state 416Return the current state of the terminal modem lines as represented 417above in the integer pointed to by 418.Fa state . 419.It Dv TIOCMBIS Fa int *state 420The bits in the integer pointed to by 421.Fa state 422represent modem state as described above; however, the state is OR-ed 423in with the current state. 424.It Dv TIOCMBIC Fa int *state 425The bits in the integer pointed to by 426.Fa state 427represent modem state as described above; however, each bit which is on 428in 429.Fa state 430is cleared in the terminal. 431.It Dv TIOCSFLAGS Fa int *state 432The bits in the integer pointed to by 433.Fa state 434contain bits that correspond to serial port state. Following is a list 435of defined variables and the serial port state they represent: 436.Pp 437.Bl -tag -width TIOCFLAG_SOFTCAR -compact 438.It TIOCFLAG_SOFTCAR 439Ignore hardware carrier. 440.It TIOCFLAG_CLOCAL 441Set clocal on open. 442.It TIOCFLAG_CRTSCTS 443Set crtscts on open. 444.It TIOCFLAG_MDMBUF 445Set mdmbuf on open. 446.El 447.Pp 448This call sets the serial port state to that represented by 449.Fa state . 450Not all serial ports may support this. 451.It Dv TIOCGFLAGS Fa int *state 452Return the current state of the serial port as represented 453above in the integer pointed to by 454.Fa state . 455.El 456.Sh SEE ALSO 457.Xr stty 1 , 458.Xr tty 1 , 459.Xr ioctl 2 , 460.Xr pty 4 , 461.Xr termios 4 , 462.Xr ttys 5 , 463.Xr getty 8 464.Sh HISTORY 465The cua support is inspired by similar support in SunOS. 466