]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de> |
2 | .\" and Andries Brouwer <aeb@cwi.nl>. | |
3 | .\" Distributed under GPL. | |
4 | .\" | |
5 | .TH TTY_IOCTL 4 2002-12-29 "Linux" "Linux Programmer's Manual" | |
6 | .SH NAME | |
7 | tty ioctl \- ioctls for terminals and serial lines | |
8 | .SH SYNOPSIS | |
9 | .sp | |
c13182ef | 10 | .BR "#include <termios.h>" |
fea681da | 11 | .sp |
c13182ef | 12 | .BI "int ioctl(int " fd ", int " cmd ", ...);" |
fea681da MK |
13 | .SH DESCRIPTION |
14 | The | |
31e9a9ec | 15 | .BR ioctl () |
fea681da MK |
16 | call for terminals and serial ports accepts many possible command arguments. |
17 | Most require a third argument, of varying type, here called \fIargp\fP | |
18 | or \fIarg\fP. | |
19 | .LP | |
20 | Use of | |
21 | .I ioctl | |
c13182ef MK |
22 | makes for non-portable programs. |
23 | Use the POSIX interface described in | |
fea681da MK |
24 | .BR termios (3) |
25 | whenever possible. | |
fea681da MK |
26 | .SS "Get and Set Terminal Attributes" |
27 | .TP | |
28 | .BI "TCGETS struct termios *" argp | |
29 | Equivalent to | |
30 | .IR "tcgetattr(fd, argp)" . | |
31 | .br | |
32 | Get the current serial port settings. | |
33 | .TP | |
34 | .BI "TCSETS const struct termios *" argp | |
35 | Equivalent to | |
36 | .IR "tcsetattr(fd, TCSANOW, argp)" . | |
37 | .br | |
38 | Set the current serial port settings. | |
39 | .TP | |
40 | .BI "TCSETSW const struct termios *" argp | |
41 | Equivalent to | |
42 | .IR "tcsetattr(fd, TCSADRAIN, argp)" . | |
43 | .br | |
44 | Allow the output buffer to drain, and | |
45 | set the current serial port settings. | |
46 | .TP | |
47 | .BI "TCSETSF const struct termios *" argp | |
48 | Equivalent to | |
49 | .IR "tcsetattr(fd, TCSAFLUSH, argp)" . | |
50 | .br | |
51 | Allow the output buffer to drain, discard pending input, and | |
52 | set the current serial port settings. | |
53 | .LP | |
54 | The following four ioctls are just like TCGETS, TCSETS, TCSETSW, TCSETSF, | |
55 | except that they take a | |
8478ee02 | 56 | .I "struct termio *" |
fea681da | 57 | instead of a |
8478ee02 | 58 | .IR "struct termios *" . |
fea681da MK |
59 | .TP |
60 | .BI "TCGETA struct termio *" argp | |
61 | .TP | |
62 | .BI "TCSETA const struct termio *" argp | |
63 | .TP | |
64 | .BI "TCSETAW const struct termio *" argp | |
65 | .TP | |
66 | .BI "TCSETAF const struct termio *" argp | |
fea681da | 67 | .SS "Locking the termios structure" |
c13182ef MK |
68 | The termios structure of a tty can be locked. |
69 | The lock is itself | |
f59a3f19 | 70 | a termios structure, with non-zero bits or fields indicating a |
fea681da MK |
71 | locked value. |
72 | .TP | |
73 | .BI "TIOCGLCKTRMIOS struct termios *" argp | |
c13182ef | 74 | Gets the locking status of the termios structure of |
fea681da MK |
75 | the terminal. |
76 | .TP | |
77 | .BI "TIOCSLCKTRMIOS const struct termios *" argp | |
c13182ef MK |
78 | Sets the locking status of the termios structure of |
79 | the terminal. | |
80 | Only root can do this. | |
fea681da MK |
81 | .SS "Get and Set Window Size" |
82 | Window sizes are kept in the kernel, but not used by the kernel | |
83 | (except in the case of virtual consoles, where the kernel will | |
84 | update the window size when the size of the virtual console changes, | |
75b94dc3 | 85 | for example, by loading a new font). |
fea681da MK |
86 | .TP |
87 | .BI "TIOCGWINSZ struct winsize *" argp | |
88 | Get window size. | |
89 | .TP | |
90 | .BI "TIOCSWINSZ const struct winsize *" argp | |
91 | Set window size. | |
92 | .LP | |
93 | The struct used by these ioctls is defined as | |
94 | ||
95 | .nf | |
96 | struct winsize { | |
cf0a9ace MK |
97 | unsigned short ws_row; |
98 | unsigned short ws_col; | |
99 | unsigned short ws_xpixel; /* unused */ | |
100 | unsigned short ws_ypixel; /* unused */ | |
fea681da MK |
101 | }; |
102 | .fi | |
103 | ||
8bd58774 MK |
104 | When the window size changes, a |
105 | .B SIGWINCH | |
106 | signal is sent to the | |
fea681da | 107 | foreground process group. |
fea681da MK |
108 | .SS "Sending a Break" |
109 | .TP | |
110 | .BI "TCSBRK int " arg | |
111 | Equivalent to | |
112 | .IR "tcsendbreak(fd, arg)" . | |
113 | .br | |
114 | If the terminal is using asynchronous serial data transmission, and | |
115 | .I arg | |
116 | is zero, then send a break (a stream of zero bits) for between | |
c13182ef MK |
117 | 0.25 and 0.5 seconds. |
118 | If the terminal is not using asynchronous | |
fea681da MK |
119 | serial data transmission, then either a break is sent, or the function |
120 | returns without doing anything. | |
121 | When | |
122 | .I arg | |
f59a3f19 | 123 | is non-zero, nobody knows what will happen. |
fea681da | 124 | |
72cedc06 | 125 | (SVr4, UnixWare, Solaris, Linux treat |
fea681da | 126 | .I "tcsendbreak(fd,arg)" |
f59a3f19 | 127 | with non-zero |
fea681da MK |
128 | .I arg |
129 | like | |
130 | .IR "tcdrain(fd)" . | |
131 | SunOS treats | |
132 | .I arg | |
133 | as a multiplier, and sends a stream of bits | |
134 | .I arg | |
135 | times as long as done for zero | |
136 | .IR arg . | |
72cedc06 | 137 | DG/UX and AIX treat |
fea681da | 138 | .I arg |
f59a3f19 | 139 | (when non-zero) as a timeinterval measured in milliseconds. |
fea681da MK |
140 | HP-UX ignores |
141 | .IR arg .) | |
142 | .TP | |
143 | .BI "TCSBRKP int " arg | |
c13182ef MK |
144 | So-called "POSIX version" of TCSBRK. |
145 | It treats non-zero | |
fea681da MK |
146 | .I arg |
147 | as a timeinterval measured in deciseconds, and does nothing | |
148 | when the driver does not support breaks. | |
149 | .TP | |
150 | .BI "TIOCSBRK void" | |
151 | Turn break on, that is, start sending zero bits. | |
152 | .TP | |
153 | .BI "TIOCCBRK void" | |
154 | Turn break off, that is, stop sending zero bits. | |
fea681da MK |
155 | .SS "Software flow control" |
156 | .TP | |
157 | .BI "TCXONC int " arg | |
158 | Equivalent to | |
159 | .IR "tcflow(fd, arg)" . | |
160 | .br | |
161 | See | |
162 | .BR tcflow (3) | |
163 | for the argument values TCOOFF, TCOON, TCIOFF, TCION. | |
fea681da MK |
164 | .SS "Buffer count and flushing" |
165 | .TP | |
166 | .BI "FIONREAD int *" argp | |
167 | Get the number of bytes in the input buffer. | |
168 | .TP | |
169 | .BI "TIOCINQ int *" argp | |
170 | Same as FIONREAD. | |
171 | .TP | |
172 | .BI "TIOCOUTQ int *" argp | |
173 | Get the number of bytes in the output buffer. | |
174 | .TP | |
175 | .BI "TCFLSH int " arg | |
176 | Equivalent to | |
177 | .IR "tcflush(fd, arg)" . | |
178 | .br | |
179 | See | |
180 | .BR tcflush (3) | |
181 | for the argument values TCIFLUSH, TCOFLUSH, TCIOFLUSH. | |
fea681da MK |
182 | .SS "Faking input" |
183 | .TP | |
184 | .BI "TIOCSTI const char *" argp | |
185 | Insert the given byte in the input queue. | |
fea681da MK |
186 | .SS "Redirecting console output" |
187 | .TP | |
188 | .BI "TIOCCONS void" | |
189 | Redirect output that would have gone to | |
190 | .I /dev/console | |
191 | or | |
192 | .I /dev/tty0 | |
c13182ef MK |
193 | to the given tty. |
194 | If that was a pty master, send it to the slave. | |
fea681da MK |
195 | Anybody can do this as long as the output was not redirected yet. |
196 | If it was redirected already EBUSY is returned, | |
197 | but root may stop redirection by using this ioctl with | |
198 | .I fd | |
199 | pointing at | |
200 | .I /dev/console | |
201 | or | |
202 | .IR /dev/tty0 . | |
fea681da MK |
203 | .SS "Controlling tty" |
204 | .TP | |
205 | .BI "TIOCSCTTY int " arg | |
206 | Make the given tty the controlling tty of the current process. | |
207 | The current process must be a session leader and not have a | |
c13182ef MK |
208 | controlling tty already. |
209 | If this tty is already the controlling tty | |
fea681da MK |
210 | of a different session group then the ioctl fails with EPERM, |
211 | unless the caller is root and | |
212 | .I arg | |
213 | equals 1, in which case the tty is stolen, and all processes that had | |
214 | it as controlling tty lose it. | |
215 | .TP | |
216 | .BI TIOCNOTTY void | |
217 | If the given tty was the controlling tty of the current process, | |
c13182ef MK |
218 | give up this controlling tty. |
219 | If the process was session leader, | |
8bd58774 MK |
220 | then send |
221 | .B SIGHUP | |
222 | and | |
223 | .B SIGCONT | |
224 | to the foreground process group | |
fea681da | 225 | and all processes in the current session lose their controlling tty. |
fea681da MK |
226 | .SS "Process group and session ID" |
227 | .TP | |
228 | .BI "TIOCGPGRP pid_t *" argp | |
229 | When successful, equivalent to | |
230 | .IR "*argp = tcgetpgrp(fd)" . | |
231 | .br | |
9fdfa163 | 232 | Get the process group ID of the foreground process group on this tty. |
fea681da MK |
233 | .TP |
234 | .BI "TIOCSPGRP const pid_t *" argp | |
235 | Equivalent to | |
236 | .IR "tcsetpgrp(fd, *argp)" . | |
237 | .br | |
357cf3fe | 238 | Set the foreground process group ID of this tty. |
fea681da MK |
239 | .TP |
240 | .BI "TIOCGSID pid_t *" argp | |
c13182ef MK |
241 | Get the session ID of the given tty. |
242 | This will fail with ENOTTY | |
243 | in case the tty is not a master pty and not our controlling tty. | |
244 | Strange. | |
fea681da MK |
245 | .SS "Exclusive mode" |
246 | .TP | |
247 | .BI "TIOCEXCL void" | |
248 | Put the tty into exclusive mode. | |
249 | No further | |
250 | .BR open (2) | |
251 | operations on the terminal are permitted. | |
252 | (They will fail with EBUSY, except for root.) | |
253 | .TP | |
254 | .BI "TIOCNXCL void" | |
255 | Disable exclusive mode. | |
fea681da MK |
256 | .SS "Line discipline" |
257 | .TP | |
258 | .BI "TIOCGETD int *" argp | |
259 | Get the line discipline of the tty. | |
260 | .TP | |
261 | .BI "TIOCSETD const int *" argp | |
262 | Set the line discipline of the tty. | |
fea681da MK |
263 | .SS "Pseudo-tty ioctls" |
264 | .TP | |
265 | .BI "TIOCPKT const int *" argp | |
266 | Enable (when | |
267 | .RI * argp | |
f59a3f19 | 268 | is non-zero) or disable packet mode. |
5e8051e6 | 269 | Can be applied to the master side of a pseudo-terminal only (and will return |
c13182ef MK |
270 | ENOTTY otherwise). |
271 | In packet mode, each subsequent | |
fea681da | 272 | .BR read (2) |
f59a3f19 | 273 | will return a packet that either contains a single non-zero control byte, |
c13182ef MK |
274 | or has a single byte containing zero (''\0') followed by data |
275 | written on the slave side of the pty. | |
28d88c17 | 276 | If the first byte is not TIOCPKT_DATA (0), it is an OR of one |
fea681da MK |
277 | or more of the following bits: |
278 | ||
279 | .nf | |
280 | TIOCPKT_FLUSHREAD The read queue for the terminal is flushed. | |
281 | TIOCPKT_FLUSHWRITE The write queue for the terminal is flushed. | |
282 | TIOCPKT_STOP Output to the terminal is stopped. | |
283 | TIOCPKT_START Output to the terminal is restarted. | |
284 | TIOCPKT_DOSTOP t_stopc is `^S' and t_startc is `^Q'. | |
285 | TIOCPKT_NOSTOP the start and stop characters are not `^S/^Q'. | |
286 | .fi | |
287 | ||
288 | While this mode is in use, the presence | |
289 | of control status information to be read | |
290 | from the master side may be detected by a | |
291 | .BR select (2) | |
292 | for exceptional conditions. | |
293 | ||
294 | This mode is used by | |
295 | .BR rlogin (1) | |
296 | and | |
297 | .BR rlogind (8) | |
298 | to implement a remote-echoed, locally `^S/^Q' flow-controlled remote login. | |
299 | ||
300 | The BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE | |
301 | have not been implemented under Linux. | |
fea681da MK |
302 | .SS "Modem control" |
303 | .TP | |
304 | .BI "TIOCMGET int *" argp | |
305 | get the status of modem bits. | |
306 | .TP | |
307 | .BI "TIOCMSET const int *" argp | |
308 | set the status of modem bits. | |
309 | .TP | |
310 | .BI "TIOCMBIC const int *" argp | |
311 | clear the indicated modem bits. | |
312 | .TP | |
313 | .BI "TIOCMBIS const int *" argp | |
314 | set the indicated modem bits. | |
315 | .LP | |
316 | Bits used by these four ioctls: | |
317 | ||
318 | .nf | |
319 | TIOCM_LE DSR (data set ready/line enable) | |
320 | TIOCM_DTR DTR (data terminal ready) | |
321 | TIOCM_RTS RTS (request to send) | |
322 | TIOCM_ST Secondary TXD (transmit) | |
323 | TIOCM_SR Secondary RXD (receive) | |
324 | TIOCM_CTS CTS (clear to send) | |
325 | TIOCM_CAR DCD (data carrier detect) | |
326 | TIOCM_CD see TIOCM_CAR | |
327 | TIOCM_RNG RNG (ring) | |
328 | TIOCM_RI see TIOCM_RNG | |
329 | TIOCM_DSR DSR (data set ready) | |
330 | .fi | |
fea681da MK |
331 | .SS "Marking a line as local" |
332 | .TP | |
333 | .BI "TIOCGSOFTCAR int *" argp | |
334 | ("Get software carrier flag") | |
335 | Get the status of the CLOCAL flag in the c_cflag field of the | |
336 | termios structure. | |
337 | .TP | |
338 | .BI "TIOCSSOFTCAR const int *" argp | |
339 | ("Set software carrier flag") | |
340 | Set the CLOCAL flag in the termios structure when | |
341 | .RI * argp | |
f59a3f19 | 342 | is non-zero, and clear it otherwise. |
fea681da MK |
343 | .LP |
344 | If the CLOCAL flag for a line is off, the hardware carrier detect (DCD) | |
345 | signal is significant, and an | |
346 | .BR open (2) | |
347 | of the corresponding tty will block until DCD is asserted, | |
348 | unless the O_NONBLOCK flag is given. | |
349 | If CLOCAL is set, the line behaves as if DCD is always asserted. | |
350 | The software carrier flag is usually turned on for local devices, | |
351 | and is off for lines with modems. | |
fea681da MK |
352 | .SS "Linux specific" |
353 | For the TIOCLINUX ioctl, see | |
354 | .BR console_ioctl (4). | |
fea681da MK |
355 | .SS "Kernel debugging" |
356 | .sp | |
357 | .BR "#include <linux/tty.h>" | |
fea681da MK |
358 | .TP |
359 | .BI "TIOCTTYGSTRUCT struct tty_struct *" argp | |
360 | Get the tty_struct corresponding to | |
361 | .IR fd . | |
c13182ef | 362 | .\" |
fea681da MK |
363 | .\" .SS "Serial info" |
364 | .\" .sp | |
365 | .\" .BR "#include <linux/serial.h>" | |
366 | .\" .sp | |
367 | .\" .TP | |
368 | .\" .BI "TIOCGSERIAL struct serial_struct *" argp | |
369 | .\" Get serial info. | |
370 | .\" .TP | |
371 | .\" .BI "TIOCSSERIAL const struct serial_struct *" argp | |
372 | .\" Set serial info. | |
fea681da MK |
373 | .SH "RETURN VALUE" |
374 | The | |
31e9a9ec | 375 | .BR ioctl () |
c13182ef MK |
376 | system call returns 0 on success. |
377 | On error it returns \-1 and sets | |
fea681da MK |
378 | .I errno |
379 | appropriately. | |
fea681da MK |
380 | .SH ERRORS |
381 | .TP | |
382 | .B ENOIOCTLCMD | |
383 | Unknown command. | |
384 | .TP | |
385 | .B EINVAL | |
386 | Invalid command parameter. | |
387 | .TP | |
388 | .B EPERM | |
389 | Insufficient permission. | |
390 | .TP | |
391 | .B ENOTTY | |
392 | Inappropriate | |
393 | .IR fd . | |
394 | .SH EXAMPLE | |
395 | Check the condition of DTR on the serial port. | |
396 | ||
397 | .nf | |
398 | #include <termios.h> | |
399 | #include <fcntl.h> | |
400 | #include <sys/ioctl.h> | |
401 | ||
cf0a9ace | 402 | int |
c13182ef | 403 | main(void) |
cf0a9ace | 404 | { |
fea681da MK |
405 | int fd, serial; |
406 | ||
407 | fd = open("/dev/ttyS0", O_RDONLY); | |
408 | ioctl(fd, TIOCMGET, &serial); | |
409 | if (serial & TIOCM_DTR) | |
410 | puts("TIOCM_DTR is not set"); | |
411 | else | |
412 | puts("TIOCM_DTR is set"); | |
413 | close(fd); | |
414 | } | |
415 | .fi | |
fea681da MK |
416 | .SH "SEE ALSO" |
417 | .BR ioctl (2), | |
418 | .BR termios (3), | |
50c00f7e | 419 | .BR console_ioctl (4), |
88ab292b | 420 | .BR pty (7) |
fea681da MK |
421 | |
422 | .\" FIONBIO const int * | |
423 | .\" FIONCLEX void | |
424 | .\" FIOCLEX void | |
425 | .\" FIOASYNC const int * | |
426 | .\" from serial.c: | |
427 | .\" TIOCSERCONFIG void | |
428 | .\" TIOCSERGWILD int * | |
429 | .\" TIOCSERSWILD const int * | |
430 | .\" TIOCSERGSTRUCT struct async_struct * | |
431 | .\" TIOCSERGETLSR int * | |
432 | .\" TIOCSERGETMULTI struct serial_multiport_struct * | |
433 | .\" TIOCSERSETMULTI const struct serial_multiport_struct * | |
434 | .\" TIOCGSERIAL, TIOCSSERIAL (see above) |