diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man2/ioctl.2')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man2/ioctl.2 | 88 |
1 files changed, 67 insertions, 21 deletions
diff --git a/upstream/opensuse-tumbleweed/man2/ioctl.2 b/upstream/opensuse-tumbleweed/man2/ioctl.2 index d6c07016..705f5db5 100644 --- a/upstream/opensuse-tumbleweed/man2/ioctl.2 +++ b/upstream/opensuse-tumbleweed/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-05-02 "Linux man-pages (unreleased)" .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. |