1.\" $NetBSD: tty.4,v 1.31 2021/08/17 14:11:22 andvar 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 7, 2019 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.It Dv TIOCGLINED Fa char name[32] 183Return the current line discipline in the string pointed to by 184.Fa name . 185.It Dv TIOCSBRK Fa void 186Set the terminal hardware into BREAK condition. 187.It Dv TIOCCBRK Fa void 188Clear the terminal hardware BREAK condition. 189.It Dv TIOCSDTR Fa void 190Assert data terminal ready (DTR). 191.It Dv TIOCCDTR Fa void 192Clear data terminal ready (DTR). 193.It Dv TIOCGPGRP Fa int *tpgrp 194Return the current process group the terminal is associated 195with in the integer pointed to by 196.Fa tpgrp . 197This is the underlying call that implements the 198.Xr tcgetpgrp 3 199call. 200.It Dv TIOCSPGRP Fa int *tpgrp 201Associate the terminal with the process group (as an integer) pointed to by 202.Fa tpgrp . 203This is the underlying call that implements the 204.Xr tcsetpgrp 3 205call. 206.It Dv TIOCGETA Fa struct termios *term 207Place the current value of the termios state associated with the 208device in the termios structure pointed to by 209.Fa term . 210This is the underlying call that implements the 211.Xr tcgetattr 3 212call. 213.It Dv TIOCSETA Fa struct termios *term 214Set the termios state associated with the device immediately. 215This is the underlying call that implements the 216.Xr tcsetattr 3 217call with the 218.Dv TCSANOW 219option. 220.It Dv TIOCSETAW Fa struct termios *term 221First wait for any output to complete, then set the termios state 222associated with the device. 223This is the underlying call that implements the 224.Xr tcsetattr 3 225call with the 226.Dv TCSADRAIN 227option. 228.It Dv TIOCSETAF Fa struct termios *term 229First wait for any output to complete, clear any pending input, 230then set the termios state associated with the device. 231This is the underlying call that implements the 232.Xr tcsetattr 3 233call with the 234.Dv TCSAFLUSH 235option. 236.It Dv TIOCOUTQ Fa int *num 237Place the current number of characters in the output queue in the 238integer pointed to by 239.Fa num . 240.It Dv TIOCSTI Fa char *cp 241Simulate typed input. 242Pretend as if the terminal received the character pointed to by 243.Fa cp . 244.It Dv TIOCNOTTY Fa void 245This call is obsolete but left for compatibility. 246In the past, when a process that didn't have a controlling terminal 247(see 248.Em The Controlling Terminal 249in 250.Xr termios 4 ) 251first opened a terminal device, it acquired that terminal as its 252controlling terminal. 253For some programs this was a hazard as they didn't want a controlling 254terminal in the first place, and this provided a mechanism to 255disassociate the controlling terminal from the calling process. 256It 257.Em must 258be called by opening the file 259.Pa /dev/tty 260and calling 261.Dv TIOCNOTTY 262on that file descriptor. 263.Pp 264The current system does not allocate a controlling terminal to 265a process on an 266.Fn open 267call: there is a specific ioctl called 268.Dv TIOCSCTTY 269to make a terminal the controlling 270terminal. 271In addition, a program can 272.Fn fork 273and call the 274.Fn setsid 275system call which will place the process into its own session - which 276has the effect of disassociating it from the controlling terminal. 277This is the new and preferred method for programs to lose their 278controlling terminal. 279.It Dv TIOCSTOP Fa void 280Stop output on the terminal (like typing ^S at the keyboard). 281.It Dv TIOCSTART Fa void 282Start output on the terminal (like typing ^Q at the keyboard). 283.It Dv TIOCSCTTY Fa void 284Make the terminal the controlling terminal for the process (the process 285must not currently have a controlling terminal). 286.It Dv TIOCDRAIN Fa void 287Wait until all output is drained. 288.It Dv TIOCEXCL Fa void 289Set exclusive use on the terminal. 290No further opens are permitted except by root. 291Of course, this means that programs that are run by root (or setuid) 292will not obey the exclusive setting - which limits the usefulness 293of this feature. 294.It Dv TIOCNXCL Fa void 295Clear exclusive use of the terminal. 296Further opens are permitted. 297.It Dv TIOCFLUSH Fa int *what 298If the value of the int pointed to by 299.Fa what 300contains the 301.Dv FREAD 302bit as defined in 303.In sys/fcntl.h , 304then all characters in the input queue are cleared. 305If it contains the 306.Dv FWRITE 307bit, then all characters in the output queue are cleared. 308If the value of the integer is zero, then it behaves as if both the 309.Dv FREAD 310and 311.Dv FWRITE 312bits were set (i.e. clears both queues). 313.It Dv TIOCGWINSZ Fa struct winsize *ws 314Put the window size information associated with the terminal in the 315.Va winsize 316structure pointed to by 317.Fa ws . 318The window size structure contains the number of rows and columns (and pixels 319if appropriate) of the devices attached to the terminal. 320It is set by user software and is the means by which most full\&-screen 321oriented programs determine the screen size. 322The 323.Va winsize 324structure is defined in 325.In sys/ioctl.h . 326.It Dv TIOCSWINSZ Fa struct winsize *ws 327Set the window size associated with the terminal to be the value in 328the 329.Va winsize 330structure pointed to by 331.Fa ws 332(see above). 333.It Dv TIOCGQSIZE Fa int *qsize 334Get the current size of the tty input and output queues. 335.It Dv TIOCSQSIZE Fa int *qsize 336Set the size of the tty input and output queues. 337Valid sizes are between 338.Dv 1024 339and 340.Dv 65536 341and input values are converted to a power of two. 342All pending input and output is dropped. 343.It Dv TIOCCONS Fa int *on 344If 345.Fa on 346points to a non-zero integer, redirect kernel console output (kernel printf's) 347to this terminal. 348If 349.Fa on 350points to a zero integer, redirect kernel console output back to the normal 351console. 352This is usually used on workstations to redirect kernel messages 353to a particular window. 354.It Dv TIOCMSET Fa int *state 355The integer pointed to by 356.Fa state 357contains bits that correspond to modem state. 358Following is a list of defined variables and the modem state they represent: 359.Pp 360.Bl -tag -width TIOCMXCTS -compact 361.It TIOCM_LE 362Line Enable. 363.It TIOCM_DTR 364Data Terminal Ready. 365.It TIOCM_RTS 366Request To Send. 367.It TIOCM_ST 368Secondary Transmit. 369.It TIOCM_SR 370Secondary Receive. 371.It TIOCM_CTS 372Clear To Send. 373.It TIOCM_CAR 374Carrier Detect. 375.It TIOCM_CD 376Carrier Detect (synonym). 377.It TIOCM_RNG 378Ring Indication. 379.It TIOCM_RI 380Ring Indication (synonym). 381.It TIOCM_DSR 382Data Set Ready. 383.El 384.Pp 385This call sets the terminal modem state to that represented by 386.Fa state . 387Not all terminals may support this. 388.It Dv TIOCMGET Fa int *state 389Return the current state of the terminal modem lines as represented 390above in the integer pointed to by 391.Fa state . 392.It Dv TIOCMBIS Fa int *state 393The bits in the integer pointed to by 394.Fa state 395represent modem state as described above, however the state is OR-ed 396in with the current state. 397.It Dv TIOCMBIC Fa int *state 398The bits in the integer pointed to by 399.Fa state 400represent modem state as described above, however each bit which is on 401in 402.Fa state 403is cleared in the terminal. 404.It Dv TIOCSFLAGS Fa int *state 405The bits in the integer pointed to by 406.Fa state 407contain bits that correspond to serial port state. 408Following is a list of defined flag values and the serial port state they 409represent: 410.Pp 411.Bl -tag -width TIOCFLAG_SOFTCAR -compact 412.It TIOCFLAG_SOFTCAR 413Ignore hardware carrier. 414.It TIOCFLAG_CLOCAL 415Set the 416.Xr termios 4 417.Dv CLOCAL 418flag on open. 419.It TIOCFLAG_CRTSCTS 420Set the 421.Xr termios 4 422.Dv CRTSCTS 423flag on open. 424.It TIOCFLAG_MDMBUF 425Set the 426.Xr termios 4 427.Dv MDMBUF 428flag on open. 429.El 430.Pp 431This call sets the serial port state to that represented by 432.Fa state . 433Not all serial ports may support this. 434.It Dv TIOCGFLAGS Fa int *state 435Return the current state of the serial port as represented 436above in the integer pointed to by 437.Fa state . 438.El 439.Sh COMPATIBILITY 440Two ioctls are maintained for backwards compatibility. 441They provide methods to get and set the current line discipline, 442but are not extensible. 443.Bl -tag -width TIOCGWINSZ 444.It Dv TIOCSETD Fa int *ldisc 445Change to the new line discipline pointed to by 446.Fa ldisc . 447The old list of available line disciplines are listed in 448.In sys/ttycom.h 449and are: 450.Pp 451.Bl -tag -width TIOCGWINSZ -compact 452.It TTYDISC 453Termios interactive line discipline. 454.It TABLDISC 455Tablet line discipline. 456.It SLIPDISC 457Serial IP line discipline. 458.It PPPDISC 459Point to Point Protocol line discipline. 460.It STRIPDISC 461Starmode Radio IP line discipline. 462.El 463.It Dv TIOCGETD Fa int *ldisc 464Return the current line discipline in the integer pointed to by 465.Fa ldisc . 466.El 467.Sh SEE ALSO 468.Xr stty 1 , 469.Xr ioctl 2 , 470.Xr tcgetattr 3 , 471.Xr tcsetattr 3 , 472.Xr ttyaction 3 , 473.Xr pty 4 , 474.Xr termios 4 , 475.Xr ttys 5 , 476.Xr getty 8 , 477.Xr linedisc 9 478.Sh HISTORY 479A console typewriter device 480.Pa /dev/tty 481and asynchronous communication interfaces 482.Pa /dev/tty[0-5] 483first appeared in 484.At v1 . 485Separate dial-out device files were implemented in SunOS 4. 486They were cloned by 487.An Charles M. Hannum 488for 489.Nx 1.4 . 490