Commit | Line | Data |
---|---|---|
5ebe7d4b KB |
1 | .\" Copyright (c) 1991, 1992, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
02d430a1 | 3 | .\" |
fbb737c3 | 4 | .\" %sccs.include.redist.roff% |
0824da60 | 5 | .\" |
5ebe7d4b | 6 | .\" @(#)tty.4 8.1 (Berkeley) %G% |
02d430a1 | 7 | .\" |
ae37da53 | 8 | .Dd August 14, 1992 |
fbb737c3 MT |
9 | .Dt TTY 4 |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm tty | |
13 | .Nd general terminal interface | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <sys/ioctl.h> | |
16 | .Sh DESCRIPTION | |
17 | This section describes the interface to the terminal drivers | |
18 | in the system. | |
19 | .Ss Terminal Special Files | |
20 | Each hardware terminal port on the system usually has a terminal special device | |
21 | file associated with it in the directory ``/dev/'' (for | |
22 | example, ``/dev/tty03''). | |
23 | When a user logs into | |
24 | the system on one of these hardware terminal ports, the system has already | |
25 | opened the associated device and prepared the line for normal interactive | |
26 | use (see | |
27 | .Xr getty 8 .) | |
28 | There is also a special case of a terminal file that connects not to | |
29 | a hardware terminal port, but to another program on the other side. | |
30 | These special terminal devices are called | |
31 | .Em ptys | |
32 | and provide the mechanism necessary to give users the same interface to the | |
33 | system when logging in over a network (using | |
34 | .Xr rlogin 1 , | |
bbce0892 | 35 | or |
fbb737c3 MT |
36 | .Xr telnet 1 |
37 | for example.) Even in these cases the details of how the terminal | |
38 | file was opened and set up is already handled by special software | |
39 | in the system. | |
40 | Thus, users do not normally need to worry about the details of | |
41 | how these lines are opened or used. Also, these lines are often used | |
42 | for dialing out of a system (through an out-calling modem), but again | |
43 | the system provides programs that hide the details of accessing | |
44 | these terminal special files (see | |
45 | .Xr tip 2 .) | |
46 | .Pp | |
47 | When an interactive user logs in, the system prepares the line to | |
48 | behave in a certain way (called a | |
49 | .Em "line discipline" ), | |
50 | the particular details of which is described in | |
51 | .Xr stty 1 | |
52 | at the command level, and in | |
53 | .Xr termios 4 | |
54 | at the programming level. A user may be concerned with changing | |
55 | settings associated with his particular login terminal and should refer | |
ae37da53 | 56 | to the preceding man pages for the common cases. The remainder of |
fbb737c3 MT |
57 | this man page is concerned |
58 | with describing details of using and controlling terminal devices | |
59 | at a low level, such as that possibly required by a program wishing | |
60 | to provide features similar to those provided by the system. | |
61 | .Ss Line disciplines | |
62 | A terminal file is used like any other file in the system in that | |
63 | it can be opened, read, and written to using standard system | |
64 | calls. For each existing terminal file, a software processing module | |
65 | called a | |
66 | .Em "line discipline" | |
67 | is associated with it. The | |
68 | .Em "line discipline" | |
69 | essentially glues the low level device driver code with the high | |
70 | level generic interface routines (such as | |
71 | .Xr read 2 | |
02d430a1 | 72 | and |
fbb737c3 MT |
73 | .Xr write 2 ), |
74 | and is responsible for implementing the semantics associated | |
75 | with the device. When a terminal file is first opened by a program, | |
76 | the default | |
77 | .Em "line discipline" | |
78 | called the | |
79 | .Dv termios | |
80 | line discipline is associated with the file. This is the primary | |
81 | line discipline that is used in most cases and provides the semantics | |
82 | that users normally associate with a terminal. When the | |
83 | .Dv termios | |
84 | line discipline is in effect, the terminal file behaves and is | |
85 | operated according to the rules described in | |
86 | .Xr termios 4 . | |
87 | Please refer to that man page for a full description of the terminal | |
88 | semantics. | |
89 | The operations described here | |
90 | generally represent features common | |
91 | across all | |
ae37da53 | 92 | .Em "line disciplines" |
fbb737c3 MT |
93 | however, some of these calls may not |
94 | make sense in conjunction with a line discipline other than | |
95 | .Dv termios , | |
96 | and some may not be supported by the underlying | |
97 | hardware or (lack thereof, as in the case of ptys). | |
98 | .Ss Terminal File Operations | |
99 | All of the following operations are invoked using the | |
100 | .Xr ioctl 2 | |
101 | system call. Refer to that man page for a description of | |
102 | the | |
103 | .Em request | |
104 | and | |
105 | .Em argp | |
106 | parameter. | |
ae37da53 CL |
107 | In addition to the ioctl |
108 | .Em requests | |
fbb737c3 | 109 | defined here, the specific line discipline |
ae37da53 | 110 | in effect will define other |
fbb737c3 MT |
111 | .Em requests |
112 | specific to it (actually | |
113 | .Xr termios 4 | |
ae37da53 | 114 | defines them as function calls, not ioctl |
fbb737c3 MT |
115 | .Em requests .) |
116 | The following section lists the available ioctl requests. The | |
117 | name of the request and the typed | |
118 | .Em argp | |
119 | parameter (if any) | |
120 | is listed along with a description of its | |
121 | purpose. For example, the first entry says | |
ae37da53 CL |
122 | .Pp |
123 | .D1 Em "TIOCSETD int *ldisc" | |
124 | .Pp | |
fbb737c3 MT |
125 | and would be called on the terminal associated with |
126 | file discriptor zero by the following code fragment: | |
127 | .Bd -literal | |
128 | int ldisc; | |
129 | ||
130 | ldisc = TTYDISC; | |
131 | ioctl(0, TIOCSETD, &ldisc); | |
132 | .Ed | |
133 | .Ss Terminal File Request Descriptions | |
ae37da53 CL |
134 | .Bl -tag -width TIOCGWINSZ |
135 | .It Dv TIOCSETD Fa int *ldisc | |
fbb737c3 MT |
136 | Change to the new line discipline pointed to by |
137 | .Fa ldisc . | |
ae37da53 CL |
138 | The available line disciplines are listed in |
139 | .Pa Aq sys/termios.h | |
fbb737c3 | 140 | and currently are: |
ae37da53 CL |
141 | .Pp |
142 | .Bl -tag -width TIOCGWINSZ -compact | |
fbb737c3 MT |
143 | .It TTYDISC |
144 | Termios interactive line discipline. | |
145 | .It TABLDISC | |
146 | Tablet line discipline. | |
147 | .It SLIPDISC | |
148 | Serial IP line discipline. | |
149 | .El | |
ae37da53 CL |
150 | .Pp |
151 | .It Dv TIOCGETD Fa int *ldisc | |
fbb737c3 MT |
152 | Return the current line discipline in the integer pointed to by |
153 | .Fa ldisc . | |
ae37da53 | 154 | .It Dv TIOCSBRK Fa void |
fbb737c3 | 155 | Set the terminal hardware into BREAK condition. |
ae37da53 | 156 | .It Dv TIOCCBRK Fa void |
fbb737c3 | 157 | Clear the terminal hardware BREAK condition. |
ae37da53 | 158 | .It Dv TIOCSDTR Fa void |
fbb737c3 | 159 | Assert data terminal ready (DTR). |
ae37da53 | 160 | .It Dv TIOCCDTR Fa void |
fbb737c3 | 161 | Clear data terminal ready (DTR). |
ae37da53 | 162 | .It Dv TIOCGPGRP Fa int *tpgrp |
fbb737c3 MT |
163 | Return the current process group the terminal is associated |
164 | with in the integer pointed to by | |
165 | .Fa tpgrp . | |
166 | This is the underlying call that implements the | |
167 | .Xr termios 4 | |
168 | .Fn tcgetattr | |
169 | call. | |
ae37da53 | 170 | .It Dv TIOCSPGRP Fa int *tpgrp |
fbb737c3 MT |
171 | Associate the terminal with the process group (as an integer) pointed to by |
172 | .Fa tpgrp . | |
173 | This is the underlying call that implements the | |
174 | .Xr termios 4 | |
175 | .Fn tcsetattr | |
176 | call. | |
ae37da53 | 177 | .It Dv TIOCGETA Fa struct termios *term |
fbb737c3 MT |
178 | Place the current value of the termios state associated with the |
179 | device in the termios structure pointed to by | |
180 | .Fa term . | |
181 | This is the underlying call that implements the | |
182 | .Xr termios 4 | |
183 | .Fn tcgetattr | |
184 | call. | |
ae37da53 | 185 | .It Dv TIOCSETA Fa struct termios *term |
fbb737c3 MT |
186 | Set the termios state associated with the device immediatly. |
187 | This is the underlying call that implements the | |
188 | .Xr termios 4 | |
189 | .Fn tcsetattr | |
ae37da53 | 190 | call with the |
fbb737c3 MT |
191 | .Dv TCSANOW |
192 | option. | |
ae37da53 | 193 | .It Dv TIOCSETAW Fa struct termios *term |
fbb737c3 MT |
194 | First wait for any output to complete, then set the termios state |
195 | associated with the device. | |
196 | This is the underlying call that implements the | |
197 | .Xr termios 4 | |
198 | .Fn tcsetattr | |
ae37da53 | 199 | call with the |
fbb737c3 MT |
200 | .Dv TCSADRAIN |
201 | option. | |
ae37da53 | 202 | .It Dv TIOCSETAF Fa struct termios *term |
fbb737c3 MT |
203 | First wait for any output to complete, clear any pending input, |
204 | then set the termios state associated with the device. | |
205 | This is the underlying call that implements the | |
206 | .Xr termios 4 | |
207 | .Fn tcsetattr | |
ae37da53 | 208 | call with the |
fbb737c3 MT |
209 | .Dv TCSAFLUSH |
210 | option. | |
ae37da53 | 211 | .It Dv TIOCOUTQ Fa int *num |
fbb737c3 MT |
212 | Place the current number of characters in the output queue in the |
213 | integer pointed to by | |
214 | .Fa num . | |
ae37da53 | 215 | .It Dv TIOCSTI Fa char *cp |
fbb737c3 MT |
216 | Simulate typed input. Pretend as if the terminal recieved the |
217 | character pointed to by | |
218 | .Fa cp . | |
ae37da53 | 219 | .It Dv TIOCNOTTY Fa void |
fbb737c3 MT |
220 | This call is obsolete but left for compatability. In the past, when |
221 | a process that didn't have a controlling terminal (see | |
222 | .Em The Controlling Terminal | |
223 | in | |
224 | .Xr termios 4 ) | |
225 | first opened a terminal device, it acquired that terminal as its | |
226 | controlling terminal. For some programs this was a hazard as they | |
227 | didn't want a controlling terminal in the first place, and this | |
228 | provided a mechanism to disassociate the controlling terminal from | |
229 | the calling process. It | |
230 | .Em must | |
231 | be called by opening the file | |
232 | .Pa /dev/tty | |
233 | and calling | |
234 | .Dv TIOCNOTTY | |
235 | on that file descriptor. | |
236 | .Pp | |
237 | The current system does not allocate a controlling terminal to | |
238 | a process on an | |
239 | .Fn open | |
240 | call: there is a specific ioctl called | |
241 | .Dv TIOSCTTY | |
242 | to make a terminal the controlling | |
243 | terminal. | |
244 | In addition, a program can | |
245 | .Fn fork | |
246 | and call the | |
247 | .Fn setsid | |
248 | system call which will place the process into its own session - which | |
249 | has the effect of disassociating it from the controlling terminal. This | |
250 | is the new and prefered method for programs to lose their controlling | |
251 | terminal. | |
ae37da53 | 252 | .It Dv TIOCSTOP Fa void |
fbb737c3 | 253 | Stop output on the terminal (like typing ^S at the keyboard). |
ae37da53 CL |
254 | .It Dv TIOCSTART Fa void |
255 | Start output on the terminal (like typing ^Q at the kayboard). | |
256 | .It Dv TIOCSCTTY Fa void | |
fbb737c3 MT |
257 | Make the terminal the controlling terminal for the process (the process |
258 | must not currently have a controlling terminal). | |
ae37da53 | 259 | .It Dv TIOCDRAIN Fa void |
fbb737c3 | 260 | Wait until all output is drained. |
ae37da53 | 261 | .It Dv TIOCEXCL Fa void |
fbb737c3 MT |
262 | Set exclusive use on the terminal. No further opens are permitted |
263 | except by root. Of course, this means that programs that are run by | |
ae37da53 | 264 | root (or setuid) will not obey the exclusive setting - which limits |
fbb737c3 | 265 | the usefullness of this feature. |
ae37da53 | 266 | .It Dv TIOCNXCL Fa void |
fbb737c3 | 267 | Clear exclusive use of the terminal. Further opens are permitted. |
ae37da53 | 268 | .It Dv TIOCFLUSH Fa int *what |
fbb737c3 MT |
269 | If the value of the int pointed to by |
270 | .Fa what | |
271 | contains the | |
272 | .Dv FREAD | |
273 | bit as defined in | |
ae37da53 | 274 | .Pa Aq sys/file.h , |
fbb737c3 MT |
275 | then all characters in the input queue are cleared. If it contains |
276 | the | |
277 | .Dv FWRITE | |
278 | bit, then all characters in the output queue are cleared. If the | |
ae37da53 CL |
279 | value of the integer is zero, then it behaves as if both the |
280 | .Dv FREAD | |
281 | and | |
282 | .Dv FWRITE | |
283 | bits were set (i.e. clears both queues). | |
284 | .It Dv TIOCGWINSZ Fa struct winsize *ws | |
fbb737c3 MT |
285 | Put the window size information associated with the terminal in the |
286 | .Va winsize | |
287 | structure pointed to by | |
288 | .Fa ws . | |
289 | The window size structure contains the number of rows and columns (and pixels | |
290 | if appropiate) of the devices attached to the terminal. It is set by user software | |
291 | and is the means by which most full\&-screen oriented programs determine the | |
292 | screen size. The | |
293 | .Va winsize | |
294 | structure is defined in | |
ae37da53 CL |
295 | .Pa Aq sys/ioctl.h . |
296 | .It Dv TIOCSWINSZ Fa struct winsize *ws | |
fbb737c3 MT |
297 | Set the window size associated with the terminal to be the value in |
298 | the | |
299 | .Va winsize | |
300 | structure pointed to by | |
301 | .Fa ws | |
302 | (see above). | |
ae37da53 | 303 | .It Dv TIOCCONS Fa int *on |
fbb737c3 MT |
304 | If |
305 | .Fa on | |
306 | points to a non-zero integer, redirect kernel console output (kernel printf's) | |
307 | to this terminal. | |
308 | If | |
309 | .Fa on | |
310 | points to a zero integer, redirect kernel console output back to the normal | |
311 | console. This is usually used on workstations to redirect kernel messages | |
312 | to a particular window. | |
ae37da53 | 313 | .It Dv TIOCMSET Fa int *state |
fbb737c3 MT |
314 | The integer pointed to by |
315 | .Fa state | |
316 | contains bits that correspond to modem state. Following is a list | |
317 | of defined variables and the modem state they represent: | |
ae37da53 CL |
318 | .Pp |
319 | .Bl -tag -width TIOCMXCTS -compact | |
fbb737c3 MT |
320 | .It TIOCM_LE |
321 | Line Enable. | |
322 | .It TIOCM_DTR | |
323 | Data Terminal Ready. | |
324 | .It TIOCM_RTS | |
325 | Request To Send. | |
326 | .It TIOCM_ST | |
327 | Secondary Transmit. | |
328 | .It TIOCM_SR | |
329 | Secondary Recieve. | |
330 | .It TIOCM_CTS | |
331 | Clear To Send. | |
332 | .It TIOCM_CAR | |
333 | Carrier Detect. | |
334 | .It TIOCM_CD | |
335 | Carier Detect (synonym). | |
336 | .It TIOCM_RNG | |
337 | Ring Indication. | |
338 | .It TIOCM_RI | |
339 | Ring Indication (synonym). | |
340 | .It TIOCM_DSR | |
341 | Data Set Ready. | |
342 | .El | |
ae37da53 | 343 | .Pp |
fbb737c3 MT |
344 | This call sets the terminal modem state to that represented by |
345 | .Fa state . | |
346 | Not all terminals may support this. | |
ae37da53 | 347 | .It Dv TIOCMGET Fa int *state |
fbb737c3 MT |
348 | Return the current state of the terminal modem lines as represented |
349 | above in the integer pointed to by | |
350 | .Fa state . | |
ae37da53 | 351 | .It Dv TIOCMBIS Fa int *state |
fbb737c3 MT |
352 | The bits in the integer pointed to by |
353 | .Fa state | |
354 | represent modem state as described above, however the state is OR-ed | |
355 | in with the current state. | |
ae37da53 | 356 | .It Dv TIOCMBIC Fa int *state |
fbb737c3 MT |
357 | The bits in the integer pointed to by |
358 | .Fa state | |
359 | represent modem state as described above, however each bit which is on | |
360 | in | |
361 | .Fa state | |
362 | is cleared in the terminal. | |
363 | .El | |
364 | .Sh SEE ALSO | |
365 | .Xr getty 8 , | |
366 | .Xr ioctl 2 , | |
367 | .Xr pty 4 , | |
368 | .Xr stty 1 , | |
369 | .Xr termios 4 |