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