Many pages: Use \[ti] instead of \(ti

[thirdparty/man-pages.git] / man2 / ioctl_tty.2

diff --git a/man2/ioctl_tty.2 b/man2/ioctl_tty.2
index d0a10a5082be48eea8474b2ed14566e0316522c3..8d2f08242f0d1b700b44b8de4a8a3f795c275652 100644 (file)
--- a/man2/ioctl_tty.2
+++ b/man2/ioctl_tty.2
@@ -1,18 +1,22 @@
+'\" t
 .\" Copyright 2002 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
 .\" and Andries Brouwer <aeb@cwi.nl>.
 .\"
-.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
-.\" Distributed under GPL
-.\" %%%LICENSE_END
+.\" SPDX-License-Identifier: GPL-1.0-or-later
 .\"
-.TH IOCTL_TTY 2 2021-08-27 "Linux" "Linux Programmer's Manual"
+.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 <termios.h>" "      /* Definition of " CLOCAL ", and"
-.BR    "                             TC*" { FLUSH , ON , OFF "} constants */"
+.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 */"
 .PP
 .BI "int ioctl(int " fd ", int " cmd ", ...);"
 .fi
@@ -31,11 +35,24 @@ makes for nonportable programs.
 Use the POSIX interface described in
 .BR termios (3)
 whenever possible.
+.PP
+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
+.BI "struct termios\~*" argp
 .IP
 Equivalent to
 .IR "tcgetattr(fd, argp)" .
@@ -44,7 +61,7 @@ Get the current serial port settings.
 .TP
 .B TCSETS
 Argument:
-.BI "const struct termios *" argp
+.BI "const struct termios\~*" argp
 .IP
 Equivalent to
 .IR "tcsetattr(fd, TCSANOW, argp)" .
@@ -53,7 +70,7 @@ Set the current serial port settings.
 .TP
 .B TCSETSW
 Argument:
-.BI "const struct termios *" argp
+.BI "const struct termios\~*" argp
 .IP
 Equivalent to
 .IR "tcsetattr(fd, TCSADRAIN, argp)" .
@@ -63,7 +80,7 @@ set the current serial port settings.
 .TP
 .B TCSETSF
 Argument:
-.BI "const struct termios *" argp
+.BI "const struct termios\~*" argp
 .IP
 Equivalent to
 .IR "tcsetattr(fd, TCSAFLUSH, argp)" .
@@ -80,9 +97,9 @@ are just like
 .BR TCSETSW ,
 .BR TCSETSF ,
 except that they take a
-.I "struct termios2\ *"
+.I "struct termios2\~*"
 instead of a
-.IR "struct termios\ *" .
+.IR "struct termios\~*" .
 If the structure member
 .B c_cflag
 contains the flag
@@ -109,9 +126,9 @@ The following four ioctls are just like
 .BR TCSETSW ,
 .BR TCSETSF ,
 except that they take a
-.I "struct termio\ *"
+.I "struct termio\~*"
 instead of a
-.IR "struct termios\ *" .
+.IR "struct termios\~*" .
 .RS
 .TS
 lb l.
@@ -132,7 +149,7 @@ locked value.
 .TP
 .B TIOCGLCKTRMIOS
 Argument:
-.BI "struct termios *" argp
+.BI "struct termios\~*" argp
 .IP
 Gets the locking status of the
 .I termios
@@ -140,13 +157,13 @@ structure of the terminal.
 .TP
 .B TIOCSLCKTRMIOS
 Argument:
-.BI "const struct termios *" argp
+.BI "const struct termios\~*" argp
 .IP
 Sets the locking status of the
 .I termios
 structure of the terminal.
 Only a process with the
-.BR CAP_SYS_ADMIN
+.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
@@ -156,13 +173,13 @@ for example, by loading a new font).
 .TP
 .B TIOCGWINSZ
 Argument:
-.BI "struct winsize *" argp
+.BI "struct winsize\~*" argp
 .IP
 Get window size.
 .TP
 .B TIOCSWINSZ
 Argument:
-.BI "const struct winsize *" argp
+.BI "const struct winsize\~*" argp
 .IP
 Set window size.
 .PP
@@ -234,13 +251,13 @@ when the driver does not support breaks.
 .TP
 .B TIOCSBRK
 Argument:
-.BI "void"
+.B void
 .IP
 Turn break on, that is, start sending zero bits.
 .TP
 .B TIOCCBRK
 Argument:
-.BI "void"
+.B void
 .IP
 Turn break off, that is, stop sending zero bits.
 .SS Software flow control
@@ -261,22 +278,22 @@ for the argument values
 .BR TCION .
 .SS Buffer count and flushing
 .TP
-.BI FIONREAD
+.B FIONREAD
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 Get the number of bytes in the input buffer.
 .TP
 .B TIOCINQ
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 Same as
 .BR FIONREAD .
 .TP
 .B TIOCOUTQ
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 Get the number of bytes in the output buffer.
 .TP
@@ -293,18 +310,35 @@ 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
+.BI "const char\~*" argp
 .IP
 Insert the given byte in the input queue.
 .SS Redirecting console output
 .TP
 .B TIOCCONS
 Argument:
-.BI "void"
+.B void
 .IP
 Redirect output that would have gone to
 .I /dev/console
@@ -312,10 +346,10 @@ or
 .I /dev/tty0
 to the given terminal.
 If that was a pseudoterminal master, send it to the slave.
-In Linux before version 2.6.10,
+Before Linux 2.6.10,
 anybody can do this as long as the output was not redirected yet;
-since version 2.6.10, only a process with the
-.BR CAP_SYS_ADMIN
+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
@@ -343,7 +377,7 @@ 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
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
 capability and
 .I arg
 equals 1, in which case the terminal is stolen, and all processes that had
@@ -351,7 +385,7 @@ it as controlling terminal lose it.
 .TP
 .B TIOCNOTTY
 Argument:
-.BI "void"
+.B void
 .IP
 If the given terminal was the controlling terminal of the calling process,
 give up this controlling terminal.
@@ -366,7 +400,7 @@ and all processes in the current session lose their controlling terminal.
 .TP
 .B TIOCGPGRP
 Argument:
-.BI "pid_t *" argp
+.BI "pid_t\~*" argp
 .IP
 When successful, equivalent to
 .IR "*argp = tcgetpgrp(fd)" .
@@ -375,7 +409,7 @@ Get the process group ID of the foreground process group on this terminal.
 .TP
 .B TIOCSPGRP
 Argument:
-.BI "const pid_t *" argp
+.BI "const pid_t\~*" argp
 .IP
 Equivalent to
 .IR "tcsetpgrp(fd, *argp)" .
@@ -384,7 +418,7 @@ Set the foreground process group ID of this terminal.
 .TP
 .B TIOCGSID
 Argument:
-.BI "pid_t *" argp
+.BI "pid_t\~*" argp
 .IP
 When successful, equivalent to
 .IR "*argp = tcgetsid(fd)" .
@@ -399,7 +433,7 @@ Strange.
 .TP
 .B TIOCEXCL
 Argument:
-.BI "void"
+.B void
 .IP
 Put the terminal into exclusive mode.
 No further
@@ -408,12 +442,12 @@ operations on the terminal are permitted.
 (They fail with
 .BR EBUSY ,
 except for a process with the
-.BR CAP_SYS_ADMIN
+.B CAP_SYS_ADMIN
 capability.)
 .TP
 .B TIOCGEXCL
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 (since Linux 3.8)
 If the terminal is currently in exclusive mode,
@@ -424,27 +458,27 @@ otherwise, place zero in
 .TP
 .B TIOCNXCL
 Argument:
-.BI "void"
+.B void
 .IP
 Disable exclusive mode.
 .SS Line discipline
 .TP
 .B TIOCGETD
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 Get the line discipline of the terminal.
 .TP
 .B TIOCSETD
 Argument:
-.BI "const int *" argp
+.BI "const int\~*" argp
 .IP
 Set the line discipline of the terminal.
 .SS Pseudoterminal ioctls
 .TP
 .B TIOCPKT
 Argument:
-.BI "const int *" argp
+.BI "const int\~*" argp
 .IP
 Enable (when
 .RI * argp
@@ -455,7 +489,7 @@ 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
+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
@@ -505,7 +539,7 @@ locally \fB\(haS\fP/\fB\(haQ\fP flow-controlled remote login.
 .TP
 .B TIOCGPKT
 Argument:
-.BI "const int *" argp
+.BI "const int\~*" argp
 .IP
 (since Linux 3.8)
 Return the current packet mode setting in the integer pointed to by
@@ -513,19 +547,19 @@ Return the current packet mode setting in the integer pointed to by
 .TP
 .B TIOCSPTLCK
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 Set (if
-.IR *argp
+.I *argp
 is nonzero) or remove (if
-.IR *argp
+.I *argp
 is zero) the lock on the pseudoterminal slave device.
 (See also
 .BR unlockpt (3).)
 .TP
 .B TIOCGPTLCK
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 (since Linux 3.8)
 Place the current lock state of the pseudoterminal slave device
@@ -572,25 +606,25 @@ have not been implemented under Linux.
 .TP
 .B TIOCMGET
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 Get the status of modem bits.
 .TP
 .B TIOCMSET
 Argument:
-.BI "const int *" argp
+.BI "const int\~*" argp
 .IP
 Set the status of modem bits.
 .TP
 .B TIOCMBIC
 Argument:
-.BI "const int *" argp
+.BI "const int\~*" argp
 .IP
 Clear the indicated modem bits.
 .TP
 .B TIOCMBIS
 Argument:
-.BI "const int *" argp
+.BI "const int\~*" argp
 .IP
 Set the indicated modem bits.
 .PP
@@ -630,7 +664,7 @@ to see which bit has changed.
 .TP
 .B TIOCGICOUNT
 Argument:
-.BI "struct serial_icounter_struct *" argp
+.BI "struct serial_icounter_struct\~*" argp
 .IP
 Get counts of input serial line interrupts (DCD, RI, DSR, CTS).
 The counts are written to the
@@ -644,7 +678,7 @@ RI, where only 0->1 transitions are counted.
 .TP
 .B TIOCGSOFTCAR
 Argument:
-.BI "int *" argp
+.BI "int\~*" argp
 .IP
 ("Get software carrier flag")
 Get the status of the CLOCAL flag in the c_cflag field of the
@@ -653,7 +687,7 @@ structure.
 .TP
 .B TIOCSSOFTCAR
 Argument:
-.BI "const int *" argp
+.BI "const int\~*" argp
 .IP
 ("Set software carrier flag")
 Set the CLOCAL flag in the
@@ -686,7 +720,7 @@ ioctl, see
 .TP
 .B TIOCTTYGSTRUCT
 Argument:
-.BI "struct tty_struct *" argp
+.BI "struct tty_struct\~*" argp
 .IP
 Get the
 .I tty_struct
@@ -735,11 +769,12 @@ Insufficient permission.
 .SH EXAMPLES
 Check the condition of DTR on the serial port.
 .PP
+.\" SRC BEGIN (tiocmget.c)
 .EX
-#include <stdio.h>
-#include <unistd.h>
 #include <fcntl.h>
+#include <stdio.h>
 #include <sys/ioctl.h>
+#include <unistd.h>
 
 int
 main(void)
@@ -755,9 +790,11 @@ main(void)
     close(fd);
 }
 .EE
+.\" SRC END
 .PP
 Get or set arbitrary baudrate on the serial port.
 .PP
+.\" SRC BEGIN (tcgets.c)
 .EX
 /* SPDX-License-Identifier: GPL-2.0-or-later */
 
@@ -766,7 +803,6 @@ Get or set arbitrary baudrate on the serial port.
 #include <stdio.h>
 #include <stdlib.h>
 #include <sys/ioctl.h>
-#include <sys/types.h>
 #include <unistd.h>
 
 int
@@ -811,12 +847,12 @@ main(int argc, char *argv[])
     /* 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 &= ~CBAUD;
+        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 &= ~(CBAUD << IBSHIFT);
+        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]);
@@ -855,8 +891,9 @@ main(int argc, char *argv[])
 #endif
 }
 .EE
+.\" SRC END
 .SH SEE ALSO
-.BR ldattach (1),
+.BR ldattach (8),
 .BR ioctl (2),
 .BR ioctl_console (2),
 .BR termios (3),
@@ -871,7 +908,6 @@ main(int argc, char *argv[])
 .\" TIOCSERGWILD               int *
 .\" TIOCSERSWILD               const int *
 .\" TIOCSERGSTRUCT             struct async_struct *
-.\" TIOCSERGETLSR              int *
 .\" TIOCSERGETMULTI            struct serial_multiport_struct *
 .\" TIOCSERSETMULTI            const struct serial_multiport_struct *
 .\" TIOCGSERIAL, TIOCSSERIAL (see above)