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