1.\" $NetBSD: tty.4,v 1.27 2011/04/28 12:15:35 wiz 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 October 7, 2006 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 TIOCCONS Fa int *on 335If 336.Fa on 337points to a non-zero integer, redirect kernel console output (kernel printf's) 338to this terminal. 339If 340.Fa on 341points to a zero integer, redirect kernel console output back to the normal 342console. 343This is usually used on workstations to redirect kernel messages 344to a particular window. 345.It Dv TIOCMSET Fa int *state 346The integer pointed to by 347.Fa state 348contains bits that correspond to modem state. 349Following is a list of defined variables and the modem state they represent: 350.Pp 351.Bl -tag -width TIOCMXCTS -compact 352.It TIOCM_LE 353Line Enable. 354.It TIOCM_DTR 355Data Terminal Ready. 356.It TIOCM_RTS 357Request To Send. 358.It TIOCM_ST 359Secondary Transmit. 360.It TIOCM_SR 361Secondary Receive. 362.It TIOCM_CTS 363Clear To Send. 364.It TIOCM_CAR 365Carrier Detect. 366.It TIOCM_CD 367Carrier Detect (synonym). 368.It TIOCM_RNG 369Ring Indication. 370.It TIOCM_RI 371Ring Indication (synonym). 372.It TIOCM_DSR 373Data Set Ready. 374.El 375.Pp 376This call sets the terminal modem state to that represented by 377.Fa state . 378Not all terminals may support this. 379.It Dv TIOCMGET Fa int *state 380Return the current state of the terminal modem lines as represented 381above in the integer pointed to by 382.Fa state . 383.It Dv TIOCMBIS Fa int *state 384The bits in the integer pointed to by 385.Fa state 386represent modem state as described above, however the state is OR-ed 387in with the current state. 388.It Dv TIOCMBIC Fa int *state 389The bits in the integer pointed to by 390.Fa state 391represent modem state as described above, however each bit which is on 392in 393.Fa state 394is cleared in the terminal. 395.It Dv TIOCSFLAGS Fa int *state 396The bits in the integer pointed to by 397.Fa state 398contain bits that correspond to serial port state. 399Following is a list of defined flag values and the serial port state they 400represent: 401.Pp 402.Bl -tag -width TIOCFLAG_SOFTCAR -compact 403.It TIOCFLAG_SOFTCAR 404Ignore hardware carrier. 405.It TIOCFLAG_CLOCAL 406Set the 407.Xr termios 4 408.Dv CLOCAL 409flag on open. 410.It TIOCFLAG_CRTSCTS 411Set the 412.Xr termios 4 413.Dv CRTSCTS 414flag on open. 415.It TIOCFLAG_MDMBUF 416Set the 417.Xr termios 4 418.Dv MDMBUF 419flag on open. 420.El 421.Pp 422This call sets the serial port state to that represented by 423.Fa state . 424Not all serial ports may support this. 425.It Dv TIOCGFLAGS Fa int *state 426Return the current state of the serial port as represented 427above in the integer pointed to by 428.Fa state . 429.El 430.Sh COMPATIBILITY 431Two ioctls are maintained for backwards compatibility. 432They provide methods to get and set the current line discipline, 433but are not extensible. 434.Bl -tag -width TIOCGWINSZ 435.It Dv TIOCSETD Fa int *ldisc 436Change to the new line discipline pointed to by 437.Fa ldisc . 438The old list of available line disciplines are listed in 439.In sys/ttycom.h 440and are: 441.Pp 442.Bl -tag -width TIOCGWINSZ -compact 443.It TTYDISC 444Termios interactive line discipline. 445.It TABLDISC 446Tablet line discipline. 447.It SLIPDISC 448Serial IP line discipline. 449.It PPPDISC 450Point to Point Protocol line discipline. 451.It STRIPDISC 452Starmode Radio IP line discipline. 453.El 454.Pp 455.It Dv TIOCGETD Fa int *ldisc 456Return the current line discipline in the integer pointed to by 457.Fa ldisc . 458.El 459.Sh SEE ALSO 460.Xr stty 1 , 461.Xr ioctl 2 , 462.Xr tcgetattr 3 , 463.Xr tcsetattr 3 , 464.Xr ttyaction 3 , 465.Xr pty 4 , 466.Xr termios 4 , 467.Xr ttys 5 , 468.Xr getty 8 , 469.Xr linedisc 9 470.Sh HISTORY 471Separate dial-out device files were implemented in SunOS 4. 472They were cloned by 473.An Charles M. Hannum 474for 475.Nx 1.4 . 476