summaryrefslogtreecommitdiffstats
path: root/man2/ioctl.2
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man2/ioctl.2185
1 files changed, 185 insertions, 0 deletions
diff --git a/man2/ioctl.2 b/man2/ioctl.2
new file mode 100644
index 0000000..d6c0701
--- /dev/null
+++ b/man2/ioctl.2
@@ -0,0 +1,185 @@
+.\" 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-03-30 "Linux man-pages 6.05.01"
+.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 VERSIONS
+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).
+.SH STANDARDS
+None.
+.SH HISTORY
+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)