summaryrefslogtreecommitdiffstats
path: root/man2/ioctl.2
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man2/ioctl.288
1 files changed, 67 insertions, 21 deletions
diff --git a/man2/ioctl.2 b/man2/ioctl.2
index d6c0701..518712b 100644
--- a/man2/ioctl.2
+++ b/man2/ioctl.2
@@ -10,7 +10,7 @@
.\" Modified 1999-06-25 by Rachael Munns <vashti@dream.org.uk>
.\" Modified 2000-09-21 by Andries Brouwer <aeb@cwi.nl>
.\"
-.TH ioctl 2 2023-03-30 "Linux man-pages 6.05.01"
+.TH ioctl 2 2024-03-03 "Linux man-pages 6.7"
.SH NAME
ioctl \- control device
.SH LIBRARY
@@ -19,10 +19,9 @@ Standard C library
.SH SYNOPSIS
.nf
.B #include <sys/ioctl.h>
-.PP
-.BI "int ioctl(int " fd ", unsigned long " request ", ...);"
-.\" POSIX says 'request' is int, but glibc has the above
-.\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705
+.P
+.BI "int ioctl(int " fd ", unsigned long " op ", ...);" "\f[R] /* glibc, BSD */\f[]"
+.BI "int ioctl(int " fd ", int " op ", ...);" "\f[R] /* musl, other UNIX */\f[]"
.fi
.SH DESCRIPTION
The
@@ -31,22 +30,22 @@ system call manipulates the underlying device parameters of special files.
In particular, many operating characteristics of character special files
(e.g., terminals) may be controlled with
.BR ioctl ()
-requests.
+operations.
The argument
.I fd
must be an open file descriptor.
-.PP
-The second argument is a device-dependent request code.
+.P
+The second argument is a device-dependent operation code.
The third argument is an untyped pointer to memory.
It's traditionally
.BI "char *" argp
(from the days before
.B "void *"
was valid C), and will be so named for this discussion.
-.PP
+.P
An
.BR ioctl ()
-.I request
+.I op
has encoded in it whether the argument is an
.I in
parameter or
@@ -56,7 +55,7 @@ parameter, and the size of the argument
in bytes.
Macros and defines used in specifying an
.BR ioctl ()
-.I request
+.I op
are located in the file
.IR <sys/ioctl.h> .
See NOTES.
@@ -64,7 +63,7 @@ See NOTES.
Usually, on success zero is returned.
A few
.BR ioctl ()
-requests use the return value as an output parameter
+operations use the return value as an output parameter
and return a nonnegative value on success.
On error, \-1 is returned, and
.I errno
@@ -80,7 +79,7 @@ is not a valid file descriptor.
references an inaccessible memory area.
.TP
.B EINVAL
-.I request
+.I op
or
.I argp
is not valid.
@@ -90,7 +89,7 @@ is not valid.
is not associated with a character special device.
.TP
.B ENOTTY
-The specified request does not apply to the kind of object that the
+The specified operation does not apply to the kind of object that the
file descriptor
.I fd
references.
@@ -103,7 +102,52 @@ model).
.SH STANDARDS
None.
.SH HISTORY
-Version\~7 AT&T UNIX.
+Version\~7 AT&T UNIX has
+.PD 0
+.in +4n
+.nf
+.BI "ioctl(int " fildes ", int " op ", struct sgttyb *" argp );
+.fi
+.in
+.P
+.PD
+(where
+.B struct sgttyb
+has historically been used by
+.BR stty (2)
+and
+.BR gtty (2),
+and is polymorphic by operation type (like a
+.B void *
+would be, if it had been available)).
+.P
+SysIII documents
+.I arg
+without a type at all.
+.P
+4.3BSD has
+.PD 0
+.in +4n
+.nf
+.BI "ioctl(int " d ", unsigned long " op ", char *" argp );
+.fi
+.in
+.P
+.PD
+(with
+.B char *
+similarly in for
+.BR "void *" ).
+.P
+SysVr4 has
+.PD 0
+.in +4n
+.nf
+.BI "int ioctl(int " fildes ", int " op ", ... /* " arg " */);"
+.fi
+.in
+.P
+.PD
.SH NOTES
In order to use this call, one needs an open file descriptor.
Often the
@@ -115,10 +159,12 @@ flag.
.\"
.SS ioctl structure
.\" added two sections - aeb
-Ioctl command values are 32-bit constants.
+Ioctl
+.I op
+values are 32-bit constants.
In principle these constants are completely arbitrary, but people have
tried to build some structure into them.
-.PP
+.P
The old Linux situation was that of mostly 16-bit constants, where the
last byte is a serial number, and the preceding byte(s) give a type
indicating the driver.
@@ -137,7 +183,7 @@ has value
.B CYGETTIMEOUT
has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq]
indicating the cyclades driver.
-.PP
+.P
Later (0.98p5) some more information was built into the number.
One has 2 direction bits
(00: none, 01: write, 10: read, 11: read/write)
@@ -145,7 +191,7 @@ followed by 14 size bits (giving the size of the argument),
followed by an 8-bit type (collecting the ioctls in groups
for a common purpose or a common driver), and an 8-bit
serial number.
-.PP
+.P
The macros describing this structure live in
.I <asm/ioctl.h>
and are
@@ -156,12 +202,12 @@ They use
.I sizeof(size)
so that size is a
misnomer here: this third argument is a data type.
-.PP
+.P
Note that the size bits are very unreliable: in lots of cases
they are wrong, either because of buggy macros using
.IR sizeof(sizeof(struct)) ,
or because of legacy values.
-.PP
+.P
Thus, it seems that the new structure only gave disadvantages:
it does not help in checking, but it causes varying values
for the various architectures.