]>
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 | .\" |
c323f3a1 | 8 | .TH TTY_IOCTL 4 2013-11-12 "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\ *" . |
52a5ae2b | 67 | .IP |
fea681da | 68 | .BI "TCGETA struct termio *" argp |
52a5ae2b | 69 | .IP |
fea681da | 70 | .BI "TCSETA const struct termio *" argp |
52a5ae2b | 71 | .IP |
fea681da | 72 | .BI "TCSETAW const struct termio *" argp |
52a5ae2b | 73 | .IP |
fea681da | 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. | |
cb476d88 | 93 | Only a process with the |
c0b75059 | 94 | .BR CAP_SYS_ADMIN |
cb476d88 | 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; | |
cb476d88 | 226 | since version 2.6.10, only a process with the |
b5fa38a3 | 227 | .BR CAP_SYS_ADMIN |
cb476d88 | 228 | capability may do this. |
b5fa38a3 | 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 | 243 | controlling terminal already. |
9ab0de3c MK |
244 | For this case, |
245 | .I arg | |
246 | should be specified as zero. | |
c323f3a1 | 247 | |
132249c4 | 248 | If this terminal is already the controlling terminal |
5cc100b9 | 249 | of a different session group, then the ioctl fails with |
097585ed | 250 | .BR EPERM , |
cb476d88 | 251 | unless the caller has the |
c0b75059 | 252 | .BR CAP_SYS_ADMIN |
cb476d88 | 253 | capability and |
fea681da | 254 | .I arg |
132249c4 MK |
255 | equals 1, in which case the terminal is stolen, and all processes that had |
256 | it as controlling terminal lose it. | |
fea681da | 257 | .TP |
17434a0d | 258 | .B "TIOCNOTTY void" |
132249c4 MK |
259 | If the given terminal was the controlling terminal of the calling process, |
260 | give up this controlling terminal. | |
c13182ef | 261 | If the process was session leader, |
8bd58774 MK |
262 | then send |
263 | .B SIGHUP | |
264 | and | |
265 | .B SIGCONT | |
266 | to the foreground process group | |
132249c4 | 267 | and all processes in the current session lose their controlling terminal. |
73d8cece | 268 | .SS Process group and session ID |
fea681da MK |
269 | .TP |
270 | .BI "TIOCGPGRP pid_t *" argp | |
271 | When successful, equivalent to | |
272 | .IR "*argp = tcgetpgrp(fd)" . | |
273 | .br | |
132249c4 | 274 | Get the process group ID of the foreground process group on this terminal. |
fea681da MK |
275 | .TP |
276 | .BI "TIOCSPGRP const pid_t *" argp | |
277 | Equivalent to | |
278 | .IR "tcsetpgrp(fd, *argp)" . | |
279 | .br | |
132249c4 | 280 | Set the foreground process group ID of this terminal. |
fea681da MK |
281 | .TP |
282 | .BI "TIOCGSID pid_t *" argp | |
132249c4 | 283 | Get the session ID of the given terminal. |
097585ed MK |
284 | This will fail with |
285 | .B ENOTTY | |
b218b023 | 286 | in case the terminal is not a master pseudoterminal |
132249c4 | 287 | and not our controlling terminal. |
c13182ef | 288 | Strange. |
73d8cece | 289 | .SS Exclusive mode |
fea681da | 290 | .TP |
0daa9e92 | 291 | .B "TIOCEXCL void" |
132249c4 | 292 | Put the terminal into exclusive mode. |
fea681da MK |
293 | No further |
294 | .BR open (2) | |
295 | operations on the terminal are permitted. | |
097585ed MK |
296 | (They will fail with |
297 | .BR EBUSY , | |
cb476d88 | 298 | except for a process with the |
c0b75059 MK |
299 | .BR CAP_SYS_ADMIN |
300 | capability.) | |
fea681da | 301 | .TP |
0daa9e92 | 302 | .B "TIOCNXCL void" |
fea681da | 303 | Disable exclusive mode. |
73d8cece | 304 | .SS Line discipline |
fea681da MK |
305 | .TP |
306 | .BI "TIOCGETD int *" argp | |
132249c4 | 307 | Get the line discipline of the terminal. |
fea681da MK |
308 | .TP |
309 | .BI "TIOCSETD const int *" argp | |
132249c4 | 310 | Set the line discipline of the terminal. |
73d8cece | 311 | .SS Pseudoterminal ioctls |
fea681da MK |
312 | .TP |
313 | .BI "TIOCPKT const int *" argp | |
314 | Enable (when | |
315 | .RI * argp | |
c7094399 | 316 | is nonzero) or disable packet mode. |
b218b023 | 317 | Can be applied to the master side of a pseudoterminal only (and will return |
097585ed MK |
318 | .B ENOTTY |
319 | otherwise). | |
c13182ef | 320 | In packet mode, each subsequent |
fea681da | 321 | .BR read (2) |
c7094399 | 322 | will return a packet that either contains a single nonzero control byte, |
f81fb444 | 323 | or has a single byte containing zero (\(aq\0\(aq) followed by data |
b218b023 | 324 | written on the slave side of the pseudoterminal. |
097585ed MK |
325 | If the first byte is not |
326 | .B TIOCPKT_DATA | |
327 | (0), it is an OR of one | |
fea681da MK |
328 | or more of the following bits: |
329 | ||
330 | .nf | |
331 | TIOCPKT_FLUSHREAD The read queue for the terminal is flushed. | |
332 | TIOCPKT_FLUSHWRITE The write queue for the terminal is flushed. | |
333 | TIOCPKT_STOP Output to the terminal is stopped. | |
334 | TIOCPKT_START Output to the terminal is restarted. | |
8bb93cd4 MK |
335 | TIOCPKT_DOSTOP The start and stop characters are \fB^S\fP/\fB^Q\fP. |
336 | TIOCPKT_NOSTOP The start and stop characters are not \fB^S\fP/\fB^Q\fP. | |
fea681da MK |
337 | .fi |
338 | ||
339 | While this mode is in use, the presence | |
340 | of control status information to be read | |
341 | from the master side may be detected by a | |
342 | .BR select (2) | |
343 | for exceptional conditions. | |
344 | ||
345 | This mode is used by | |
346 | .BR rlogin (1) | |
347 | and | |
348 | .BR rlogind (8) | |
f81fb444 | 349 | to implement a remote-echoed, |
8bb93cd4 | 350 | locally \fB^S\fP/\fB^Q\fP flow-controlled remote login. |
fea681da | 351 | |
097585ed MK |
352 | The BSD ioctls |
353 | .BR TIOCSTOP , | |
354 | .BR TIOCSTART , | |
355 | .BR TIOCUCNTL , | |
0daa9e92 | 356 | .B TIOCREMOTE |
fea681da | 357 | have not been implemented under Linux. |
73d8cece | 358 | .SS Modem control |
fea681da MK |
359 | .TP |
360 | .BI "TIOCMGET int *" argp | |
2096c4f3 | 361 | Get the status of modem bits. |
fea681da MK |
362 | .TP |
363 | .BI "TIOCMSET const int *" argp | |
2096c4f3 | 364 | Set the status of modem bits. |
fea681da MK |
365 | .TP |
366 | .BI "TIOCMBIC const int *" argp | |
2096c4f3 | 367 | Clear the indicated modem bits. |
fea681da MK |
368 | .TP |
369 | .BI "TIOCMBIS const int *" argp | |
2096c4f3 | 370 | Set the indicated modem bits. |
1dcf15dd FM |
371 | .TP |
372 | .BI "TIOCMIWAIT int " arg | |
373 | Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change. | |
374 | The mask is passed in arg for bits of interest (use |'ed | |
375 | TIOCM_RNG/DSR/CD/CTS for masking). | |
376 | Caller should use | |
377 | .B TIOCGICOUNT | |
378 | to see which one it was. | |
fea681da | 379 | .LP |
d398da7b | 380 | The following bits are used by the above ioctls: |
fea681da MK |
381 | |
382 | .nf | |
383 | TIOCM_LE DSR (data set ready/line enable) | |
384 | TIOCM_DTR DTR (data terminal ready) | |
385 | TIOCM_RTS RTS (request to send) | |
386 | TIOCM_ST Secondary TXD (transmit) | |
387 | TIOCM_SR Secondary RXD (receive) | |
388 | TIOCM_CTS CTS (clear to send) | |
389 | TIOCM_CAR DCD (data carrier detect) | |
390 | TIOCM_CD see TIOCM_CAR | |
391 | TIOCM_RNG RNG (ring) | |
392 | TIOCM_RI see TIOCM_RNG | |
393 | TIOCM_DSR DSR (data set ready) | |
394 | .fi | |
1dcf15dd FM |
395 | .TP |
396 | .BI "TIOCGICOUNT struct serial_icounter_struct *" argp | |
397 | Get counter of input serial line interrupts (DCD, RI, DSR, CTS). | |
398 | Write counters to the user passed | |
399 | .I argp | |
400 | serial_icounter_struct structure. | |
401 | ||
402 | NB: both 1->0 and 0->1 transitions are counted except for | |
403 | RI where only 0->1 is counted. | |
73d8cece | 404 | .SS Marking a line as local |
fea681da MK |
405 | .TP |
406 | .BI "TIOCGSOFTCAR int *" argp | |
407 | ("Get software carrier flag") | |
408 | Get the status of the CLOCAL flag in the c_cflag field of the | |
4961e71d MK |
409 | .I termios |
410 | structure. | |
fea681da MK |
411 | .TP |
412 | .BI "TIOCSSOFTCAR const int *" argp | |
413 | ("Set software carrier flag") | |
4961e71d MK |
414 | Set the CLOCAL flag in the |
415 | .I termios | |
416 | structure when | |
fea681da | 417 | .RI * argp |
c7094399 | 418 | is nonzero, and clear it otherwise. |
fea681da | 419 | .LP |
097585ed MK |
420 | If the |
421 | .B CLOCAL | |
422 | flag for a line is off, the hardware carrier detect (DCD) | |
fea681da MK |
423 | signal is significant, and an |
424 | .BR open (2) | |
132249c4 | 425 | of the corresponding terminal will block until DCD is asserted, |
097585ed MK |
426 | unless the |
427 | .B O_NONBLOCK | |
428 | flag is given. | |
429 | If | |
430 | .B CLOCAL | |
431 | is set, the line behaves as if DCD is always asserted. | |
fea681da MK |
432 | The software carrier flag is usually turned on for local devices, |
433 | and is off for lines with modems. | |
73d8cece | 434 | .SS Linux-specific |
097585ed MK |
435 | For the |
436 | .B TIOCLINUX | |
437 | ioctl, see | |
fea681da | 438 | .BR console_ioctl (4). |
73d8cece | 439 | .SS Kernel debugging |
0daa9e92 | 440 | .B "#include <linux/tty.h>" |
fea681da MK |
441 | .TP |
442 | .BI "TIOCTTYGSTRUCT struct tty_struct *" argp | |
f88233dd MK |
443 | Get the |
444 | .I tty_struct | |
445 | corresponding to | |
fea681da | 446 | .IR fd . |
c13182ef | 447 | .\" |
d282bb24 | 448 | .\" .SS Serial info |
fea681da MK |
449 | .\" .BR "#include <linux/serial.h>" |
450 | .\" .sp | |
451 | .\" .TP | |
452 | .\" .BI "TIOCGSERIAL struct serial_struct *" argp | |
453 | .\" Get serial info. | |
454 | .\" .TP | |
455 | .\" .BI "TIOCSSERIAL const struct serial_struct *" argp | |
456 | .\" Set serial info. | |
47297adb | 457 | .SH RETURN VALUE |
fea681da | 458 | The |
0b80cf56 | 459 | .BR ioctl (2) |
c13182ef | 460 | system call returns 0 on success. |
dec985f9 | 461 | On error, it returns \-1 and sets |
fea681da MK |
462 | .I errno |
463 | appropriately. | |
fea681da MK |
464 | .SH ERRORS |
465 | .TP | |
fea681da MK |
466 | .B EINVAL |
467 | Invalid command parameter. | |
468 | .TP | |
eab64696 MK |
469 | .B ENOIOCTLCMD |
470 | Unknown command. | |
fea681da MK |
471 | .TP |
472 | .B ENOTTY | |
473 | Inappropriate | |
474 | .IR fd . | |
eab64696 MK |
475 | .TP |
476 | .B EPERM | |
477 | Insufficient permission. | |
fea681da MK |
478 | .SH EXAMPLE |
479 | Check the condition of DTR on the serial port. | |
480 | ||
481 | .nf | |
482 | #include <termios.h> | |
483 | #include <fcntl.h> | |
484 | #include <sys/ioctl.h> | |
485 | ||
cf0a9ace | 486 | int |
c13182ef | 487 | main(void) |
cf0a9ace | 488 | { |
fea681da MK |
489 | int fd, serial; |
490 | ||
491 | fd = open("/dev/ttyS0", O_RDONLY); | |
492 | ioctl(fd, TIOCMGET, &serial); | |
493 | if (serial & TIOCM_DTR) | |
fea681da | 494 | puts("TIOCM_DTR is set"); |
e3f16cf7 MK |
495 | else |
496 | puts("TIOCM_DTR is not set"); | |
fea681da MK |
497 | close(fd); |
498 | } | |
499 | .fi | |
47297adb | 500 | .SH SEE ALSO |
fea681da MK |
501 | .BR ioctl (2), |
502 | .BR termios (3), | |
50c00f7e | 503 | .BR console_ioctl (4), |
88ab292b | 504 | .BR pty (7) |
25a46448 | 505 | .\" |
fea681da MK |
506 | .\" FIONBIO const int * |
507 | .\" FIONCLEX void | |
508 | .\" FIOCLEX void | |
509 | .\" FIOASYNC const int * | |
510 | .\" from serial.c: | |
511 | .\" TIOCSERCONFIG void | |
512 | .\" TIOCSERGWILD int * | |
513 | .\" TIOCSERSWILD const int * | |
514 | .\" TIOCSERGSTRUCT struct async_struct * | |
515 | .\" TIOCSERGETLSR int * | |
516 | .\" TIOCSERGETMULTI struct serial_multiport_struct * | |
517 | .\" TIOCSERSETMULTI const struct serial_multiport_struct * | |
518 | .\" TIOCGSERIAL, TIOCSSERIAL (see above) |