| 1 |
.\" Copyright 1980-1991, Regents of the University of California. |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: BSD-4-Clause-UC |
| 5 |
.\" |
| 6 |
.TH ioctl 2 2025-09-21 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
ioctl \- control device |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B #include <sys/ioctl.h> |
| 15 |
.P |
| 16 |
.BI "int ioctl(int " fd ", unsigned long " op ", ...);" "\f[R] /* glibc, BSD */\f[]" |
| 17 |
.BI "int ioctl(int " fd ", int " op ", ...);" "\f[R] /* musl, other UNIX */\f[]" |
| 18 |
.fi |
| 19 |
.SH DESCRIPTION |
| 20 |
The |
| 21 |
.BR ioctl () |
| 22 |
system call manipulates the underlying device parameters of special files. |
| 23 |
In particular, many operating characteristics of character special files |
| 24 |
(e.g., terminals) may be controlled with |
| 25 |
.BR ioctl () |
| 26 |
operations. |
| 27 |
The argument |
| 28 |
.I fd |
| 29 |
must be an open file descriptor. |
| 30 |
.P |
| 31 |
The second argument is a device-dependent operation code. |
| 32 |
The third argument is an untyped pointer to memory. |
| 33 |
It's traditionally |
| 34 |
.BI "char *" argp |
| 35 |
(from the days before |
| 36 |
.B "void *" |
| 37 |
was valid C), and will be so named for this discussion. |
| 38 |
.P |
| 39 |
An |
| 40 |
.BR ioctl () |
| 41 |
.I op |
| 42 |
has encoded in it whether the argument is an |
| 43 |
.I in |
| 44 |
parameter or |
| 45 |
.I out |
| 46 |
parameter, and the size of the argument |
| 47 |
.I argp |
| 48 |
in bytes. |
| 49 |
Macros and defines used in specifying an |
| 50 |
.BR ioctl () |
| 51 |
.I op |
| 52 |
are located in the file |
| 53 |
.IR <sys/ioctl.h> . |
| 54 |
See NOTES. |
| 55 |
.SH RETURN VALUE |
| 56 |
Usually, on success zero is returned. |
| 57 |
A few |
| 58 |
.BR ioctl () |
| 59 |
operations use the return value as an output parameter |
| 60 |
and return a nonnegative value on success. |
| 61 |
On error, \-1 is returned, and |
| 62 |
.I errno |
| 63 |
is set to indicate the error. |
| 64 |
.SH ERRORS |
| 65 |
.TP |
| 66 |
.B EBADF |
| 67 |
.I fd |
| 68 |
is not a valid file descriptor. |
| 69 |
.TP |
| 70 |
.B EFAULT |
| 71 |
.I argp |
| 72 |
references an inaccessible memory area. |
| 73 |
.TP |
| 74 |
.B EINVAL |
| 75 |
.I op |
| 76 |
or |
| 77 |
.I argp |
| 78 |
is not valid. |
| 79 |
.TP |
| 80 |
.B ENOTTY |
| 81 |
.I fd |
| 82 |
is not associated with a character special device. |
| 83 |
.TP |
| 84 |
.B ENOTTY |
| 85 |
The specified operation does not apply to the kind of object that the |
| 86 |
file descriptor |
| 87 |
.I fd |
| 88 |
references. |
| 89 |
.SH VERSIONS |
| 90 |
Arguments, returns, and semantics of |
| 91 |
.BR ioctl () |
| 92 |
vary according to the device driver in question (the call is used as a |
| 93 |
catch-all for operations that don't cleanly fit the UNIX stream I/O |
| 94 |
model). |
| 95 |
.SH STANDARDS |
| 96 |
None. |
| 97 |
.SH HISTORY |
| 98 |
Version\~7 AT&T UNIX has |
| 99 |
.PD 0 |
| 100 |
.in +4n |
| 101 |
.nf |
| 102 |
.BI "ioctl(int " fd ", int " op ", struct sgttyb *" argp ); |
| 103 |
.fi |
| 104 |
.in |
| 105 |
.P |
| 106 |
.PD |
| 107 |
(where |
| 108 |
.B struct sgttyb |
| 109 |
has historically been used by |
| 110 |
.BR stty (2) |
| 111 |
and |
| 112 |
.BR gtty (2), |
| 113 |
and is polymorphic by operation type (like a |
| 114 |
.B void * |
| 115 |
would be, if it had been available)). |
| 116 |
.P |
| 117 |
SysIII documents |
| 118 |
.I arg |
| 119 |
without a type at all. |
| 120 |
.P |
| 121 |
4.3BSD has |
| 122 |
.PD 0 |
| 123 |
.in +4n |
| 124 |
.nf |
| 125 |
.BI "ioctl(int " d ", unsigned long " op ", char *" argp ); |
| 126 |
.fi |
| 127 |
.in |
| 128 |
.P |
| 129 |
.PD |
| 130 |
(with |
| 131 |
.B char * |
| 132 |
similarly in for |
| 133 |
.BR "void *" ). |
| 134 |
.P |
| 135 |
SysVr4 has |
| 136 |
.in +4n |
| 137 |
.nf |
| 138 |
.BI "int ioctl(int " fd ", int " op ", ... /* " arg " */);" |
| 139 |
.fi |
| 140 |
.in |
| 141 |
.SH NOTES |
| 142 |
In order to use this call, one needs an open file descriptor. |
| 143 |
Often the |
| 144 |
.BR open (2) |
| 145 |
call has unwanted side effects, that can be avoided under Linux |
| 146 |
by giving it the |
| 147 |
.B O_NONBLOCK |
| 148 |
flag. |
| 149 |
.\" |
| 150 |
.SS ioctl structure |
| 151 |
.\" added two sections - aeb |
| 152 |
Ioctl |
| 153 |
.I op |
| 154 |
values are 32-bit constants. |
| 155 |
In principle these constants are completely arbitrary, but people have |
| 156 |
tried to build some structure into them. |
| 157 |
.P |
| 158 |
The old Linux situation was that of mostly 16-bit constants, where the |
| 159 |
last byte is a serial number, and the preceding byte(s) give a type |
| 160 |
indicating the driver. |
| 161 |
Sometimes the major number was used: 0x03 |
| 162 |
for the |
| 163 |
.B HDIO_* |
| 164 |
ioctls, 0x06 for the |
| 165 |
.B LP* |
| 166 |
ioctls. |
| 167 |
And sometimes |
| 168 |
one or more ASCII letters were used. |
| 169 |
For example, |
| 170 |
.B TCGETS |
| 171 |
has value |
| 172 |
0x00005401, with 0x54 = \[aq]T\[aq] indicating the terminal driver, and |
| 173 |
.B CYGETTIMEOUT |
| 174 |
has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq] |
| 175 |
indicating the cyclades driver. |
| 176 |
.P |
| 177 |
Later (0.98p5) some more information was built into the number. |
| 178 |
One has 2 direction bits |
| 179 |
(00: none, 01: write, 10: read, 11: read/write) |
| 180 |
followed by 14 size bits (giving the size of the argument), |
| 181 |
followed by an 8-bit type (collecting the ioctls in groups |
| 182 |
for a common purpose or a common driver), and an 8-bit |
| 183 |
serial number. |
| 184 |
.P |
| 185 |
The macros describing this structure live in |
| 186 |
.I <asm/ioctl.h> |
| 187 |
and are |
| 188 |
.B _IO(type,nr) |
| 189 |
and |
| 190 |
.BR "{_IOR,_IOW,_IOWR}(type,nr,size)" . |
| 191 |
They use |
| 192 |
.I sizeof(size) |
| 193 |
so that size is a |
| 194 |
misnomer here: this third argument is a data type. |
| 195 |
.P |
| 196 |
Note that the size bits are very unreliable: in lots of cases |
| 197 |
they are wrong, either because of buggy macros using |
| 198 |
.IR sizeof(sizeof(struct)) , |
| 199 |
or because of legacy values. |
| 200 |
.P |
| 201 |
Thus, it seems that the new structure only gave disadvantages: |
| 202 |
it does not help in checking, but it causes varying values |
| 203 |
for the various architectures. |
| 204 |
.SH SEE ALSO |
| 205 |
.BR execve (2), |
| 206 |
.BR fcntl (2), |
| 207 |
.BR ioctl_console (2), |
| 208 |
.BR ioctl_fat (2), |
| 209 |
.BR ioctl_fs (2), |
| 210 |
.BR ioctl_fsmap (2), |
| 211 |
.BR ioctl_nsfs (2), |
| 212 |
.BR ioctl_tty (2), |
| 213 |
.BR ioctl_userfaultfd (2), |
| 214 |
.BR ioctl_eventpoll (2), |
| 215 |
.BR open (2), |
| 216 |
.\" .BR mt (4), |
| 217 |
.BR sd (4), |
| 218 |
.BR tty (4) |