diff options
Diffstat (limited to 'upstream/debian-bookworm/man2/ioctl.2')
| -rw-r--r-- | upstream/debian-bookworm/man2/ioctl.2 | 186 |
1 files changed, 186 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/ioctl.2 b/upstream/debian-bookworm/man2/ioctl.2 new file mode 100644 index 00000000..e436dd52 --- /dev/null +++ b/upstream/debian-bookworm/man2/ioctl.2 @@ -0,0 +1,186 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)ioctl.2 6.4 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> +.\" 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-02-05 "Linux man-pages 6.03" +.SH NAME +ioctl \- control device +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.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 +.fi +.SH DESCRIPTION +The +.BR ioctl () +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. +The argument +.I fd +must be an open file descriptor. +.PP +The second argument is a device-dependent request 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 +An +.BR ioctl () +.I request +has encoded in it whether the argument is an +.I in +parameter or +.I out +parameter, and the size of the argument +.I argp +in bytes. +Macros and defines used in specifying an +.BR ioctl () +.I request +are located in the file +.IR <sys/ioctl.h> . +See NOTES. +.SH RETURN VALUE +Usually, on success zero is returned. +A few +.BR ioctl () +requests use the return value as an output parameter +and return a nonnegative value on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.B EFAULT +.I argp +references an inaccessible memory area. +.TP +.B EINVAL +.I request +or +.I argp +is not valid. +.TP +.B ENOTTY +.I fd +is not associated with a character special device. +.TP +.B ENOTTY +The specified request does not apply to the kind of object that the +file descriptor +.I fd +references. +.SH STANDARDS +No single standard. +Arguments, returns, and semantics of +.BR ioctl () +vary according to the device driver in question (the call is used as a +catch-all for operations that don't cleanly fit the UNIX stream I/O +model). +.PP +The +.BR ioctl () +system call appeared in Version 7 AT&T UNIX. +.SH NOTES +In order to use this call, one needs an open file descriptor. +Often the +.BR open (2) +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 = \[aq]T\[aq] indicating the terminal driver, and +.B CYGETTIMEOUT +has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[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), +.BR ioctl_console (2), +.BR ioctl_fat (2), +.BR ioctl_ficlone (2), +.BR ioctl_ficlonerange (2), +.BR ioctl_fideduperange (2), +.BR ioctl_fslabel (2), +.BR ioctl_getfsmap (2), +.BR ioctl_iflags (2), +.BR ioctl_ns (2), +.BR ioctl_tty (2), +.BR ioctl_userfaultfd (2), +.BR open (2), +.\" .BR mt (4), +.BR sd (4), +.BR tty (4) |