161599Sbostic.\" Copyright (c) 1991, 1992, 1993 261599Sbostic.\" The Regents of the University of California. All rights reserved. 320632Smckusick.\" 455908Smarc.\" %sccs.include.redist.roff% 520632Smckusick.\" 6*66970Sbostic.\" @(#)tty.4 8.3 (Berkeley) 04/19/94 748410Sbostic.\" 855909Scael.Dd August 14, 1992 955908Smarc.Dt TTY 4 1055908Smarc.Os BSD 4 1155908Smarc.Sh NAME 1255908Smarc.Nm tty 1355908Smarc.Nd general terminal interface 1455908Smarc.Sh SYNOPSIS 1555908Smarc.Fd #include <sys/ioctl.h> 1655908Smarc.Sh DESCRIPTION 1755908SmarcThis section describes the interface to the terminal drivers 1855908Smarcin the system. 1955908Smarc.Ss Terminal Special Files 2055908SmarcEach hardware terminal port on the system usually has a terminal special device 2155908Smarcfile associated with it in the directory ``/dev/'' (for 2255908Smarcexample, ``/dev/tty03''). 2355908SmarcWhen a user logs into 2455908Smarcthe system on one of these hardware terminal ports, the system has already 2555908Smarcopened the associated device and prepared the line for normal interactive 2655908Smarcuse (see 2755908Smarc.Xr getty 8 .) 2855908SmarcThere is also a special case of a terminal file that connects not to 2955908Smarca hardware terminal port, but to another program on the other side. 3055908SmarcThese special terminal devices are called 3155908Smarc.Em ptys 3255908Smarcand provide the mechanism necessary to give users the same interface to the 3355908Smarcsystem when logging in over a network (using 3455908Smarc.Xr rlogin 1 , 3528263Skarelsor 3655908Smarc.Xr telnet 1 3755908Smarcfor example.) Even in these cases the details of how the terminal 3855908Smarcfile was opened and set up is already handled by special software 3955908Smarcin the system. 4055908SmarcThus, users do not normally need to worry about the details of 4155908Smarchow these lines are opened or used. Also, these lines are often used 4255908Smarcfor dialing out of a system (through an out-calling modem), but again 4355908Smarcthe system provides programs that hide the details of accessing 4455908Smarcthese terminal special files (see 4555908Smarc.Xr tip 2 .) 4655908Smarc.Pp 4755908SmarcWhen an interactive user logs in, the system prepares the line to 4855908Smarcbehave in a certain way (called a 4964994Smckusick.Em "line discipline" ) , 5055908Smarcthe particular details of which is described in 5155908Smarc.Xr stty 1 5255908Smarcat the command level, and in 5355908Smarc.Xr termios 4 5455908Smarcat the programming level. A user may be concerned with changing 5555908Smarcsettings associated with his particular login terminal and should refer 5655909Scaelto the preceding man pages for the common cases. The remainder of 5755908Smarcthis man page is concerned 5855908Smarcwith describing details of using and controlling terminal devices 5955908Smarcat a low level, such as that possibly required by a program wishing 6055908Smarcto provide features similar to those provided by the system. 6155908Smarc.Ss Line disciplines 6255908SmarcA terminal file is used like any other file in the system in that 6355908Smarcit can be opened, read, and written to using standard system 6464994Smckusickcalls. For each existing terminal file, there is a software processing module 6555908Smarccalled a 6655908Smarc.Em "line discipline" 6755908Smarcis associated with it. The 6855908Smarc.Em "line discipline" 6955908Smarcessentially glues the low level device driver code with the high 7055908Smarclevel generic interface routines (such as 7155908Smarc.Xr read 2 7220632Smckusickand 7355908Smarc.Xr write 2 ), 7455908Smarcand is responsible for implementing the semantics associated 7555908Smarcwith the device. When a terminal file is first opened by a program, 7655908Smarcthe default 7755908Smarc.Em "line discipline" 7855908Smarccalled the 7955908Smarc.Dv termios 8055908Smarcline discipline is associated with the file. This is the primary 8155908Smarcline discipline that is used in most cases and provides the semantics 8255908Smarcthat users normally associate with a terminal. When the 8355908Smarc.Dv termios 8455908Smarcline discipline is in effect, the terminal file behaves and is 8555908Smarcoperated according to the rules described in 8655908Smarc.Xr termios 4 . 8755908SmarcPlease refer to that man page for a full description of the terminal 8855908Smarcsemantics. 8955908SmarcThe operations described here 9055908Smarcgenerally represent features common 9155908Smarcacross all 9264994Smckusick.Em "line disciplines" , 9364994Smckusickhowever some of these calls may not 9455908Smarcmake sense in conjunction with a line discipline other than 9555908Smarc.Dv termios , 9655908Smarcand some may not be supported by the underlying 9764994Smckusickhardware (or lack thereof, as in the case of ptys). 9855908Smarc.Ss Terminal File Operations 9955908SmarcAll of the following operations are invoked using the 10055908Smarc.Xr ioctl 2 10155908Smarcsystem call. Refer to that man page for a description of 10255908Smarcthe 10355908Smarc.Em request 10455908Smarcand 10555908Smarc.Em argp 10664994Smckusickparameters. 10755909ScaelIn addition to the ioctl 10855909Scael.Em requests 10955908Smarcdefined here, the specific line discipline 11055909Scaelin effect will define other 11155908Smarc.Em requests 11255908Smarcspecific to it (actually 11355908Smarc.Xr termios 4 11455909Scaeldefines them as function calls, not ioctl 11564994Smckusick.Em requests . ) 11655908SmarcThe following section lists the available ioctl requests. The 11764994Smckusickname of the request, a description of its purpose, and the typed 11855908Smarc.Em argp 11955908Smarcparameter (if any) 12064994Smckusickare listed. For example, the first entry says 12155909Scael.Pp 12255909Scael.D1 Em "TIOCSETD int *ldisc" 12355909Scael.Pp 12455908Smarcand would be called on the terminal associated with 12564994Smckusickfile descriptor zero by the following code fragment: 12655908Smarc.Bd -literal 12755908Smarc int ldisc; 12855908Smarc 12955908Smarc ldisc = TTYDISC; 13055908Smarc ioctl(0, TIOCSETD, &ldisc); 13155908Smarc.Ed 13255908Smarc.Ss Terminal File Request Descriptions 13355909Scael.Bl -tag -width TIOCGWINSZ 13455909Scael.It Dv TIOCSETD Fa int *ldisc 13555908SmarcChange to the new line discipline pointed to by 13655908Smarc.Fa ldisc . 13755909ScaelThe available line disciplines are listed in 13855909Scael.Pa Aq sys/termios.h 13955908Smarcand currently are: 14055909Scael.Pp 14155909Scael.Bl -tag -width TIOCGWINSZ -compact 14255908Smarc.It TTYDISC 14355908SmarcTermios interactive line discipline. 14455908Smarc.It TABLDISC 14555908SmarcTablet line discipline. 14655908Smarc.It SLIPDISC 14755908SmarcSerial IP line discipline. 14855908Smarc.El 14955909Scael.Pp 15055909Scael.It Dv TIOCGETD Fa int *ldisc 15155908SmarcReturn the current line discipline in the integer pointed to by 15255908Smarc.Fa ldisc . 15355909Scael.It Dv TIOCSBRK Fa void 15455908SmarcSet the terminal hardware into BREAK condition. 15555909Scael.It Dv TIOCCBRK Fa void 15655908SmarcClear the terminal hardware BREAK condition. 15755909Scael.It Dv TIOCSDTR Fa void 15855908SmarcAssert data terminal ready (DTR). 15955909Scael.It Dv TIOCCDTR Fa void 16055908SmarcClear data terminal ready (DTR). 16155909Scael.It Dv TIOCGPGRP Fa int *tpgrp 16255908SmarcReturn the current process group the terminal is associated 16355908Smarcwith in the integer pointed to by 16455908Smarc.Fa tpgrp . 16555908SmarcThis is the underlying call that implements the 16655908Smarc.Xr termios 4 16755908Smarc.Fn tcgetattr 16855908Smarccall. 16955909Scael.It Dv TIOCSPGRP Fa int *tpgrp 17055908SmarcAssociate the terminal with the process group (as an integer) pointed to by 17155908Smarc.Fa tpgrp . 17255908SmarcThis is the underlying call that implements the 17355908Smarc.Xr termios 4 17455908Smarc.Fn tcsetattr 17555908Smarccall. 17655909Scael.It Dv TIOCGETA Fa struct termios *term 17755908SmarcPlace the current value of the termios state associated with the 17855908Smarcdevice in the termios structure pointed to by 17955908Smarc.Fa term . 18055908SmarcThis is the underlying call that implements the 18155908Smarc.Xr termios 4 18255908Smarc.Fn tcgetattr 18355908Smarccall. 18455909Scael.It Dv TIOCSETA Fa struct termios *term 185*66970SbosticSet the termios state associated with the device immediately. 18655908SmarcThis is the underlying call that implements the 18755908Smarc.Xr termios 4 18855908Smarc.Fn tcsetattr 18955909Scaelcall with the 19055908Smarc.Dv TCSANOW 19155908Smarcoption. 19255909Scael.It Dv TIOCSETAW Fa struct termios *term 19355908SmarcFirst wait for any output to complete, then set the termios state 19455908Smarcassociated with the device. 19555908SmarcThis is the underlying call that implements the 19655908Smarc.Xr termios 4 19755908Smarc.Fn tcsetattr 19855909Scaelcall with the 19955908Smarc.Dv TCSADRAIN 20055908Smarcoption. 20155909Scael.It Dv TIOCSETAF Fa struct termios *term 20255908SmarcFirst wait for any output to complete, clear any pending input, 20355908Smarcthen set the termios state associated with the device. 20455908SmarcThis is the underlying call that implements the 20555908Smarc.Xr termios 4 20655908Smarc.Fn tcsetattr 20755909Scaelcall with the 20855908Smarc.Dv TCSAFLUSH 20955908Smarcoption. 21055909Scael.It Dv TIOCOUTQ Fa int *num 21155908SmarcPlace the current number of characters in the output queue in the 21255908Smarcinteger pointed to by 21355908Smarc.Fa num . 21455909Scael.It Dv TIOCSTI Fa char *cp 21564994SmckusickSimulate typed input. Pretend as if the terminal received the 21655908Smarccharacter pointed to by 21755908Smarc.Fa cp . 21855909Scael.It Dv TIOCNOTTY Fa void 219*66970SbosticThis call is obsolete but left for compatibility. In the past, when 22055908Smarca process that didn't have a controlling terminal (see 22155908Smarc.Em The Controlling Terminal 22255908Smarcin 22355908Smarc.Xr termios 4 ) 22455908Smarcfirst opened a terminal device, it acquired that terminal as its 22555908Smarccontrolling terminal. For some programs this was a hazard as they 22655908Smarcdidn't want a controlling terminal in the first place, and this 22755908Smarcprovided a mechanism to disassociate the controlling terminal from 22855908Smarcthe calling process. It 22955908Smarc.Em must 23055908Smarcbe called by opening the file 23155908Smarc.Pa /dev/tty 23255908Smarcand calling 23355908Smarc.Dv TIOCNOTTY 23455908Smarcon that file descriptor. 23555908Smarc.Pp 23655908SmarcThe current system does not allocate a controlling terminal to 23755908Smarca process on an 23855908Smarc.Fn open 23955908Smarccall: there is a specific ioctl called 24055908Smarc.Dv TIOSCTTY 24155908Smarcto make a terminal the controlling 24255908Smarcterminal. 24355908SmarcIn addition, a program can 24455908Smarc.Fn fork 24555908Smarcand call the 24655908Smarc.Fn setsid 24755908Smarcsystem call which will place the process into its own session - which 24855908Smarchas the effect of disassociating it from the controlling terminal. This 249*66970Sbosticis the new and preferred method for programs to lose their controlling 25055908Smarcterminal. 25155909Scael.It Dv TIOCSTOP Fa void 25255908SmarcStop output on the terminal (like typing ^S at the keyboard). 25355909Scael.It Dv TIOCSTART Fa void 25464994SmckusickStart output on the terminal (like typing ^Q at the keyboard). 25555909Scael.It Dv TIOCSCTTY Fa void 25655908SmarcMake the terminal the controlling terminal for the process (the process 25755908Smarcmust not currently have a controlling terminal). 25855909Scael.It Dv TIOCDRAIN Fa void 25955908SmarcWait until all output is drained. 26055909Scael.It Dv TIOCEXCL Fa void 26155908SmarcSet exclusive use on the terminal. No further opens are permitted 26255908Smarcexcept by root. Of course, this means that programs that are run by 26355909Scaelroot (or setuid) will not obey the exclusive setting - which limits 264*66970Sbosticthe usefulness of this feature. 26555909Scael.It Dv TIOCNXCL Fa void 26655908SmarcClear exclusive use of the terminal. Further opens are permitted. 26755909Scael.It Dv TIOCFLUSH Fa int *what 26855908SmarcIf the value of the int pointed to by 26955908Smarc.Fa what 27055908Smarccontains the 27155908Smarc.Dv FREAD 27255908Smarcbit as defined in 27355909Scael.Pa Aq sys/file.h , 27455908Smarcthen all characters in the input queue are cleared. If it contains 27555908Smarcthe 27655908Smarc.Dv FWRITE 27755908Smarcbit, then all characters in the output queue are cleared. If the 27855909Scaelvalue of the integer is zero, then it behaves as if both the 27955909Scael.Dv FREAD 28055909Scaeland 28155909Scael.Dv FWRITE 28255909Scaelbits were set (i.e. clears both queues). 28355909Scael.It Dv TIOCGWINSZ Fa struct winsize *ws 28455908SmarcPut the window size information associated with the terminal in the 28555908Smarc.Va winsize 28655908Smarcstructure pointed to by 28755908Smarc.Fa ws . 28855908SmarcThe window size structure contains the number of rows and columns (and pixels 28964994Smckusickif appropriate) of the devices attached to the terminal. It is set by user software 29055908Smarcand is the means by which most full\&-screen oriented programs determine the 29155908Smarcscreen size. The 29255908Smarc.Va winsize 29355908Smarcstructure is defined in 29455909Scael.Pa Aq sys/ioctl.h . 29555909Scael.It Dv TIOCSWINSZ Fa struct winsize *ws 29655908SmarcSet the window size associated with the terminal to be the value in 29755908Smarcthe 29855908Smarc.Va winsize 29955908Smarcstructure pointed to by 30055908Smarc.Fa ws 30155908Smarc(see above). 30255909Scael.It Dv TIOCCONS Fa int *on 30355908SmarcIf 30455908Smarc.Fa on 30555908Smarcpoints to a non-zero integer, redirect kernel console output (kernel printf's) 30655908Smarcto this terminal. 30755908SmarcIf 30855908Smarc.Fa on 30955908Smarcpoints to a zero integer, redirect kernel console output back to the normal 31055908Smarcconsole. This is usually used on workstations to redirect kernel messages 31155908Smarcto a particular window. 31255909Scael.It Dv TIOCMSET Fa int *state 31355908SmarcThe integer pointed to by 31455908Smarc.Fa state 31555908Smarccontains bits that correspond to modem state. Following is a list 31655908Smarcof defined variables and the modem state they represent: 31755909Scael.Pp 31855909Scael.Bl -tag -width TIOCMXCTS -compact 31955908Smarc.It TIOCM_LE 32055908SmarcLine Enable. 32155908Smarc.It TIOCM_DTR 32255908SmarcData Terminal Ready. 32355908Smarc.It TIOCM_RTS 32455908SmarcRequest To Send. 32555908Smarc.It TIOCM_ST 32655908SmarcSecondary Transmit. 32755908Smarc.It TIOCM_SR 32864994SmckusickSecondary Receive. 32955908Smarc.It TIOCM_CTS 33055908SmarcClear To Send. 33155908Smarc.It TIOCM_CAR 33255908SmarcCarrier Detect. 33355908Smarc.It TIOCM_CD 33455908SmarcCarier Detect (synonym). 33555908Smarc.It TIOCM_RNG 33655908SmarcRing Indication. 33755908Smarc.It TIOCM_RI 33855908SmarcRing Indication (synonym). 33955908Smarc.It TIOCM_DSR 34055908SmarcData Set Ready. 34155908Smarc.El 34255909Scael.Pp 34355908SmarcThis call sets the terminal modem state to that represented by 34455908Smarc.Fa state . 34555908SmarcNot all terminals may support this. 34655909Scael.It Dv TIOCMGET Fa int *state 34755908SmarcReturn the current state of the terminal modem lines as represented 34855908Smarcabove in the integer pointed to by 34955908Smarc.Fa state . 35055909Scael.It Dv TIOCMBIS Fa int *state 35155908SmarcThe bits in the integer pointed to by 35255908Smarc.Fa state 35355908Smarcrepresent modem state as described above, however the state is OR-ed 35455908Smarcin with the current state. 35555909Scael.It Dv TIOCMBIC Fa int *state 35655908SmarcThe bits in the integer pointed to by 35755908Smarc.Fa state 35855908Smarcrepresent modem state as described above, however each bit which is on 35955908Smarcin 36055908Smarc.Fa state 36155908Smarcis cleared in the terminal. 36255908Smarc.El 36355908Smarc.Sh SEE ALSO 36455908Smarc.Xr getty 8 , 36555908Smarc.Xr ioctl 2 , 36655908Smarc.Xr pty 4 , 36755908Smarc.Xr stty 1 , 36855908Smarc.Xr termios 4 369