1 .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
2 .\" and Andries Brouwer <aeb@cwi.nl>.
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" Distributed under GPL
8 .TH IOCTL_TTY 2 2020-06-09 "Linux" "Linux Programmer's Manual"
10 ioctl_tty \- ioctls for terminals and serial lines
12 .B "#include <termios.h>"
14 .BI "int ioctl(int " fd ", int " cmd ", ...);"
18 call for terminals and serial ports accepts many possible command arguments.
19 Most require a third argument, of varying type, here called
26 makes for nonportable programs.
27 Use the POSIX interface described in
30 .SS Get and set terminal attributes
32 .BI "TCGETS struct termios *" argp
34 .IR "tcgetattr(fd, argp)" .
36 Get the current serial port settings.
38 .BI "TCSETS const struct termios *" argp
40 .IR "tcsetattr(fd, TCSANOW, argp)" .
42 Set the current serial port settings.
44 .BI "TCSETSW const struct termios *" argp
46 .IR "tcsetattr(fd, TCSADRAIN, argp)" .
48 Allow the output buffer to drain, and
49 set the current serial port settings.
51 .BI "TCSETSF const struct termios *" argp
53 .IR "tcsetattr(fd, TCSAFLUSH, argp)" .
55 Allow the output buffer to drain, discard pending input, and
56 set the current serial port settings.
58 The following four ioctls are just like
63 except that they take a
66 .IR "struct termios\ *" .
68 .BI "TCGETA struct termio *" argp
70 .BI "TCSETA const struct termio *" argp
72 .BI "TCSETAW const struct termio *" argp
74 .BI "TCSETAF const struct termio *" argp
75 .SS Locking the termios structure
78 structure of a terminal can be locked.
81 structure, with nonzero bits or fields indicating a
84 .BI "TIOCGLCKTRMIOS struct termios *" argp
85 Gets the locking status of the
87 structure of the terminal.
89 .BI "TIOCSLCKTRMIOS const struct termios *" argp
90 Sets the locking status of the
92 structure of the terminal.
93 Only a process with the
95 capability can do this.
96 .SS Get and set window size
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,
100 for example, by loading a new font).
102 The following constants and structure are defined in
105 .BI "TIOCGWINSZ struct winsize *" argp
108 .BI "TIOCSWINSZ const struct winsize *" argp
111 The struct used by these ioctls is defined as
116 unsigned short ws_row;
117 unsigned short ws_col;
118 unsigned short ws_xpixel; /* unused */
119 unsigned short ws_ypixel; /* unused */
124 When the window size changes, a
126 signal is sent to the
127 foreground process group.
130 .BI "TCSBRK int " arg
132 .IR "tcsendbreak(fd, arg)" .
134 If the terminal is using asynchronous serial data transmission, and
136 is zero, then send a break (a stream of zero bits) for between
137 0.25 and 0.5 seconds.
138 If the terminal is not using asynchronous
139 serial data transmission, then either a break is sent, or the function
140 returns without doing anything.
143 is nonzero, nobody knows what will happen.
145 (SVr4, UnixWare, Solaris, Linux treat
146 .I "tcsendbreak(fd,arg)"
153 as a multiplier, and sends a stream of bits
155 times as long as done for zero
159 (when nonzero) as a time interval measured in milliseconds.
163 .BI "TCSBRKP int " arg
164 So-called "POSIX version" of
168 as a timeinterval measured in deciseconds, and does nothing
169 when the driver does not support breaks.
172 Turn break on, that is, start sending zero bits.
175 Turn break off, that is, stop sending zero bits.
176 .SS Software flow control
178 .BI "TCXONC int " arg
180 .IR "tcflow(fd, arg)" .
184 for the argument values
189 .SS Buffer count and flushing
191 .BI "FIONREAD int *" argp
192 Get the number of bytes in the input buffer.
194 .BI "TIOCINQ int *" argp
198 .BI "TIOCOUTQ int *" argp
199 Get the number of bytes in the output buffer.
201 .BI "TCFLSH int " arg
203 .IR "tcflush(fd, arg)" .
207 for the argument values
213 .BI "TIOCSTI const char *" argp
214 Insert the given byte in the input queue.
215 .SS Redirecting console output
218 Redirect output that would have gone to
222 to the given terminal.
223 If that was a pseudoterminal master, send it to the slave.
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 a process with the
228 capability may do this.
229 If output was redirected already, then
232 but redirection can be stopped by using this ioctl with
238 .SS Controlling terminal
240 .BI "TIOCSCTTY int " arg
241 Make the given terminal the controlling terminal of the calling process.
242 The calling process must be a session leader and not have a
243 controlling terminal already.
246 should be specified as zero.
248 If this terminal is already the controlling terminal
249 of a different session group, then the ioctl fails with
251 unless the caller has the
255 equals 1, in which case the terminal is stolen, and all processes that had
256 it as controlling terminal lose it.
259 If the given terminal was the controlling terminal of the calling process,
260 give up this controlling terminal.
261 If the process was session leader,
266 to the foreground process group
267 and all processes in the current session lose their controlling terminal.
268 .SS Process group and session ID
270 .BI "TIOCGPGRP pid_t *" argp
271 When successful, equivalent to
272 .IR "*argp = tcgetpgrp(fd)" .
274 Get the process group ID of the foreground process group on this terminal.
276 .BI "TIOCSPGRP const pid_t *" argp
278 .IR "tcsetpgrp(fd, *argp)" .
280 Set the foreground process group ID of this terminal.
282 .BI "TIOCGSID pid_t *" argp
283 Get the session ID of the given terminal.
284 This fails with the error
286 if the terminal is not a master pseudoterminal
287 and not our controlling terminal.
292 Put the terminal into exclusive mode.
295 operations on the terminal are permitted.
298 except for a process with the
302 .BI "TIOCGEXCL int *" argp
304 If the terminal is currently in exclusive mode,
305 place a nonzero value in the location pointed to by
307 otherwise, place zero in
311 Disable exclusive mode.
314 .BI "TIOCGETD int *" argp
315 Get the line discipline of the terminal.
317 .BI "TIOCSETD const int *" argp
318 Set the line discipline of the terminal.
319 .SS Pseudoterminal ioctls
321 .BI "TIOCPKT const int *" argp
324 is nonzero) or disable packet mode.
325 Can be applied to the master side of a pseudoterminal only (and will return
328 In packet mode, each subsequent
330 will return a packet that either contains a single nonzero control byte,
331 or has a single byte containing zero (\(aq\e0\(aq) followed by data
332 written on the slave side of the pseudoterminal.
333 If the first byte is not
335 (0), it is an OR of one
336 or more of the following bits:
339 TIOCPKT_FLUSHREAD The read queue for the terminal is flushed.
340 TIOCPKT_FLUSHWRITE The write queue for the terminal is flushed.
341 TIOCPKT_STOP Output to the terminal is stopped.
342 TIOCPKT_START Output to the terminal is restarted.
343 TIOCPKT_DOSTOP The start and stop characters are \fB^S\fP/\fB^Q\fP.
344 TIOCPKT_NOSTOP The start and stop characters are not \fB^S\fP/\fB^Q\fP.
347 While packet mode is in use, the presence
348 of control status information to be read
349 from the master side may be detected by a
351 for exceptional conditions or a
361 to implement a remote-echoed,
362 locally \fB^S\fP/\fB^Q\fP flow-controlled remote login.
364 .BI "TIOCGPKT const int *" argp
366 Return the current packet mode setting in the integer pointed to by
369 .BI "TIOCSPTLCK int *" argp
372 is nonzero) or remove (if
374 is zero) the lock on the pseudoterminal slave device.
378 .BI "TIOCGPTLCK int *" argp
380 Place the current lock state of the pseudoterminal slave device
381 in the location pointed to by
384 .BI "TIOCGPTPEER int " flags
385 .\" commit 54ebbfb1603415d9953c150535850d30609ef077
387 Given a file descriptor in
389 that refers to a pseudoterminal master,
393 and return a new file descriptor that refers to the peer
394 pseudoterminal slave device.
395 This operation can be performed
396 regardless of whether the pathname of the slave device
397 is accessible through the calling process's mount namespace.
399 Security-conscious programs interacting with namespaces may wish to use this
400 operation rather than
402 with the pathname returned by
404 and similar library functions that have insecure APIs.
405 (For example, confusion can occur in some cases using
407 with a pathname where a devpts filesystem
408 has been mounted in a different mount namespace.)
415 have not been implemented under Linux.
418 .BI "TIOCMGET int *" argp
419 Get the status of modem bits.
421 .BI "TIOCMSET const int *" argp
422 Set the status of modem bits.
424 .BI "TIOCMBIC const int *" argp
425 Clear the indicated modem bits.
427 .BI "TIOCMBIS const int *" argp
428 Set the indicated modem bits.
430 The following bits are used by the above ioctls:
433 TIOCM_LE DSR (data set ready/line enable)
434 TIOCM_DTR DTR (data terminal ready)
435 TIOCM_RTS RTS (request to send)
436 TIOCM_ST Secondary TXD (transmit)
437 TIOCM_SR Secondary RXD (receive)
438 TIOCM_CTS CTS (clear to send)
439 TIOCM_CAR DCD (data carrier detect)
440 TIOCM_CD see TIOCM_CAR
442 TIOCM_RI see TIOCM_RNG
443 TIOCM_DSR DSR (data set ready)
446 .BI "TIOCMIWAIT int " arg
447 Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change.
448 The bits of interest are specified as a bit mask in
450 by ORing together any of the bit values,
456 The caller should use
458 to see which bit has changed.
460 .BI "TIOCGICOUNT struct serial_icounter_struct *" argp
461 Get counts of input serial line interrupts (DCD, RI, DSR, CTS).
462 The counts are written to the
463 .I serial_icounter_struct
464 structure pointed to by
467 Note: both 1->0 and 0->1 transitions are counted, except for
468 RI, where only 0->1 transitions are counted.
469 .SS Marking a line as local
471 .BI "TIOCGSOFTCAR int *" argp
472 ("Get software carrier flag")
473 Get the status of the CLOCAL flag in the c_cflag field of the
477 .BI "TIOCSSOFTCAR const int *" argp
478 ("Set software carrier flag")
479 Set the CLOCAL flag in the
483 is nonzero, and clear it otherwise.
487 flag for a line is off, the hardware carrier detect (DCD)
488 signal is significant, and an
490 of the corresponding terminal will block until DCD is asserted,
496 is set, the line behaves as if DCD is always asserted.
497 The software carrier flag is usually turned on for local devices,
498 and is off for lines with modems.
503 .BR ioctl_console (2).
505 .B "#include <linux/tty.h>"
507 .BI "TIOCTTYGSTRUCT struct tty_struct *" argp
512 This command was removed in Linux 2.5.67.
513 .\" commit b3506a09d15dc5aee6d4bb88d759b157016e1864
514 .\" Author: Andries E. Brouwer <andries.brouwer@cwi.nl>
515 .\" Date: Tue Apr 1 04:42:46 2003 -0800
517 .\" [PATCH] kill TIOCTTYGSTRUCT
519 .\" Only used for (dubious) debugging purposes, and exposes
520 .\" internal kernel state.
523 .\" .BR "#include <linux/serial.h>"
526 .\" .BI "TIOCGSERIAL struct serial_struct *" argp
529 .\" .BI "TIOCSSERIAL const struct serial_struct *" argp
534 system call returns 0 on success.
535 On error, it returns \-1 and sets
541 Invalid command parameter.
551 Insufficient permission.
553 Check the condition of DTR on the serial port.
558 #include <sys/ioctl.h>
565 fd = open("/dev/ttyS0", O_RDONLY);
566 ioctl(fd, TIOCMGET, &serial);
567 if (serial & TIOCM_DTR)
568 puts("TIOCM_DTR is set");
570 puts("TIOCM_DTR is not set");
577 .BR ioctl_console (2),
581 .\" FIONBIO const int *
584 .\" FIOASYNC const int *
586 .\" TIOCSERCONFIG void
587 .\" TIOCSERGWILD int *
588 .\" TIOCSERSWILD const int *
589 .\" TIOCSERGSTRUCT struct async_struct *
590 .\" TIOCSERGETLSR int *
591 .\" TIOCSERGETMULTI struct serial_multiport_struct *
592 .\" TIOCSERSETMULTI const struct serial_multiport_struct *
593 .\" TIOCGSERIAL, TIOCSSERIAL (see above)