diff options
Diffstat (limited to 'man/man2/ioctl_tty.2')
| -rw-r--r-- | man/man2/ioctl_tty.2 | 922 |
1 files changed, 922 insertions, 0 deletions
diff --git a/man/man2/ioctl_tty.2 b/man/man2/ioctl_tty.2 new file mode 100644 index 000000000..c458933a2 --- /dev/null +++ b/man/man2/ioctl_tty.2 @@ -0,0 +1,922 @@ +'\" t +.\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de> +.\" and Andries Brouwer <aeb@cwi.nl>. +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.TH ioctl_tty 2 (date) "Linux man-pages (unreleased)" +.SH NAME +ioctl_tty \- ioctls for terminals and serial lines +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/ioctl.h> +.BR "#include <asm/termbits.h>" " /* Definition of " "struct termios" , +.BR " struct termios2" ", and" +.BR " Bnnn" ", " BOTHER ", " CBAUD ", " CLOCAL , +.BR " TC*" { FLUSH , ON , OFF "} and other constants */" +.P +.BI "int ioctl(int " fd ", int " op ", ...);" +.fi +.SH DESCRIPTION +The +.BR ioctl (2) +call for terminals and serial ports accepts many possible operation arguments. +Most require a third argument, of varying type, here called +.I argp +or +.IR arg . +.P +Use of +.BR ioctl () +makes for nonportable programs. +Use the POSIX interface described in +.BR termios (3) +whenever possible. +.P +Please note that +.B struct termios +from +.I <asm/termbits.h> +is different and incompatible with +.B struct termios +from +.IR <termios.h> . +These ioctl calls require +.B struct termios +from +.IR <asm/termbits.h> . +.SS Get and set terminal attributes +.TP +.B TCGETS +Argument: +.BI "struct termios\~*" argp +.IP +Equivalent to +.IR "tcgetattr(fd, argp)" . +.IP +Get the current serial port settings. +.TP +.B TCSETS +Argument: +.BI "const struct termios\~*" argp +.IP +Equivalent to +.IR "tcsetattr(fd, TCSANOW, argp)" . +.IP +Set the current serial port settings. +.TP +.B TCSETSW +Argument: +.BI "const struct termios\~*" argp +.IP +Equivalent to +.IR "tcsetattr(fd, TCSADRAIN, argp)" . +.IP +Allow the output buffer to drain, and +set the current serial port settings. +.TP +.B TCSETSF +Argument: +.BI "const struct termios\~*" argp +.IP +Equivalent to +.IR "tcsetattr(fd, TCSAFLUSH, argp)" . +.IP +Allow the output buffer to drain, discard pending input, and +set the current serial port settings. +.P +The following four ioctls, added in Linux 2.6.20, +.\" commit 64bb6c5e1ddcd47c951740485026ef08975ee2e6 +.\" commit 592ee3a5e5e2a981ef2829a0380093006d045661 +are just like +.BR TCGETS , +.BR TCSETS , +.BR TCSETSW , +.BR TCSETSF , +except that they take a +.I "struct termios2\~*" +instead of a +.IR "struct termios\~*" . +If the structure member +.B c_cflag +contains the flag +.BR BOTHER , +then the baud rate is stored in the structure members +.B c_ispeed +and +.B c_ospeed +as integer values. +These ioctls are not supported on all architectures. +.RS +.TS +lb l. +TCGETS2 \fBstruct termios2 *\fPargp +TCSETS2 \fBconst struct termios2 *\fPargp +TCSETSW2 \fBconst struct termios2 *\fPargp +TCSETSF2 \fBconst struct termios2 *\fPargp +.TE +.RE +.P +The following four ioctls are just like +.BR TCGETS , +.BR TCSETS , +.BR TCSETSW , +.BR TCSETSF , +except that they take a +.I "struct termio\~*" +instead of a +.IR "struct termios\~*" . +.RS +.TS +lb l. +TCGETA \fBstruct termio *\fPargp +TCSETA \fBconst struct termio *\fPargp +TCSETAW \fBconst struct termio *\fPargp +TCSETAF \fBconst struct termio *\fPargp +.TE +.RE +.SS Locking the termios structure +The +.I termios +structure of a terminal can be locked. +The lock is itself a +.I termios +structure, with nonzero bits or fields indicating a +locked value. +.TP +.B TIOCGLCKTRMIOS +Argument: +.BI "struct termios\~*" argp +.IP +Gets the locking status of the +.I termios +structure of the terminal. +.TP +.B TIOCSLCKTRMIOS +Argument: +.BI "const struct termios\~*" argp +.IP +Sets the locking status of the +.I termios +structure of the terminal. +Only a process with the +.B CAP_SYS_ADMIN +capability can do this. +.SS Get and set window size +Window sizes are kept in the kernel, but not used by the kernel +(except in the case of virtual consoles, where the kernel will +update the window size when the size of the virtual console changes, +for example, by loading a new font). +.TP +.B TIOCGWINSZ +Argument: +.BI "struct winsize\~*" argp +.IP +Get window size. +.TP +.B TIOCSWINSZ +Argument: +.BI "const struct winsize\~*" argp +.IP +Set window size. +.P +The struct used by these ioctls is defined as +.P +.in +4n +.EX +struct winsize { + unsigned short ws_row; + unsigned short ws_col; + unsigned short ws_xpixel; /* unused */ + unsigned short ws_ypixel; /* unused */ +}; +.EE +.in +.P +When the window size changes, a +.B SIGWINCH +signal is sent to the +foreground process group. +.SS Sending a break +.TP +.B TCSBRK +Argument: +.BI "int " arg +.IP +Equivalent to +.IR "tcsendbreak(fd, arg)" . +.IP +If the terminal is using asynchronous serial data transmission, and +.I arg +is zero, then send a break (a stream of zero bits) for between +0.25 and 0.5 seconds. +If the terminal is not using asynchronous +serial data transmission, then either a break is sent, or the function +returns without doing anything. +When +.I arg +is nonzero, nobody knows what will happen. +.IP +(SVr4, UnixWare, Solaris, and Linux treat +.I "tcsendbreak(fd,arg)" +with nonzero +.I arg +like +.IR "tcdrain(fd)" . +SunOS treats +.I arg +as a multiplier, and sends a stream of bits +.I arg +times as long as done for zero +.IR arg . +DG/UX and AIX treat +.I arg +(when nonzero) as a time interval measured in milliseconds. +HP-UX ignores +.IR arg .) +.TP +.B TCSBRKP +Argument: +.BI "int " arg +.IP +So-called "POSIX version" of +.BR TCSBRK . +It treats nonzero +.I arg +as a time interval measured in deciseconds, and does nothing +when the driver does not support breaks. +.TP +.B TIOCSBRK +Argument: +.B void +.IP +Turn break on, that is, start sending zero bits. +.TP +.B TIOCCBRK +Argument: +.B void +.IP +Turn break off, that is, stop sending zero bits. +.SS Software flow control +.TP +.B TCXONC +Argument: +.BI "int " arg +.IP +Equivalent to +.IR "tcflow(fd, arg)" . +.IP +See +.BR tcflow (3) +for the argument values +.BR TCOOFF , +.BR TCOON , +.BR TCIOFF , +.BR TCION . +.SS Buffer count and flushing +.TP +.B FIONREAD +Argument: +.BI "int\~*" argp +.IP +Get the number of bytes in the input buffer. +.TP +.B TIOCINQ +Argument: +.BI "int\~*" argp +.IP +Same as +.BR FIONREAD . +.TP +.B TIOCOUTQ +Argument: +.BI "int\~*" argp +.IP +Get the number of bytes in the output buffer. +.TP +.B TCFLSH +Argument: +.BI "int " arg +.IP +Equivalent to +.IR "tcflush(fd, arg)" . +.IP +See +.BR tcflush (3) +for the argument values +.BR TCIFLUSH , +.BR TCOFLUSH , +.BR TCIOFLUSH . +.TP +.B TIOCSERGETLSR +Argument: +.BI "int\~*" argp +.IP +Get line status register. +Status register has +.B TIOCSER_TEMT +bit set when +output buffer is empty and also hardware transmitter is physically empty. +.IP +Does not have to be supported by all serial tty drivers. +.IP +.BR tcdrain (3) +does not wait and returns immediately when +.B TIOCSER_TEMT +bit is set. +.SS Faking input +.TP +.B TIOCSTI +Argument: +.BI "const char\~*" argp +.IP +Insert the given byte in the input queue. +.IP +Since Linux 6.2, +.\" commit 690c8b804ad2eafbd35da5d3c95ad325ca7d5061 +.\" commit 83efeeeb3d04b22aaed1df99bc70a48fe9d22c4d +this operation may require the +.B CAP_SYS_ADMIN +capability (if the +.I dev.tty.legacy_tiocsti +sysctl variable is set to false). +.SS Redirecting console output +.TP +.B TIOCCONS +Argument: +.B void +.IP +Redirect output that would have gone to +.I /dev/console +or +.I /dev/tty0 +to the given terminal. +If that was a pseudoterminal master, send it to the slave. +Before Linux 2.6.10, +anybody can do this as long as the output was not redirected yet; +since Linux 2.6.10, only a process with the +.B CAP_SYS_ADMIN +capability may do this. +If output was redirected already, then +.B EBUSY +is returned, +but redirection can be stopped by using this ioctl with +.I fd +pointing at +.I /dev/console +or +.IR /dev/tty0 . +.SS Controlling terminal +.TP +.B TIOCSCTTY +Argument: +.BI "int " arg +.IP +Make the given terminal the controlling terminal of the calling process. +The calling process must be a session leader and not have a +controlling terminal already. +For this case, +.I arg +should be specified as zero. +.IP +If this terminal is already the controlling terminal +of a different session group, then the ioctl fails with +.BR EPERM , +unless the caller has the +.B CAP_SYS_ADMIN +capability and +.I arg +equals 1, in which case the terminal is stolen, and all processes that had +it as controlling terminal lose it. +.TP +.B TIOCNOTTY +Argument: +.B void +.IP +If the given terminal was the controlling terminal of the calling process, +give up this controlling terminal. +If the process was session leader, +then send +.B SIGHUP +and +.B SIGCONT +to the foreground process group +and all processes in the current session lose their controlling terminal. +.SS Process group and session ID +.TP +.B TIOCGPGRP +Argument: +.BI "pid_t\~*" argp +.IP +When successful, equivalent to +.IR "*argp = tcgetpgrp(fd)" . +.IP +Get the process group ID of the foreground process group on this terminal. +.TP +.B TIOCSPGRP +Argument: +.BI "const pid_t\~*" argp +.IP +Equivalent to +.IR "tcsetpgrp(fd, *argp)" . +.IP +Set the foreground process group ID of this terminal. +.TP +.B TIOCGSID +Argument: +.BI "pid_t\~*" argp +.IP +When successful, equivalent to +.IR "*argp = tcgetsid(fd)" . +.IP +Get the session ID of the given terminal. +This fails with the error +.B ENOTTY +if the terminal is not a master pseudoterminal +and not our controlling terminal. +Strange. +.SS Exclusive mode +.TP +.B TIOCEXCL +Argument: +.B void +.IP +Put the terminal into exclusive mode. +No further +.BR open (2) +operations on the terminal are permitted. +(They fail with +.BR EBUSY , +except for a process with the +.B CAP_SYS_ADMIN +capability.) +.TP +.B TIOCGEXCL +Argument: +.BI "int\~*" argp +.IP +(since Linux 3.8) +If the terminal is currently in exclusive mode, +place a nonzero value in the location pointed to by +.IR argp ; +otherwise, place zero in +.IR *argp . +.TP +.B TIOCNXCL +Argument: +.B void +.IP +Disable exclusive mode. +.SS Line discipline +.TP +.B TIOCGETD +Argument: +.BI "int\~*" argp +.IP +Get the line discipline of the terminal. +.TP +.B TIOCSETD +Argument: +.BI "const int\~*" argp +.IP +Set the line discipline of the terminal. +.SS Pseudoterminal ioctls +.TP +.B TIOCPKT +Argument: +.BI "const int\~*" argp +.IP +Enable (when +.RI * argp +is nonzero) or disable packet mode. +Can be applied to the master side of a pseudoterminal only (and will return +.B ENOTTY +otherwise). +In packet mode, each subsequent +.BR read (2) +will return a packet that either contains a single nonzero control byte, +or has a single byte containing zero (\[aq]\e0\[aq]) followed by data +written on the slave side of the pseudoterminal. +If the first byte is not +.B TIOCPKT_DATA +(0), it is an OR of one +or more of the following bits: +.IP +.ad l +.TS +lb l. +TIOCPKT_FLUSHREAD T{ +The read queue for the terminal is flushed. +T} +TIOCPKT_FLUSHWRITE T{ +The write queue for the terminal is flushed. +T} +TIOCPKT_STOP T{ +Output to the terminal is stopped. +T} +TIOCPKT_START T{ +Output to the terminal is restarted. +T} +TIOCPKT_DOSTOP T{ +The start and stop characters are \fB\[ha]S\fP/\fB\[ha]Q\fP. +T} +TIOCPKT_NOSTOP T{ +The start and stop characters are not \fB\[ha]S\fP/\fB\[ha]Q\fP. +T} +.TE +.ad +.IP +While packet mode is in use, the presence +of control status information to be read +from the master side may be detected by a +.BR select (2) +for exceptional conditions or a +.BR poll (2) +for the +.B POLLPRI +event. +.IP +This mode is used by +.BR rlogin (1) +and +.BR rlogind (8) +to implement a remote-echoed, +locally \fB\[ha]S\fP/\fB\[ha]Q\fP flow-controlled remote login. +.TP +.B TIOCGPKT +Argument: +.BI "const int\~*" argp +.IP +(since Linux 3.8) +Return the current packet mode setting in the integer pointed to by +.IR argp . +.TP +.B TIOCSPTLCK +Argument: +.BI "int\~*" argp +.IP +Set (if +.I *argp +is nonzero) or remove (if +.I *argp +is zero) the lock on the pseudoterminal slave device. +(See also +.BR unlockpt (3).) +.TP +.B TIOCGPTLCK +Argument: +.BI "int\~*" argp +.IP +(since Linux 3.8) +Place the current lock state of the pseudoterminal slave device +in the location pointed to by +.IR argp . +.TP +.B TIOCGPTPEER +Argument: +.BI "int " flags +.IP +.\" commit 54ebbfb1603415d9953c150535850d30609ef077 +(since Linux 4.13) +Given a file descriptor in +.I fd +that refers to a pseudoterminal master, +open (with the given +.BR open (2)-style +.IR flags ) +and return a new file descriptor that refers to the peer +pseudoterminal slave device. +This operation can be performed +regardless of whether the pathname of the slave device +is accessible through the calling process's mount namespace. +.IP +Security-conscious programs interacting with namespaces may wish to use this +operation rather than +.BR open (2) +with the pathname returned by +.BR ptsname (3), +and similar library functions that have insecure APIs. +(For example, confusion can occur in some cases using +.BR ptsname (3) +with a pathname where a devpts filesystem +has been mounted in a different mount namespace.) +.P +The BSD ioctls +.BR TIOCSTOP , +.BR TIOCSTART , +.BR TIOCUCNTL , +and +.B TIOCREMOTE +have not been implemented under Linux. +.SS Modem control +.TP +.B TIOCMGET +Argument: +.BI "int\~*" argp +.IP +Get the status of modem bits. +.TP +.B TIOCMSET +Argument: +.BI "const int\~*" argp +.IP +Set the status of modem bits. +.TP +.B TIOCMBIC +Argument: +.BI "const int\~*" argp +.IP +Clear the indicated modem bits. +.TP +.B TIOCMBIS +Argument: +.BI "const int\~*" argp +.IP +Set the indicated modem bits. +.P +The following bits are used by the above ioctls: +.P +.TS +lb l. +TIOCM_LE DSR (data set ready/line enable) +TIOCM_DTR DTR (data terminal ready) +TIOCM_RTS RTS (request to send) +TIOCM_ST Secondary TXD (transmit) +TIOCM_SR Secondary RXD (receive) +TIOCM_CTS CTS (clear to send) +TIOCM_CAR DCD (data carrier detect) +TIOCM_CD see TIOCM_CAR +TIOCM_RNG RNG (ring) +TIOCM_RI see TIOCM_RNG +TIOCM_DSR DSR (data set ready) +.TE +.TP +.B TIOCMIWAIT +Argument: +.BI "int " arg +.IP +Wait for any of the 4 modem bits (DCD, RI, DSR, CTS) to change. +The bits of interest are specified as a bit mask in +.IR arg , +by ORing together any of the bit values, +.BR TIOCM_RNG , +.BR TIOCM_DSR , +.BR TIOCM_CD , +and +.BR TIOCM_CTS . +The caller should use +.B TIOCGICOUNT +to see which bit has changed. +.TP +.B TIOCGICOUNT +Argument: +.BI "struct serial_icounter_struct\~*" argp +.IP +Get counts of input serial line interrupts (DCD, RI, DSR, CTS). +The counts are written to the +.I serial_icounter_struct +structure pointed to by +.IR argp . +.IP +Note: both 1->0 and 0->1 transitions are counted, except for +RI, where only 0->1 transitions are counted. +.SS Marking a line as local +.TP +.B TIOCGSOFTCAR +Argument: +.BI "int\~*" argp +.IP +("Get software carrier flag") +Get the status of the CLOCAL flag in the c_cflag field of the +.I termios +structure. +.TP +.B TIOCSSOFTCAR +Argument: +.BI "const int\~*" argp +.IP +("Set software carrier flag") +Set the CLOCAL flag in the +.I termios +structure when +.RI * argp +is nonzero, and clear it otherwise. +.P +If the +.B CLOCAL +flag for a line is off, the hardware carrier detect (DCD) +signal is significant, and an +.BR open (2) +of the corresponding terminal will block until DCD is asserted, +unless the +.B O_NONBLOCK +flag is given. +If +.B CLOCAL +is set, the line behaves as if DCD is always asserted. +The software carrier flag is usually turned on for local devices, +and is off for lines with modems. +.SS Linux-specific +For the +.B TIOCLINUX +ioctl, see +.BR ioctl_console (2). +.SS Kernel debugging +.B "#include <linux/tty.h>" +.TP +.B TIOCTTYGSTRUCT +Argument: +.BI "struct tty_struct\~*" argp +.IP +Get the +.I tty_struct +corresponding to +.IR fd . +This operation was removed in Linux 2.5.67. +.\" commit b3506a09d15dc5aee6d4bb88d759b157016e1864 +.\" Author: Andries E. Brouwer <andries.brouwer@cwi.nl> +.\" Date: Tue Apr 1 04:42:46 2003 -0800 +.\" +.\" [PATCH] kill TIOCTTYGSTRUCT +.\" +.\" Only used for (dubious) debugging purposes, and exposes +.\" internal kernel state. +.\" +.\" .SS Serial info +.\" .BR "#include <linux/serial.h>" +.\" .P +.\" .TP +.\" .BI "TIOCGSERIAL struct serial_struct *" argp +.\" Get serial info. +.\" .TP +.\" .BI "TIOCSSERIAL const struct serial_struct *" argp +.\" Set serial info. +.SH RETURN VALUE +The +.BR ioctl (2) +system call returns 0 on success. +On error, it returns \-1 and sets +.I errno +to indicate the error. +.SH ERRORS +.TP +.B EINVAL +Invalid operation parameter. +.TP +.B ENOIOCTLCMD +Unknown operation. +.TP +.B ENOTTY +Inappropriate +.IR fd . +.TP +.B EPERM +Insufficient permission. +.SH EXAMPLES +Check the condition of DTR on the serial port. +.P +.\" SRC BEGIN (tiocmget.c) +.EX +#include <fcntl.h> +#include <stdio.h> +#include <sys/ioctl.h> +#include <unistd.h> +\& +int +main(void) +{ + int fd, serial; +\& + fd = open("/dev/ttyS0", O_RDONLY); + ioctl(fd, TIOCMGET, &serial); + if (serial & TIOCM_DTR) + puts("TIOCM_DTR is set"); + else + puts("TIOCM_DTR is not set"); + close(fd); +} +.EE +.\" SRC END +.P +Get or set arbitrary baudrate on the serial port. +.P +.\" SRC BEGIN (tcgets.c) +.EX +/* SPDX-License-Identifier: GPL-2.0-or-later */ +\& +#include <asm/termbits.h> +#include <fcntl.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/ioctl.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ +#if !defined BOTHER + fprintf(stderr, "BOTHER is unsupported\en"); + /* Program may fallback to TCGETS/TCSETS with Bnnn constants */ + exit(EXIT_FAILURE); +#else + /* Declare tio structure, its type depends on supported ioctl */ +# if defined TCGETS2 + struct termios2 tio; +# else + struct termios tio; +# endif + int fd, rc; +\& + if (argc != 2 && argc != 3 && argc != 4) { + fprintf(stderr, "Usage: %s device [output [input] ]\en", argv[0]); + exit(EXIT_FAILURE); + } +\& + fd = open(argv[1], O_RDWR | O_NONBLOCK | O_NOCTTY); + if (fd < 0) { + perror("open"); + exit(EXIT_FAILURE); + } +\& + /* Get the current serial port settings via supported ioctl */ +# if defined TCGETS2 + rc = ioctl(fd, TCGETS2, &tio); +# else + rc = ioctl(fd, TCGETS, &tio); +# endif + if (rc) { + perror("TCGETS"); + close(fd); + exit(EXIT_FAILURE); + } +\& + /* Change baud rate when more arguments were provided */ + if (argc == 3 || argc == 4) { + /* Clear the current output baud rate and fill a new value */ + tio.c_cflag &= \[ti]CBAUD; + tio.c_cflag |= BOTHER; + tio.c_ospeed = atoi(argv[2]); +\& + /* Clear the current input baud rate and fill a new value */ + tio.c_cflag &= \[ti](CBAUD << IBSHIFT); + tio.c_cflag |= BOTHER << IBSHIFT; + /* When 4th argument is not provided reuse output baud rate */ + tio.c_ispeed = (argc == 4) ? atoi(argv[3]) : atoi(argv[2]); +\& + /* Set new serial port settings via supported ioctl */ +# if defined TCSETS2 + rc = ioctl(fd, TCSETS2, &tio); +# else + rc = ioctl(fd, TCSETS, &tio); +# endif + if (rc) { + perror("TCSETS"); + close(fd); + exit(EXIT_FAILURE); + } +\& + /* And get new values which were really configured */ +# if defined TCGETS2 + rc = ioctl(fd, TCGETS2, &tio); +# else + rc = ioctl(fd, TCGETS, &tio); +# endif + if (rc) { + perror("TCGETS"); + close(fd); + exit(EXIT_FAILURE); + } + } +\& + close(fd); +\& + printf("output baud rate: %u\en", tio.c_ospeed); + printf("input baud rate: %u\en", tio.c_ispeed); +\& + exit(EXIT_SUCCESS); +#endif +} +.EE +.\" SRC END +.SH SEE ALSO +.BR ldattach (8), +.BR ioctl (2), +.BR ioctl_console (2), +.BR termios (3), +.BR pty (7) +.\" +.\" FIONBIO const int * +.\" FIONCLEX void +.\" FIOCLEX void +.\" FIOASYNC const int * +.\" from serial.c: +.\" TIOCSERCONFIG void +.\" TIOCSERGWILD int * +.\" TIOCSERSWILD const int * +.\" TIOCSERGSTRUCT struct async_struct * +.\" TIOCSERGETMULTI struct serial_multiport_struct * +.\" TIOCSERSETMULTI const struct serial_multiport_struct * +.\" TIOCGSERIAL, TIOCSSERIAL (see above) |