Debian Codegraph @

upstream/debian-unstable/man2/ioctl.2

raw
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)