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