diff options
Diffstat (limited to 'man2/ioctl_tty.2')
| -rw-r--r-- | man2/ioctl_tty.2 | 922 |
1 files changed, 0 insertions, 922 deletions
diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2 deleted file mode 100644 index 9d247ed..0000000 --- a/man2/ioctl_tty.2 +++ /dev/null @@ -1,922 +0,0 @@ -'\" 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 2024-03-03 "Linux man-pages 6.7" -.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) |