xref: /csrg-svn/share/man/man4/tty.4 (revision 66970)
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