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