]>
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 | .\" | |
1d767b55 | 13 | .TH IOCTL 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
fea681da MK |
14 | .SH NAME |
15 | ioctl \- control device | |
16 | .SH SYNOPSIS | |
c7db92b9 | 17 | .nf |
fea681da | 18 | .B #include <sys/ioctl.h> |
68e4db0a | 19 | .PP |
b7670bdd | 20 | .BI "int ioctl(int " fd ", unsigned long " request ", ...);" |
82f955d2 MK |
21 | .\" POSIX says 'request' is int, but glibc has the above |
22 | .\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705 | |
c7db92b9 | 23 | .fi |
fea681da MK |
24 | .SH DESCRIPTION |
25 | The | |
e511ffb6 | 26 | .BR ioctl () |
79c064f2 | 27 | system call manipulates the underlying device parameters of special files. |
c13182ef | 28 | In particular, many operating characteristics of character special files |
75b94dc3 | 29 | (e.g., terminals) may be controlled with |
e511ffb6 | 30 | .BR ioctl () |
c13182ef MK |
31 | requests. |
32 | The argument | |
b7670bdd | 33 | .I fd |
fea681da MK |
34 | must be an open file descriptor. |
35 | .PP | |
c13182ef MK |
36 | The second argument is a device-dependent request code. |
37 | The third argument is an untyped pointer to memory. | |
38 | It's traditionally | |
fea681da MK |
39 | .BI "char *" argp |
40 | (from the days before | |
41 | .B "void *" | |
42 | was valid C), and will be so named for this discussion. | |
43 | .PP | |
c13182ef | 44 | An |
1e321034 | 45 | .BR ioctl () |
fea681da MK |
46 | .I request |
47 | has encoded in it whether the argument is an | |
48 | .I in | |
49 | parameter or | |
50 | .I out | |
51 | parameter, and the size of the argument | |
52 | .I argp | |
c13182ef MK |
53 | in bytes. |
54 | Macros and defines used in specifying an | |
1e321034 | 55 | .BR ioctl () |
fea681da MK |
56 | .I request |
57 | are located in the file | |
58 | .IR <sys/ioctl.h> . | |
91b00e53 | 59 | See NOTES. |
47297adb | 60 | .SH RETURN VALUE |
fea681da | 61 | Usually, on success zero is returned. |
c13182ef | 62 | A few |
1e321034 MK |
63 | .BR ioctl () |
64 | requests use the return value as an output parameter | |
2fda57bd | 65 | and return a nonnegative value on success. |
fea681da MK |
66 | On error, \-1 is returned, and |
67 | .I errno | |
f6a4078b | 68 | is set to indicate the error. |
fea681da | 69 | .SH ERRORS |
0019177e | 70 | .TP |
fea681da | 71 | .B EBADF |
b7670bdd | 72 | .I fd |
d9cb0d7d | 73 | is not a valid file descriptor. |
fea681da MK |
74 | .TP |
75 | .B EFAULT | |
76 | .I argp | |
77 | references an inaccessible memory area. | |
78 | .TP | |
79 | .B EINVAL | |
db122bbd | 80 | .I request |
fea681da MK |
81 | or |
82 | .I argp | |
83 | is not valid. | |
84 | .TP | |
85 | .B ENOTTY | |
b7670bdd | 86 | .I fd |
fea681da MK |
87 | is not associated with a character special device. |
88 | .TP | |
89 | .B ENOTTY | |
90 | The specified request does not apply to the kind of object that the | |
d9cb0d7d | 91 | file descriptor |
b7670bdd | 92 | .I fd |
fea681da | 93 | references. |
a1d5f77c | 94 | .SH CONFORMING TO |
c13182ef | 95 | No single standard. |
97c1eac8 | 96 | Arguments, returns, and semantics of |
2777b1ca | 97 | .BR ioctl () |
fea681da | 98 | vary according to the device driver in question (the call is used as a |
008f1ecc | 99 | catch-all for operations that don't cleanly fit the UNIX stream I/O |
c13182ef | 100 | model). |
599e0cef | 101 | .PP |
97c1eac8 | 102 | The |
e511ffb6 | 103 | .BR ioctl () |
79c064f2 | 104 | system call appeared in Version 7 AT&T UNIX. |
a1d5f77c MK |
105 | .SH NOTES |
106 | In order to use this call, one needs an open file descriptor. | |
107 | Often the | |
108 | .BR open (2) | |
109 | call has unwanted side effects, that can be avoided under Linux | |
682edefb | 110 | by giving it the |
0daa9e92 | 111 | .B O_NONBLOCK |
682edefb | 112 | flag. |
91b00e53 MK |
113 | .\" |
114 | .SS ioctl structure | |
115 | .\" added two sections - aeb | |
116 | Ioctl command values are 32-bit constants. | |
117 | In principle these constants are completely arbitrary, but people have | |
118 | tried to build some structure into them. | |
119 | .PP | |
120 | The old Linux situation was that of mostly 16-bit constants, where the | |
121 | last byte is a serial number, and the preceding byte(s) give a type | |
122 | indicating the driver. | |
123 | Sometimes the major number was used: 0x03 | |
124 | for the | |
125 | .B HDIO_* | |
126 | ioctls, 0x06 for the | |
127 | .B LP* | |
128 | ioctls. | |
129 | And sometimes | |
130 | one or more ASCII letters were used. | |
131 | For example, | |
132 | .B TCGETS | |
133 | has value | |
134 | 0x00005401, with 0x54 = \(aqT\(aq indicating the terminal driver, and | |
135 | .B CYGETTIMEOUT | |
136 | has value 0x00435906, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq | |
137 | indicating the cyclades driver. | |
138 | .PP | |
139 | Later (0.98p5) some more information was built into the number. | |
140 | One has 2 direction bits | |
141 | (00: none, 01: write, 10: read, 11: read/write) | |
142 | followed by 14 size bits (giving the size of the argument), | |
143 | followed by an 8-bit type (collecting the ioctls in groups | |
144 | for a common purpose or a common driver), and an 8-bit | |
145 | serial number. | |
146 | .PP | |
147 | The macros describing this structure live in | |
148 | .I <asm/ioctl.h> | |
149 | and are | |
150 | .B _IO(type,nr) | |
151 | and | |
152 | .BR "{_IOR,_IOW,_IOWR}(type,nr,size)" . | |
153 | They use | |
154 | .I sizeof(size) | |
155 | so that size is a | |
156 | misnomer here: this third argument is a data type. | |
157 | .PP | |
158 | Note that the size bits are very unreliable: in lots of cases | |
159 | they are wrong, either because of buggy macros using | |
160 | .IR sizeof(sizeof(struct)) , | |
161 | or because of legacy values. | |
162 | .PP | |
163 | Thus, it seems that the new structure only gave disadvantages: | |
164 | it does not help in checking, but it causes varying values | |
165 | for the various architectures. | |
47297adb | 166 | .SH SEE ALSO |
fea681da MK |
167 | .BR execve (2), |
168 | .BR fcntl (2), | |
d49a2220 | 169 | .BR ioctl_console (2), |
68232827 | 170 | .BR ioctl_fat (2), |
7288143c | 171 | .BR ioctl_ficlone (2), |
49c3367c | 172 | .BR ioctl_ficlonerange (2), |
6a68ffd7 | 173 | .BR ioctl_fideduperange (2), |
407dd5e4 | 174 | .BR ioctl_fslabel (2), |
cef01dbc | 175 | .BR ioctl_getfsmap (2), |
45909100 | 176 | .BR ioctl_iflags (2), |
2ea8ee2c | 177 | .BR ioctl_ns (2), |
a9168840 | 178 | .BR ioctl_tty (2), |
b0fab7d7 | 179 | .BR ioctl_userfaultfd (2), |
fea681da | 180 | .BR open (2), |
0f5ccfc8 | 181 | .\" .BR mt (4), |
fea681da | 182 | .BR sd (4), |
a9168840 | 183 | .BR tty (4) |