1 .\" Copyright (c) 1980, 1991 Regents of the University of California.
2 .\" All rights reserved.
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\" @(#)ioctl.2 6.4 (Berkeley) 3/10/91
8 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
9 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
10 .\" Modified 1999-06-25 by Rachael Munns <vashti@dream.org.uk>
11 .\" Modified 2000-09-21 by Andries Brouwer <aeb@cwi.nl>
13 .TH IOCTL 2 2021-03-22 "Linux man-pages (unreleased)"
15 ioctl \- control device
18 .RI ( libc ", " \-lc )
21 .B #include <sys/ioctl.h>
23 .BI "int ioctl(int " fd ", unsigned long " request ", ...);"
24 .\" POSIX says 'request' is int, but glibc has the above
25 .\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705
30 system call manipulates the underlying device parameters of special files.
31 In particular, many operating characteristics of character special files
32 (e.g., terminals) may be controlled with
37 must be an open file descriptor.
39 The second argument is a device-dependent request code.
40 The third argument is an untyped pointer to memory.
45 was valid C), and will be so named for this discussion.
50 has encoded in it whether the argument is an
54 parameter, and the size of the argument
57 Macros and defines used in specifying an
60 are located in the file
64 Usually, on success zero is returned.
67 requests use the return value as an output parameter
68 and return a nonnegative value on success.
69 On error, \-1 is returned, and
71 is set to indicate the error.
76 is not a valid file descriptor.
80 references an inaccessible memory area.
90 is not associated with a character special device.
93 The specified request does not apply to the kind of object that the
99 Arguments, returns, and semantics of
101 vary according to the device driver in question (the call is used as a
102 catch-all for operations that don't cleanly fit the UNIX stream I/O
107 system call appeared in Version 7 AT&T UNIX.
109 In order to use this call, one needs an open file descriptor.
112 call has unwanted side effects, that can be avoided under Linux
118 .\" added two sections - aeb
119 Ioctl command values are 32-bit constants.
120 In principle these constants are completely arbitrary, but people have
121 tried to build some structure into them.
123 The old Linux situation was that of mostly 16-bit constants, where the
124 last byte is a serial number, and the preceding byte(s) give a type
125 indicating the driver.
126 Sometimes the major number was used: 0x03
133 one or more ASCII letters were used.
137 0x00005401, with 0x54 = \(aqT\(aq indicating the terminal driver, and
139 has value 0x00435906, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq
140 indicating the cyclades driver.
142 Later (0.98p5) some more information was built into the number.
143 One has 2 direction bits
144 (00: none, 01: write, 10: read, 11: read/write)
145 followed by 14 size bits (giving the size of the argument),
146 followed by an 8-bit type (collecting the ioctls in groups
147 for a common purpose or a common driver), and an 8-bit
150 The macros describing this structure live in
155 .BR "{_IOR,_IOW,_IOWR}(type,nr,size)" .
159 misnomer here: this third argument is a data type.
161 Note that the size bits are very unreliable: in lots of cases
162 they are wrong, either because of buggy macros using
163 .IR sizeof(sizeof(struct)) ,
164 or because of legacy values.
166 Thus, it seems that the new structure only gave disadvantages:
167 it does not help in checking, but it causes varying values
168 for the various architectures.
172 .BR ioctl_console (2),
174 .BR ioctl_ficlone (2),
175 .BR ioctl_ficlonerange (2),
176 .BR ioctl_fideduperange (2),
177 .BR ioctl_fslabel (2),
178 .BR ioctl_getfsmap (2),
179 .BR ioctl_iflags (2),
182 .BR ioctl_userfaultfd (2),