| blob | 5b8c28a9c42154202f7d726c3ca6ca121b269877 |
1 .\" Copyright (c) 1980, 1991 Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
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 .\"
13 .TH ioctl 2 (date) "Linux man-pages (unreleased)"
14 .SH NAME
15 ioctl \- control device
16 .SH LIBRARY
17 Standard C library
18 .RI ( libc ", " \-lc )
19 .SH SYNOPSIS
20 .nf
21 .B #include <sys/ioctl.h>
22 .P
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[]"
25 .fi
26 .SH DESCRIPTION
27 The
28 .BR ioctl ()
29 system call manipulates the underlying device parameters of special files.
30 In particular, many operating characteristics of character special files
31 (e.g., terminals) may be controlled with
32 .BR ioctl ()
33 operations.
34 The argument
35 .I fd
36 must be an open file descriptor.
37 .P
38 The second argument is a device-dependent operation code.
39 The third argument is an untyped pointer to memory.
40 It's traditionally
41 .BI "char *" argp
42 (from the days before
43 .B "void *"
44 was valid C), and will be so named for this discussion.
45 .P
46 An
47 .BR ioctl ()
48 .I op
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
55 in bytes.
56 Macros and defines used in specifying an
57 .BR ioctl ()
58 .I op
59 are located in the file
60 .IR <sys/ioctl.h> .
61 See NOTES.
62 .SH RETURN VALUE
63 Usually, on success zero is returned.
64 A few
65 .BR ioctl ()
66 operations use the return value as an output parameter
67 and return a nonnegative value on success.
68 On error, \-1 is returned, and
69 .I errno
70 is set to indicate the error.
71 .SH ERRORS
72 .TP
73 .B EBADF
74 .I fd
75 is not a valid file descriptor.
76 .TP
77 .B EFAULT
78 .I argp
79 references an inaccessible memory area.
80 .TP
81 .B EINVAL
82 .I op
83 or
84 .I argp
85 is not valid.
86 .TP
87 .B ENOTTY
88 .I fd
89 is not associated with a character special device.
90 .TP
91 .B ENOTTY
92 The specified operation does not apply to the kind of object that the
93 file descriptor
94 .I fd
95 references.
96 .SH VERSIONS
97 Arguments, returns, and semantics of
98 .BR ioctl ()
99 vary according to the device driver in question (the call is used as a
100 catch-all for operations that don't cleanly fit the UNIX stream I/O
101 model).
102 .SH STANDARDS
103 None.
104 .SH HISTORY
105 Version\~7 AT&T UNIX has
106 .PD 0
107 .in +4n
108 .nf
109 .BI "ioctl(int " fildes ", int " op ", struct sgttyb *" argp );
110 .fi
111 .in
112 .P
113 .PD
114 (where
115 .B struct sgttyb
116 has historically been used by
117 .BR stty (2)
118 and
119 .BR gtty (2),
120 and is polymorphic by operation type (like a
121 .B void *
122 would be, if it had been available)).
123 .P
124 SysIII documents
125 .I arg
126 without a type at all.
127 .P
128 4.3BSD has
129 .PD 0
130 .in +4n
131 .nf
132 .BI "ioctl(int " d ", unsigned long " op ", char *" argp );
133 .fi
134 .in
135 .P
136 .PD
137 (with
138 .B char *
139 similarly in for
140 .BR "void *" ).
141 .P
142 SysVr4 has
143 .PD 0
144 .in +4n
145 .nf
146 .BI "int ioctl(int " fildes ", int " op ", ... /* " arg " */);"
147 .fi
148 .in
149 .P
150 .PD
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
156 by giving it the
157 .B O_NONBLOCK
158 flag.
159 .\"
160 .SS ioctl structure
161 .\" added two sections - aeb
162 Ioctl
163 .I op
164 values are 32-bit constants.
165 In principle these constants are completely arbitrary, but people have
166 tried to build some structure into them.
167 .P
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
182 0x00005401, with 0x54 = \[aq]T\[aq] indicating the terminal driver, and
183 .B CYGETTIMEOUT
184 has value 0x00435906, with 0x43 0x59 = \[aq]C\[aq] \[aq]Y\[aq]
185 indicating the cyclades driver.
186 .P
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.
194 .P
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.
205 .P
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.
210 .P
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.
214 .SH SEE ALSO
215 .BR execve (2),
216 .BR fcntl (2),
217 .BR ioctl_console (2),
218 .BR ioctl_fat (2),
219 .BR ioctl_ficlone (2),
220 .BR ioctl_ficlonerange (2),
221 .BR ioctl_fideduperange (2),
222 .BR ioctl_fslabel (2),
223 .BR ioctl_getfsmap (2),
224 .BR ioctl_iflags (2),
225 .BR ioctl_ns (2),
226 .BR ioctl_tty (2),
227 .BR ioctl_userfaultfd (2),
228 .BR open (2),
229 .\" .BR mt (4),
230 .BR sd (4),
231 .BR tty (4)