1 .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
2 .\" and Andries Brouwer <aeb@cwi.nl>.
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
6 .TH IOCTL_TTY 2 2021-08-27 "Linux" "Linux Programmer's Manual"
8 ioctl_tty \- ioctls for terminals and serial lines
11 .RI ( libc ", " \-lc )
14 .B #include <sys/ioctl.h>
15 .BR "#include <asm/termbits.h>" " /* Definition of " "struct termios" ,
16 .BR " struct termios2" ", and"
17 .BR " Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL ,
18 .BR " TC*" { FLUSH , ON , OFF "} and other constants */"
20 .BI "int ioctl(int " fd ", int " cmd ", ...);"
25 call for terminals and serial ports accepts many possible command arguments.
26 Most require a third argument, of varying type, here called
33 makes for nonportable programs.
34 Use the POSIX interface described in
42 is different and incompatible with
46 These ioctl calls require
49 .IR <asm/termbits.h> .
50 .SS Get and set terminal attributes
54 .BI "struct termios\~*" argp
57 .IR "tcgetattr(fd, argp)" .
59 Get the current serial port settings.
63 .BI "const struct termios\~*" argp
66 .IR "tcsetattr(fd, TCSANOW, argp)" .
68 Set the current serial port settings.
72 .BI "const struct termios\~*" argp
75 .IR "tcsetattr(fd, TCSADRAIN, argp)" .
77 Allow the output buffer to drain, and
78 set the current serial port settings.
82 .BI "const struct termios\~*" argp
85 .IR "tcsetattr(fd, TCSAFLUSH, argp)" .
87 Allow the output buffer to drain, discard pending input, and
88 set the current serial port settings.
90 The following four ioctls, added in Linux 2.6.20,
91 .\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6
92 .\" commit 592ee3a5e5e2a981ef2829a0380093006d045661
98 except that they take a
99 .I "struct termios2\~*"
101 .IR "struct termios\~*" .
102 If the structure member
106 then the baud rate is stored in the structure members
111 These ioctls are not supported on all architectures.
115 TCGETS2 \fBstruct termios2 *\fPargp
116 TCSETS2 \fBconst struct termios2 *\fPargp
117 TCSETSW2 \fBconst struct termios2 *\fPargp
118 TCSETSF2 \fBconst struct termios2 *\fPargp
122 The following four ioctls are just like
127 except that they take a
128 .I "struct termio\~*"
130 .IR "struct termios\~*" .
134 TCGETA \fBstruct termio *\fPargp
135 TCSETA \fBconst struct termio *\fPargp
136 TCSETAW \fBconst struct termio *\fPargp
137 TCSETAF \fBconst struct termio *\fPargp
140 .SS Locking the termios structure
143 structure of a terminal can be locked.
146 structure, with nonzero bits or fields indicating a
151 .BI "struct termios\~*" argp
153 Gets the locking status of the
155 structure of the terminal.
159 .BI "const struct termios\~*" argp
161 Sets the locking status of the
163 structure of the terminal.
164 Only a process with the
166 capability can do this.
167 .SS Get and set window size
168 Window sizes are kept in the kernel, but not used by the kernel
169 (except in the case of virtual consoles, where the kernel will
170 update the window size when the size of the virtual console changes,
171 for example, by loading a new font).
175 .BI "struct winsize\~*" argp
181 .BI "const struct winsize\~*" argp
185 The struct used by these ioctls is defined as
190 unsigned short ws_row;
191 unsigned short ws_col;
192 unsigned short ws_xpixel; /* unused */
193 unsigned short ws_ypixel; /* unused */
198 When the window size changes, a
200 signal is sent to the
201 foreground process group.
209 .IR "tcsendbreak(fd, arg)" .
211 If the terminal is using asynchronous serial data transmission, and
213 is zero, then send a break (a stream of zero bits) for between
214 0.25 and 0.5 seconds.
215 If the terminal is not using asynchronous
216 serial data transmission, then either a break is sent, or the function
217 returns without doing anything.
220 is nonzero, nobody knows what will happen.
222 (SVr4, UnixWare, Solaris, and Linux treat
223 .I "tcsendbreak(fd,arg)"
230 as a multiplier, and sends a stream of bits
232 times as long as done for zero
236 (when nonzero) as a time interval measured in milliseconds.
244 So-called "POSIX version" of
248 as a time interval measured in deciseconds, and does nothing
249 when the driver does not support breaks.
255 Turn break on, that is, start sending zero bits.
261 Turn break off, that is, stop sending zero bits.
262 .SS Software flow control
269 .IR "tcflow(fd, arg)" .
273 for the argument values
278 .SS Buffer count and flushing
284 Get the number of bytes in the input buffer.
297 Get the number of bytes in the output buffer.
304 .IR "tcflush(fd, arg)" .
308 for the argument values
316 .BI "const char\~*" argp
318 Insert the given byte in the input queue.
319 .SS Redirecting console output
325 Redirect output that would have gone to
329 to the given terminal.
330 If that was a pseudoterminal master, send it to the slave.
331 In Linux before version 2.6.10,
332 anybody can do this as long as the output was not redirected yet;
333 since version 2.6.10, only a process with the
335 capability may do this.
336 If output was redirected already, then
339 but redirection can be stopped by using this ioctl with
345 .SS Controlling terminal
351 Make the given terminal the controlling terminal of the calling process.
352 The calling process must be a session leader and not have a
353 controlling terminal already.
356 should be specified as zero.
358 If this terminal is already the controlling terminal
359 of a different session group, then the ioctl fails with
361 unless the caller has the
365 equals 1, in which case the terminal is stolen, and all processes that had
366 it as controlling terminal lose it.
372 If the given terminal was the controlling terminal of the calling process,
373 give up this controlling terminal.
374 If the process was session leader,
379 to the foreground process group
380 and all processes in the current session lose their controlling terminal.
381 .SS Process group and session ID
387 When successful, equivalent to
388 .IR "*argp = tcgetpgrp(fd)" .
390 Get the process group ID of the foreground process group on this terminal.
394 .BI "const pid_t\~*" argp
397 .IR "tcsetpgrp(fd, *argp)" .
399 Set the foreground process group ID of this terminal.
405 When successful, equivalent to
406 .IR "*argp = tcgetsid(fd)" .
408 Get the session ID of the given terminal.
409 This fails with the error
411 if the terminal is not a master pseudoterminal
412 and not our controlling terminal.
420 Put the terminal into exclusive mode.
423 operations on the terminal are permitted.
426 except for a process with the
435 If the terminal is currently in exclusive mode,
436 place a nonzero value in the location pointed to by
438 otherwise, place zero in
445 Disable exclusive mode.
452 Get the line discipline of the terminal.
456 .BI "const int\~*" argp
458 Set the line discipline of the terminal.
459 .SS Pseudoterminal ioctls
463 .BI "const int\~*" argp
467 is nonzero) or disable packet mode.
468 Can be applied to the master side of a pseudoterminal only (and will return
471 In packet mode, each subsequent
473 will return a packet that either contains a single nonzero control byte,
474 or has a single byte containing zero (\(aq\e0\(aq) followed by data
475 written on the slave side of the pseudoterminal.
476 If the first byte is not
478 (0), it is an OR of one
479 or more of the following bits:
485 The read queue for the terminal is flushed.
487 TIOCPKT_FLUSHWRITE T{
488 The write queue for the terminal is flushed.
491 Output to the terminal is stopped.
494 Output to the terminal is restarted.
497 The start and stop characters are \fB\(haS\fP/\fB\(haQ\fP.
500 The start and stop characters are not \fB\(haS\fP/\fB\(haQ\fP.
505 While packet mode is in use, the presence
506 of control status information to be read
507 from the master side may be detected by a
509 for exceptional conditions or a
519 to implement a remote-echoed,
520 locally \fB\(haS\fP/\fB\(haQ\fP flow-controlled remote login.
524 .BI "const int\~*" argp
527 Return the current packet mode setting in the integer pointed to by
536 is nonzero) or remove (if
538 is zero) the lock on the pseudoterminal slave device.
547 Place the current lock state of the pseudoterminal slave device
548 in the location pointed to by
555 .\" commit 54ebbfb1603415d9953c150535850d30609ef077
557 Given a file descriptor in
559 that refers to a pseudoterminal master,
563 and return a new file descriptor that refers to the peer
564 pseudoterminal slave device.
565 This operation can be performed
566 regardless of whether the pathname of the slave device
567 is accessible through the calling process's mount namespace.
569 Security-conscious programs interacting with namespaces may wish to use this
570 operation rather than
572 with the pathname returned by
574 and similar library functions that have insecure APIs.
575 (For example, confusion can occur in some cases using
577 with a pathname where a devpts filesystem
578 has been mounted in a different mount namespace.)
586 have not been implemented under Linux.
593 Get the status of modem bits.
597 .BI "const int\~*" argp
599 Set the status of modem bits.
603 .BI "const int\~*" argp
605 Clear the indicated modem bits.
609 .BI "const int\~*" argp
611 Set the indicated modem bits.
613 The following bits are used by the above ioctls:
617 TIOCM_LE DSR (data set ready/line enable)
618 TIOCM_DTR DTR (data terminal ready)
619 TIOCM_RTS RTS (request to send)
620 TIOCM_ST Secondary TXD (transmit)
621 TIOCM_SR Secondary RXD (receive)
622 TIOCM_CTS CTS (clear to send)
623 TIOCM_CAR DCD (data carrier detect)
624 TIOCM_CD see TIOCM_CAR
626 TIOCM_RI see TIOCM_RNG
627 TIOCM_DSR DSR (data set ready)
634 Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change.
635 The bits of interest are specified as a bit mask in
637 by ORing together any of the bit values,
643 The caller should use
645 to see which bit has changed.
649 .BI "struct serial_icounter_struct\~*" argp
651 Get counts of input serial line interrupts (DCD, RI, DSR, CTS).
652 The counts are written to the
653 .I serial_icounter_struct
654 structure pointed to by
657 Note: both 1->0 and 0->1 transitions are counted, except for
658 RI, where only 0->1 transitions are counted.
659 .SS Marking a line as local
665 ("Get software carrier flag")
666 Get the status of the CLOCAL flag in the c_cflag field of the
672 .BI "const int\~*" argp
674 ("Set software carrier flag")
675 Set the CLOCAL flag in the
679 is nonzero, and clear it otherwise.
683 flag for a line is off, the hardware carrier detect (DCD)
684 signal is significant, and an
686 of the corresponding terminal will block until DCD is asserted,
692 is set, the line behaves as if DCD is always asserted.
693 The software carrier flag is usually turned on for local devices,
694 and is off for lines with modems.
699 .BR ioctl_console (2).
701 .B "#include <linux/tty.h>"
705 .BI "struct tty_struct\~*" argp
711 This command was removed in Linux 2.5.67.
712 .\" commit b3506a09d15dc5aee6d4bb88d759b157016e1864
713 .\" Author: Andries E. Brouwer <andries.brouwer@cwi.nl>
714 .\" Date: Tue Apr 1 04:42:46 2003 -0800
716 .\" [PATCH] kill TIOCTTYGSTRUCT
718 .\" Only used for (dubious) debugging purposes, and exposes
719 .\" internal kernel state.
722 .\" .BR "#include <linux/serial.h>"
725 .\" .BI "TIOCGSERIAL struct serial_struct *" argp
728 .\" .BI "TIOCSSERIAL const struct serial_struct *" argp
733 system call returns 0 on success.
734 On error, it returns \-1 and sets
736 to indicate the error.
740 Invalid command parameter.
750 Insufficient permission.
752 Check the condition of DTR on the serial port.
758 #include <sys/ioctl.h>
765 fd = open("/dev/ttyS0", O_RDONLY);
766 ioctl(fd, TIOCMGET, &serial);
767 if (serial & TIOCM_DTR)
768 puts("TIOCM_DTR is set");
770 puts("TIOCM_DTR is not set");
775 Get or set arbitrary baudrate on the serial port.
778 /* SPDX-License-Identifier: GPL-2.0-or-later */
780 #include <asm/termbits.h>
784 #include <sys/ioctl.h>
785 #include <sys/types.h>
789 main(int argc, char *argv[])
792 fprintf(stderr, "BOTHER is unsupported\en");
793 /* Program may fallback to TCGETS/TCSETS with Bnnn constants */
796 /* Declare tio structure, its type depends on supported ioctl */
804 if (argc != 2 && argc != 3 && argc != 4) {
805 fprintf(stderr, "Usage: %s device [output [input] ]\en", argv[0]);
809 fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY);
815 /* Get the current serial port settings via supported ioctl */
817 rc = ioctl(fd, TCGETS2, &tio);
819 rc = ioctl(fd, TCGETS, &tio);
827 /* Change baud rate when more arguments were provided */
828 if (argc == 3 || argc == 4) {
829 /* Clear the current output baud rate and fill a new value */
830 tio.c_cflag &= ~CBAUD;
831 tio.c_cflag |= BOTHER;
832 tio.c_ospeed = atoi(argv[2]);
834 /* Clear the current input baud rate and fill a new value */
835 tio.c_cflag &= ~(CBAUD << IBSHIFT);
836 tio.c_cflag |= BOTHER << IBSHIFT;
837 /* When 4th argument is not provided reuse output baud rate */
838 tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]);
840 /* Set new serial port settings via supported ioctl */
842 rc = ioctl(fd, TCSETS2, &tio);
844 rc = ioctl(fd, TCSETS, &tio);
852 /* And get new values which were really configured */
854 rc = ioctl(fd, TCGETS2, &tio);
856 rc = ioctl(fd, TCGETS, &tio);
867 printf("output baud rate: %u\en", tio.c_ospeed);
868 printf("input baud rate: %u\en", tio.c_ispeed);
877 .BR ioctl_console (2),
881 .\" FIONBIO const int *
884 .\" FIOASYNC const int *
886 .\" TIOCSERCONFIG void
887 .\" TIOCSERGWILD int *
888 .\" TIOCSERSWILD const int *
889 .\" TIOCSERGSTRUCT struct async_struct *
890 .\" TIOCSERGETLSR int *
891 .\" TIOCSERGETMULTI struct serial_multiport_struct *
892 .\" TIOCSERSETMULTI const struct serial_multiport_struct *
893 .\" TIOCGSERIAL, TIOCSSERIAL (see above)