ioctl.2: Move subsection on "ioctl structure" from ioctl_list(2) to ioctl(2)

In preparation for removing ioctl_list(2), let's preserve
some useful text that was added to ioctl_list(2)
by Andries Brouwer.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/ioctl.2 b/man2/ioctl.2
index 6957b804503bfe8f25625a4acaad00a0846b1b57..9f8f51828bdba5c930666500261b227888ec6451 100644 (file)
--- a/man2/ioctl.2
+++ b/man2/ioctl.2
@@ -82,6 +82,7 @@ Macros and defines used in specifying an
 .I request
 are located in the file
 .IR <sys/ioctl.h> .
+See NOTES.
 .SH RETURN VALUE
 Usually, on success zero is returned.
 A few
@@ -139,6 +140,59 @@ call has unwanted side effects, that can be avoided under Linux
 by giving it the
 .B O_NONBLOCK
 flag.
+.\"
+.SS ioctl structure
+.\" added two sections - aeb
+Ioctl command values are 32-bit constants.
+In principle these constants are completely arbitrary, but people have
+tried to build some structure into them.
+.PP
+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.
+Sometimes the major number was used: 0x03
+for the
+.B HDIO_*
+ioctls, 0x06 for the
+.B LP*
+ioctls.
+And sometimes
+one or more ASCII letters were used.
+For example,
+.B TCGETS
+has value
+0x00005401, with 0x54 = \(aqT\(aq indicating the terminal driver, and
+.B CYGETTIMEOUT
+has value 0x00435906, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq
+indicating the cyclades driver.
+.PP
+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)
+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
+The macros describing this structure live in
+.I <asm/ioctl.h>
+and are
+.B _IO(type,nr)
+and
+.BR "{_IOR,_IOW,_IOWR}(type,nr,size)" .
+They use
+.I sizeof(size)
+so that size is a
+misnomer here: this third argument is a data type.
+.PP
+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
+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.
 .SH SEE ALSO
 .BR execve (2),
 .BR fcntl (2),