xref: /freebsd/share/man/man4/tty.4 (revision ee12faa062c04a49bf6fe4e6867bad8606e2413f)
1.\" Copyright (c) 1991, 1992, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)tty.4	8.3 (Berkeley) 4/19/94
29.\"
30.Dd April 3, 2022
31.Dt TTY 4
32.Os
33.Sh NAME
34.Nm tty
35.Nd general terminal interface
36.Sh SYNOPSIS
37.In sys/ioctl.h
38.Sh DESCRIPTION
39This section describes the interface to the terminal drivers
40in the system.
41.Ss Terminal Special Files
42Each hardware terminal port on the system usually has a terminal special device
43file associated with it in the directory ``/dev/'' (for
44example, ``/dev/tty03'').
45When a user logs into
46the system on one of these hardware terminal ports, the system has already
47opened the associated device and prepared the line for normal interactive
48use (see
49.Xr getty 8 . )
50There is also a special case of a terminal file that connects not to
51a hardware terminal port, but to another program on the other side.
52These special terminal devices are called
53.Em ptys
54and provide the mechanism necessary to give users the same interface to the
55system when logging in over a network (using
56.Xr telnet 1
57for example).
58Even in these cases the details of how the terminal
59file was opened and set up is already handled by special software
60in the system.
61Thus, users do not normally need to worry about the details of
62how these lines are opened or used.
63Also, these lines are often used
64for dialing out of a system (through an out-calling modem), but again
65the system provides programs that hide the details of accessing
66these terminal special files (see
67.Xr tip 1 ) .
68.Pp
69When an interactive user logs in, the system prepares the line to
70behave in a certain way (called a
71.Em "line discipline" ) ,
72the particular details of which is described in
73.Xr stty 1
74at the command level, and in
75.Xr termios 4
76at the programming level.
77A user may be concerned with changing
78settings associated with his particular login terminal and should refer
79to the preceding man pages for the common cases.
80The remainder of this man page is concerned
81with describing details of using and controlling terminal devices
82at a low level, such as that possibly required by a program wishing
83to provide features similar to those provided by the system.
84.Ss Terminal File Operations
85All of the following operations are invoked using the
86.Xr ioctl 2
87system call.
88Refer to that man page for a description of the
89.Em request
90and
91.Em argp
92parameters.
93In addition to the ioctl
94.Em requests
95defined here, the specific line discipline
96in effect will define other
97.Em requests
98specific to it (actually
99.Xr termios 4
100defines them as function calls, not ioctl
101.Em requests . )
102The following section lists the available ioctl requests.
103The name of the request, a description of its purpose, and the typed
104.Em argp
105parameter (if any)
106are listed.
107For example, the first entry says
108.Pp
109.D1 Em "TIOCSPGRP int *tpgrp"
110.Pp
111and would be called on the terminal associated with
112file descriptor zero by the following code fragment:
113.Bd -literal
114	int pgrp;
115
116	pgrp = getpgrp();
117	ioctl(0, TIOCSPGRP, &pgrp);
118.Ed
119.Ss Terminal File Request Descriptions
120.Bl -tag -width TIOCGWINSZ
121.It Dv TIOCSETD Fa int *ldisc
122This call is obsolete but left for compatibility.
123Before
124.Fx 8.0 ,
125it would change to the new line discipline pointed to by
126.Fa ldisc .
127.It Dv TIOCGETD Fa int *ldisc
128Return the current line discipline in the integer pointed to by
129.Fa ldisc .
130.It Dv TIOCSBRK Fa void
131Set the terminal hardware into BREAK condition.
132.It Dv TIOCCBRK Fa void
133Clear the terminal hardware BREAK condition.
134.It Dv TIOCSDTR Fa void
135Assert data terminal ready (DTR).
136.It Dv TIOCCDTR Fa void
137Clear data terminal ready (DTR).
138.It Dv TIOCGPGRP Fa int *tpgrp
139Return the current process group with which the terminal is associated
140in the integer pointed to by
141.Fa tpgrp .
142This is the underlying call that implements the
143.Xr termios 4
144.Fn tcgetattr
145call.
146.It Dv TIOCSPGRP Fa int *tpgrp
147Associate the terminal with the process group (as an integer) pointed to by
148.Fa tpgrp .
149This is the underlying call that implements the
150.Xr termios 4
151.Fn tcsetattr
152call.
153.It Dv TIOCGETA Fa struct termios *term
154Place the current value of the termios state associated with the
155device in the termios structure pointed to by
156.Fa term .
157This is the underlying call that implements the
158.Xr termios 4
159.Fn tcgetattr
160call.
161.It Dv TIOCSETA Fa struct termios *term
162Set the termios state associated with the device immediately.
163This is the underlying call that implements the
164.Xr termios 4
165.Fn tcsetattr
166call with the
167.Dv TCSANOW
168option.
169.It Dv TIOCSETAW Fa struct termios *term
170First wait for any output to complete, then set the termios state
171associated with the device.
172This is the underlying call that implements the
173.Xr termios 4
174.Fn tcsetattr
175call with the
176.Dv TCSADRAIN
177option.
178.It Dv TIOCSETAF Fa struct termios *term
179First wait for any output to complete, clear any pending input,
180then set the termios state associated with the device.
181This is the underlying call that implements the
182.Xr termios 4
183.Fn tcsetattr
184call with the
185.Dv TCSAFLUSH
186option.
187.It Dv TIOCOUTQ Fa int *num
188Place the current number of characters in the output queue in the
189integer pointed to by
190.Fa num .
191.It Dv TIOCSTI Fa char *cp
192Simulate typed input.
193Pretend as if the terminal received the character pointed to by
194.Fa cp .
195.It Dv TIOCNOTTY Fa void
196In the past, when a process that did not have a controlling terminal (see
197.Em The Controlling Terminal
198in
199.Xr termios 4 )
200first opened a terminal device, it acquired that terminal as its
201controlling terminal.
202For some programs this was a hazard as they
203did not want a controlling terminal in the first place, and this
204provides a mechanism to disassociate the controlling terminal from
205the calling process.
206It
207.Em must
208be called by opening the file
209.Pa /dev/tty
210and calling
211.Dv TIOCNOTTY
212on that file descriptor.
213.Pp
214The current system does not allocate a controlling terminal to
215a process on an
216.Fn open
217call: there is a specific ioctl called
218.Dv TIOCSCTTY
219to make a terminal the controlling
220terminal.
221In addition, a program can
222.Fn fork
223and call the
224.Fn setsid
225system call which will place the process into its own session - which
226has the effect of disassociating it from the controlling terminal.
227This is the new and preferred method for programs to lose their controlling
228terminal.
229.Pp
230However, environmental restrictions may prohibit the process from being able to
231.Fn fork
232and call the
233.Fn setsid
234system call to disassociate it from the controlling terminal.
235In this case, it must use
236.Dv TIOCNOTTY .
237.It Dv TIOCSTOP Fa void
238Stop output on the terminal (like typing ^S at the keyboard).
239.It Dv TIOCSTART Fa void
240Start output on the terminal (like typing ^Q at the keyboard).
241.It Dv TIOCSCTTY Fa void
242Make the terminal the controlling terminal for the process (the process
243must not currently have a controlling terminal).
244.It Dv TIOCDRAIN Fa void
245Wait until all output is drained, or until the drain wait timeout expires.
246.It Dv TIOCGDRAINWAIT Fa int *timeout
247Return the current drain wait timeout in seconds.
248.It Dv TIOCSDRAINWAIT Fa int *timeout
249Set the drain wait timeout in seconds.
250A value of zero disables timeouts.
251The default drain wait timeout is controlled by the tunable
252.Xr sysctl 8
253OID
254.Va kern.tty_drainwait .
255.It Dv TIOCEXCL Fa void
256Set exclusive use on the terminal.
257No further opens are permitted except by root.
258Of course, this means that programs that are run by
259root (or setuid) will not obey the exclusive setting - which limits
260the usefulness of this feature.
261.It Dv TIOCNXCL Fa void
262Clear exclusive use of the terminal.
263Further opens are permitted.
264.It Dv TIOCFLUSH Fa int *what
265If the value of the int pointed to by
266.Fa what
267contains the
268.Dv FREAD
269bit as defined in
270.In sys/file.h ,
271then all characters in the input queue are cleared.
272If it contains the
273.Dv FWRITE
274bit, then all characters in the output queue are cleared.
275If the value of the integer is zero, then it behaves as if both the
276.Dv FREAD
277and
278.Dv FWRITE
279bits were set (i.e., clears both queues).
280.It Dv TIOCGWINSZ Fa struct winsize *ws
281Put the window size information associated with the terminal in the
282.Va winsize
283structure pointed to by
284.Fa ws .
285The window size structure contains the number of rows and columns (and pixels
286if appropriate) of the devices attached to the terminal.
287It is set by user software
288and is the means by which most full\&-screen oriented programs determine the
289screen size.
290The
291.Va winsize
292structure is defined in
293.In sys/ioctl.h .
294.It Dv TIOCSWINSZ Fa struct winsize *ws
295Set the window size associated with the terminal to be the value in
296the
297.Va winsize
298structure pointed to by
299.Fa ws
300(see above).
301.It Dv TIOCCONS Fa int *on
302If
303.Fa on
304points to a non-zero integer, redirect kernel console output (kernel printf's)
305to this terminal.
306If
307.Fa on
308points to a zero integer, redirect kernel console output back to the normal
309console.
310This is usually used on workstations to redirect kernel messages
311to a particular window.
312.It Dv TIOCMSET Fa int *state
313The integer pointed to by
314.Fa state
315contains bits that correspond to modem state.
316Following is a list of defined variables and the modem state they represent:
317.Pp
318.Bl -tag -width TIOCMXCTS -compact
319.It TIOCM_LE
320Line Enable.
321.It TIOCM_DTR
322Data Terminal Ready.
323.It TIOCM_RTS
324Request To Send.
325.It TIOCM_ST
326Secondary Transmit.
327.It TIOCM_SR
328Secondary Receive.
329.It TIOCM_CTS
330Clear To Send.
331.It TIOCM_CAR
332Carrier Detect.
333.It TIOCM_CD
334Carrier Detect (synonym).
335.It TIOCM_RNG
336Ring Indication.
337.It TIOCM_RI
338Ring Indication (synonym).
339.It TIOCM_DSR
340Data Set Ready.
341.El
342.Pp
343This call sets the terminal modem state to that represented by
344.Fa state .
345Not all terminals may support this.
346.It Dv TIOCMGET Fa int *state
347Return the current state of the terminal modem lines as represented
348above in the integer pointed to by
349.Fa state .
350.It Dv TIOCMBIS Fa int *state
351The bits in the integer pointed to by
352.Fa state
353represent modem state as described above, however the state is OR-ed
354in with the current state.
355.It Dv TIOCMBIC Fa int *state
356The bits in the integer pointed to by
357.Fa state
358represent modem state as described above, however each bit which is on
359in
360.Fa state
361is cleared in the terminal.
362.El
363.Sh IMPLEMENTATION NOTES
364The total number of input and output bytes
365through all terminal devices
366are available via the
367.Va kern.tty_nin
368and
369.Va kern.tty_nout
370read-only
371.Xr sysctl 8
372variables.
373.Sh SEE ALSO
374.Xr stty 1 ,
375.Xr ioctl 2 ,
376.Xr ng_tty 4 ,
377.Xr pty 4 ,
378.Xr termios 4 ,
379.Xr getty 8
380.Sh HISTORY
381A console typewriter device
382.Pa /dev/tty
383and asynchronous communication interfaces
384.Pa /dev/tty[0-5]
385first appeared in
386.At v1 .
387