]>
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, | |
85 | e.g. by loading a new font). | |
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 | ||
104 | When the window size changes, a SIGWINCH signal is sent to the | |
105 | foreground process group. | |
fea681da MK |
106 | .SS "Sending a Break" |
107 | .TP | |
108 | .BI "TCSBRK int " arg | |
109 | Equivalent to | |
110 | .IR "tcsendbreak(fd, arg)" . | |
111 | .br | |
112 | If the terminal is using asynchronous serial data transmission, and | |
113 | .I arg | |
114 | is zero, then send a break (a stream of zero bits) for between | |
c13182ef MK |
115 | 0.25 and 0.5 seconds. |
116 | If the terminal is not using asynchronous | |
fea681da MK |
117 | serial data transmission, then either a break is sent, or the function |
118 | returns without doing anything. | |
119 | When | |
120 | .I arg | |
f59a3f19 | 121 | is non-zero, nobody knows what will happen. |
fea681da | 122 | |
72cedc06 | 123 | (SVr4, UnixWare, Solaris, Linux treat |
fea681da | 124 | .I "tcsendbreak(fd,arg)" |
f59a3f19 | 125 | with non-zero |
fea681da MK |
126 | .I arg |
127 | like | |
128 | .IR "tcdrain(fd)" . | |
129 | SunOS treats | |
130 | .I arg | |
131 | as a multiplier, and sends a stream of bits | |
132 | .I arg | |
133 | times as long as done for zero | |
134 | .IR arg . | |
72cedc06 | 135 | DG/UX and AIX treat |
fea681da | 136 | .I arg |
f59a3f19 | 137 | (when non-zero) as a timeinterval measured in milliseconds. |
fea681da MK |
138 | HP-UX ignores |
139 | .IR arg .) | |
140 | .TP | |
141 | .BI "TCSBRKP int " arg | |
c13182ef MK |
142 | So-called "POSIX version" of TCSBRK. |
143 | It treats non-zero | |
fea681da MK |
144 | .I arg |
145 | as a timeinterval measured in deciseconds, and does nothing | |
146 | when the driver does not support breaks. | |
147 | .TP | |
148 | .BI "TIOCSBRK void" | |
149 | Turn break on, that is, start sending zero bits. | |
150 | .TP | |
151 | .BI "TIOCCBRK void" | |
152 | Turn break off, that is, stop sending zero bits. | |
fea681da MK |
153 | .SS "Software flow control" |
154 | .TP | |
155 | .BI "TCXONC int " arg | |
156 | Equivalent to | |
157 | .IR "tcflow(fd, arg)" . | |
158 | .br | |
159 | See | |
160 | .BR tcflow (3) | |
161 | for the argument values TCOOFF, TCOON, TCIOFF, TCION. | |
fea681da MK |
162 | .SS "Buffer count and flushing" |
163 | .TP | |
164 | .BI "FIONREAD int *" argp | |
165 | Get the number of bytes in the input buffer. | |
166 | .TP | |
167 | .BI "TIOCINQ int *" argp | |
168 | Same as FIONREAD. | |
169 | .TP | |
170 | .BI "TIOCOUTQ int *" argp | |
171 | Get the number of bytes in the output buffer. | |
172 | .TP | |
173 | .BI "TCFLSH int " arg | |
174 | Equivalent to | |
175 | .IR "tcflush(fd, arg)" . | |
176 | .br | |
177 | See | |
178 | .BR tcflush (3) | |
179 | for the argument values TCIFLUSH, TCOFLUSH, TCIOFLUSH. | |
fea681da MK |
180 | .SS "Faking input" |
181 | .TP | |
182 | .BI "TIOCSTI const char *" argp | |
183 | Insert the given byte in the input queue. | |
fea681da MK |
184 | .SS "Redirecting console output" |
185 | .TP | |
186 | .BI "TIOCCONS void" | |
187 | Redirect output that would have gone to | |
188 | .I /dev/console | |
189 | or | |
190 | .I /dev/tty0 | |
c13182ef MK |
191 | to the given tty. |
192 | If that was a pty master, send it to the slave. | |
fea681da MK |
193 | Anybody can do this as long as the output was not redirected yet. |
194 | If it was redirected already EBUSY is returned, | |
195 | but root may stop redirection by using this ioctl with | |
196 | .I fd | |
197 | pointing at | |
198 | .I /dev/console | |
199 | or | |
200 | .IR /dev/tty0 . | |
fea681da MK |
201 | .SS "Controlling tty" |
202 | .TP | |
203 | .BI "TIOCSCTTY int " arg | |
204 | Make the given tty the controlling tty of the current process. | |
205 | The current process must be a session leader and not have a | |
c13182ef MK |
206 | controlling tty already. |
207 | If this tty is already the controlling tty | |
fea681da MK |
208 | of a different session group then the ioctl fails with EPERM, |
209 | unless the caller is root and | |
210 | .I arg | |
211 | equals 1, in which case the tty is stolen, and all processes that had | |
212 | it as controlling tty lose it. | |
213 | .TP | |
214 | .BI TIOCNOTTY void | |
215 | If the given tty was the controlling tty of the current process, | |
c13182ef MK |
216 | give up this controlling tty. |
217 | If the process was session leader, | |
fea681da MK |
218 | then send SIGHUP and SIGCONT to the foreground process group |
219 | and all processes in the current session lose their controlling tty. | |
fea681da MK |
220 | .SS "Process group and session ID" |
221 | .TP | |
222 | .BI "TIOCGPGRP pid_t *" argp | |
223 | When successful, equivalent to | |
224 | .IR "*argp = tcgetpgrp(fd)" . | |
225 | .br | |
9fdfa163 | 226 | Get the process group ID of the foreground process group on this tty. |
fea681da MK |
227 | .TP |
228 | .BI "TIOCSPGRP const pid_t *" argp | |
229 | Equivalent to | |
230 | .IR "tcsetpgrp(fd, *argp)" . | |
231 | .br | |
357cf3fe | 232 | Set the foreground process group ID of this tty. |
fea681da MK |
233 | .TP |
234 | .BI "TIOCGSID pid_t *" argp | |
c13182ef MK |
235 | Get the session ID of the given tty. |
236 | This will fail with ENOTTY | |
237 | in case the tty is not a master pty and not our controlling tty. | |
238 | Strange. | |
fea681da MK |
239 | .SS "Exclusive mode" |
240 | .TP | |
241 | .BI "TIOCEXCL void" | |
242 | Put the tty into exclusive mode. | |
243 | No further | |
244 | .BR open (2) | |
245 | operations on the terminal are permitted. | |
246 | (They will fail with EBUSY, except for root.) | |
247 | .TP | |
248 | .BI "TIOCNXCL void" | |
249 | Disable exclusive mode. | |
fea681da MK |
250 | .SS "Line discipline" |
251 | .TP | |
252 | .BI "TIOCGETD int *" argp | |
253 | Get the line discipline of the tty. | |
254 | .TP | |
255 | .BI "TIOCSETD const int *" argp | |
256 | Set the line discipline of the tty. | |
fea681da MK |
257 | .SS "Pseudo-tty ioctls" |
258 | .TP | |
259 | .BI "TIOCPKT const int *" argp | |
260 | Enable (when | |
261 | .RI * argp | |
f59a3f19 | 262 | is non-zero) or disable packet mode. |
5e8051e6 | 263 | Can be applied to the master side of a pseudo-terminal only (and will return |
c13182ef MK |
264 | ENOTTY otherwise). |
265 | In packet mode, each subsequent | |
fea681da | 266 | .BR read (2) |
f59a3f19 | 267 | will return a packet that either contains a single non-zero control byte, |
c13182ef MK |
268 | or has a single byte containing zero (''\0') followed by data |
269 | written on the slave side of the pty. | |
28d88c17 | 270 | If the first byte is not TIOCPKT_DATA (0), it is an OR of one |
fea681da MK |
271 | or more of the following bits: |
272 | ||
273 | .nf | |
274 | TIOCPKT_FLUSHREAD The read queue for the terminal is flushed. | |
275 | TIOCPKT_FLUSHWRITE The write queue for the terminal is flushed. | |
276 | TIOCPKT_STOP Output to the terminal is stopped. | |
277 | TIOCPKT_START Output to the terminal is restarted. | |
278 | TIOCPKT_DOSTOP t_stopc is `^S' and t_startc is `^Q'. | |
279 | TIOCPKT_NOSTOP the start and stop characters are not `^S/^Q'. | |
280 | .fi | |
281 | ||
282 | While this mode is in use, the presence | |
283 | of control status information to be read | |
284 | from the master side may be detected by a | |
285 | .BR select (2) | |
286 | for exceptional conditions. | |
287 | ||
288 | This mode is used by | |
289 | .BR rlogin (1) | |
290 | and | |
291 | .BR rlogind (8) | |
292 | to implement a remote-echoed, locally `^S/^Q' flow-controlled remote login. | |
293 | ||
294 | The BSD ioctls TIOCSTOP, TIOCSTART, TIOCUCNTL, TIOCREMOTE | |
295 | have not been implemented under Linux. | |
fea681da MK |
296 | .SS "Modem control" |
297 | .TP | |
298 | .BI "TIOCMGET int *" argp | |
299 | get the status of modem bits. | |
300 | .TP | |
301 | .BI "TIOCMSET const int *" argp | |
302 | set the status of modem bits. | |
303 | .TP | |
304 | .BI "TIOCMBIC const int *" argp | |
305 | clear the indicated modem bits. | |
306 | .TP | |
307 | .BI "TIOCMBIS const int *" argp | |
308 | set the indicated modem bits. | |
309 | .LP | |
310 | Bits used by these four ioctls: | |
311 | ||
312 | .nf | |
313 | TIOCM_LE DSR (data set ready/line enable) | |
314 | TIOCM_DTR DTR (data terminal ready) | |
315 | TIOCM_RTS RTS (request to send) | |
316 | TIOCM_ST Secondary TXD (transmit) | |
317 | TIOCM_SR Secondary RXD (receive) | |
318 | TIOCM_CTS CTS (clear to send) | |
319 | TIOCM_CAR DCD (data carrier detect) | |
320 | TIOCM_CD see TIOCM_CAR | |
321 | TIOCM_RNG RNG (ring) | |
322 | TIOCM_RI see TIOCM_RNG | |
323 | TIOCM_DSR DSR (data set ready) | |
324 | .fi | |
fea681da MK |
325 | .SS "Marking a line as local" |
326 | .TP | |
327 | .BI "TIOCGSOFTCAR int *" argp | |
328 | ("Get software carrier flag") | |
329 | Get the status of the CLOCAL flag in the c_cflag field of the | |
330 | termios structure. | |
331 | .TP | |
332 | .BI "TIOCSSOFTCAR const int *" argp | |
333 | ("Set software carrier flag") | |
334 | Set the CLOCAL flag in the termios structure when | |
335 | .RI * argp | |
f59a3f19 | 336 | is non-zero, and clear it otherwise. |
fea681da MK |
337 | .LP |
338 | If the CLOCAL flag for a line is off, the hardware carrier detect (DCD) | |
339 | signal is significant, and an | |
340 | .BR open (2) | |
341 | of the corresponding tty will block until DCD is asserted, | |
342 | unless the O_NONBLOCK flag is given. | |
343 | If CLOCAL is set, the line behaves as if DCD is always asserted. | |
344 | The software carrier flag is usually turned on for local devices, | |
345 | and is off for lines with modems. | |
fea681da MK |
346 | .SS "Linux specific" |
347 | For the TIOCLINUX ioctl, see | |
348 | .BR console_ioctl (4). | |
fea681da MK |
349 | .SS "Kernel debugging" |
350 | .sp | |
351 | .BR "#include <linux/tty.h>" | |
fea681da MK |
352 | .TP |
353 | .BI "TIOCTTYGSTRUCT struct tty_struct *" argp | |
354 | Get the tty_struct corresponding to | |
355 | .IR fd . | |
c13182ef | 356 | .\" |
fea681da MK |
357 | .\" .SS "Serial info" |
358 | .\" .sp | |
359 | .\" .BR "#include <linux/serial.h>" | |
360 | .\" .sp | |
361 | .\" .TP | |
362 | .\" .BI "TIOCGSERIAL struct serial_struct *" argp | |
363 | .\" Get serial info. | |
364 | .\" .TP | |
365 | .\" .BI "TIOCSSERIAL const struct serial_struct *" argp | |
366 | .\" Set serial info. | |
fea681da MK |
367 | .SH "RETURN VALUE" |
368 | The | |
31e9a9ec | 369 | .BR ioctl () |
c13182ef MK |
370 | system call returns 0 on success. |
371 | On error it returns \-1 and sets | |
fea681da MK |
372 | .I errno |
373 | appropriately. | |
fea681da MK |
374 | .SH ERRORS |
375 | .TP | |
376 | .B ENOIOCTLCMD | |
377 | Unknown command. | |
378 | .TP | |
379 | .B EINVAL | |
380 | Invalid command parameter. | |
381 | .TP | |
382 | .B EPERM | |
383 | Insufficient permission. | |
384 | .TP | |
385 | .B ENOTTY | |
386 | Inappropriate | |
387 | .IR fd . | |
388 | .SH EXAMPLE | |
389 | Check the condition of DTR on the serial port. | |
390 | ||
391 | .nf | |
392 | #include <termios.h> | |
393 | #include <fcntl.h> | |
394 | #include <sys/ioctl.h> | |
395 | ||
cf0a9ace | 396 | int |
c13182ef | 397 | main(void) |
cf0a9ace | 398 | { |
fea681da MK |
399 | int fd, serial; |
400 | ||
401 | fd = open("/dev/ttyS0", O_RDONLY); | |
402 | ioctl(fd, TIOCMGET, &serial); | |
403 | if (serial & TIOCM_DTR) | |
404 | puts("TIOCM_DTR is not set"); | |
405 | else | |
406 | puts("TIOCM_DTR is set"); | |
407 | close(fd); | |
408 | } | |
409 | .fi | |
fea681da MK |
410 | .SH "SEE ALSO" |
411 | .BR ioctl (2), | |
412 | .BR termios (3), | |
50c00f7e | 413 | .BR console_ioctl (4), |
88ab292b | 414 | .BR pty (7) |
fea681da MK |
415 | |
416 | .\" FIONBIO const int * | |
417 | .\" FIONCLEX void | |
418 | .\" FIOCLEX void | |
419 | .\" FIOASYNC const int * | |
420 | .\" from serial.c: | |
421 | .\" TIOCSERCONFIG void | |
422 | .\" TIOCSERGWILD int * | |
423 | .\" TIOCSERSWILD const int * | |
424 | .\" TIOCSERGSTRUCT struct async_struct * | |
425 | .\" TIOCSERGETLSR int * | |
426 | .\" TIOCSERGETMULTI struct serial_multiport_struct * | |
427 | .\" TIOCSERSETMULTI const struct serial_multiport_struct * | |
428 | .\" TIOCGSERIAL, TIOCSSERIAL (see above) |