Commit | Line | Data |
---|---|---|
f93b9c36 SW |
1 | .\" $NetBSD: ioctl.9,v 1.26 2008/11/12 12:35:54 ad Exp $ |
2 | .\" | |
3 | .\" Copyright (c) 1999 The NetBSD Foundation, Inc. | |
4 | .\" All rights reserved. | |
5 | .\" | |
6 | .\" This code is derived from software contributed to The NetBSD Foundation | |
7 | .\" by Heiko W.Rupp <hwr@pilhuhn.de> | |
8 | .\" | |
9 | .\" Redistribution and use in source and binary forms, with or without | |
10 | .\" modification, are permitted provided that the following conditions | |
11 | .\" are met: | |
12 | .\" 1. Redistributions of source code must retain the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer. | |
14 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
15 | .\" notice, this list of conditions and the following disclaimer in the | |
16 | .\" documentation and/or other materials provided with the distribution. | |
17 | .\" | |
18 | .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS | |
19 | .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED | |
20 | .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | |
21 | .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS | |
22 | .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
23 | .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
24 | .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
25 | .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
26 | .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
27 | .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |
28 | .\" POSSIBILITY OF SUCH DAMAGE. | |
29 | .\" | |
82b0523a | 30 | .Dd October 4, 2018 |
f93b9c36 SW |
31 | .Dt IOCTL 9 |
32 | .Os | |
33 | .Sh NAME | |
34 | .Nm ioctl , | |
35 | .Nm _IO , | |
36 | .Nm _IOR , | |
37 | .Nm _IOW , | |
38 | .Nm _IOWR | |
39 | .Nd "how to implement a new ioctl call to access device drivers" | |
40 | .Sh SYNOPSIS | |
f93b9c36 | 41 | .In sys/ioccom.h |
f93b9c36 SW |
42 | .Fn _IO "g" "t" |
43 | .Fn _IOR "g" "n" "t" | |
44 | .Fn _IOW "g" "n" "t" | |
45 | .Fn _IOWR "g" "n" "t" | |
46 | .Sh DESCRIPTION | |
47 | Whenever an | |
48 | .Xr ioctl 2 | |
49 | call is made, the kernel dispatches it to the device driver | |
50 | which can then interpret the request number and data in a specialized | |
51 | manner. | |
52 | Ioctls are defined as: | |
f93b9c36 SW |
53 | .Bd -literal |
54 | #define MYDEVIOCTL fun(g, n, t) | |
55 | .Ed | |
56 | .Pp | |
57 | where the different symbols correspond to: | |
58 | .Bl -tag -width ".Dv MYDEVIOCTL" | |
59 | .It Dv MYDEVIOCTL | |
60 | The name which will later be given in the | |
61 | .Xr ioctl 2 | |
62 | system call as second argument, e.g., | |
63 | .Bd -literal | |
64 | ioctl(fd, MYDEVIOCTL, ...) | |
65 | .Ed | |
66 | .It Fn fun | |
67 | A macro which can be one of: | |
68 | .Bl -tag -width ".Fn _IOWR" | |
31524921 | 69 | .It Fn _IO |
f93b9c36 SW |
70 | The call is a simple message to the kernel by itself. |
71 | It does not copy anything into the kernel, nor does it want anything back. | |
72 | .It Fn _IOR | |
73 | The call only reads parameters from the kernel and does not | |
74 | pass any to it. | |
75 | .It Fn _IOW | |
76 | The call only writes parameters to the kernel, but does not want anything | |
77 | back. | |
78 | .It Fn _IOWR | |
79 | The call writes data to the kernel and wants information back. | |
80 | .El | |
81 | .Pp | |
82 | We always consider reading or writing to the kernel, from the user perspective. | |
83 | .It Fa g | |
84 | This integer describes to which subsystem the ioctl applies. | |
85 | Here are some examples: | |
86 | .Pp | |
87 | .Bl -tag -width xxxxx -compact | |
f685c57d SW |
88 | .It '8' |
89 | .Xr aac 4 | |
f93b9c36 SW |
90 | .It 'a' |
91 | .Xr nata 4 | |
f685c57d | 92 | .It 'B' |
f93b9c36 | 93 | .Xr bpf 4 |
f685c57d | 94 | .It 'C' |
1501e71c SW |
95 | .Xr cam 4 |
96 | .It 'C' | |
f685c57d SW |
97 | .Xr ciss 4 |
98 | .It 'd' | |
99 | .Xr disklabel 5 | |
100 | .It 'd' | |
101 | diskslice | |
8970d9e9 SW |
102 | .It 'd' |
103 | .Xr drm 4 | |
f685c57d SW |
104 | .It 'f' |
105 | generic file-descriptor | |
106 | .It 'F' | |
107 | frame buffer | |
f93b9c36 SW |
108 | .It 'h' |
109 | .Xr HAMMER 5 | |
f685c57d SW |
110 | .It 'i' |
111 | .Xr iic 4 | |
112 | .It 'i' | |
113 | .Xr carp 4 | |
114 | .It 'i' | |
115 | .Xr gre 4 | |
116 | .It 'k' | |
117 | .Xr keyboard 4 | |
118 | and | |
119 | .Xr syscons 4 | |
120 | .It 'm' | |
121 | .Xr mem 4 | |
122 | .It 'm' | |
123 | .Pa /dev/midi | |
124 | .It 'm' | |
125 | .Xr mtio 4 | |
8970d9e9 SW |
126 | .It 'M' |
127 | .Xr sound 4 | |
128 | mixer | |
f685c57d SW |
129 | .It 'n' |
130 | .Xr smb 4 | |
f685c57d SW |
131 | .It 'p' |
132 | .Pa /dev/dsp | |
133 | and | |
134 | .Pa /dev/audio | |
135 | .It 'p' | |
136 | .Xr pci 4 | |
137 | .It 'p' | |
138 | .Xr ppbus 4 | |
d0981ce5 SW |
139 | .It 'p' |
140 | .Xr procfs 5 | |
f685c57d SW |
141 | .It 'q' |
142 | .Pa /dev/sequencer | |
143 | .It 'r' | |
f685c57d | 144 | random number generator |
f93b9c36 | 145 | .It 't' |
f685c57d SW |
146 | .Xr tty 4 |
147 | .It 't' | |
f685c57d SW |
148 | .Xr tap 4 |
149 | .It 't' | |
150 | .Xr tun 4 | |
151 | .It 't' | |
152 | SLIP ttys | |
153 | .It 'T' | |
154 | .Xr snp 4 | |
f93b9c36 SW |
155 | .El |
156 | .It Fa n | |
157 | This number uniquely identifies the ioctl within the group. | |
158 | That said, two subsystems may share the same | |
159 | .Fa g , | |
160 | but there may be only one | |
161 | .Fa n | |
162 | for a given | |
163 | .Fa g . | |
164 | This is an unsigned 8 bit number. | |
165 | .It Fa t | |
166 | This specifies the type of the passed parameter. | |
167 | This one gets internally transformed to the size of the parameter, so | |
168 | for example, if you want to pass a structure, then you have to specify that | |
169 | structure and not a pointer to it or sizeof(struct MYDEV). | |
170 | .El | |
171 | .Pp | |
172 | In order for the new ioctl to be visible to the system, it is installed | |
173 | in either | |
174 | .In sys/ioctl.h or one of the files that are reached from | |
175 | .In sys/ioctl.h . | |
a68e0df0 SW |
176 | .Sh RETURN VALUES |
177 | A distinction must be made at this point. | |
178 | All | |
179 | .Fn *_ioctl | |
180 | routines from | |
181 | .Em within kernel | |
182 | should return either 0 for success | |
183 | or a defined error code, as described in | |
184 | .In sys/errno.h . | |
185 | At the libc level though a conversion takes place, so that eventually | |
186 | .Xr ioctl 2 | |
187 | returns either 0 for success or -1 for failure, in which case the | |
188 | .Va errno | |
189 | variable is set accordingly. | |
190 | .Pp | |
191 | The use of magic numbers such as -1, to indicate that a given ioctl | |
192 | code was not handled, is strongly discouraged. | |
193 | The value -1 is bound to the | |
194 | .Er ERESTART | |
195 | pseudo-error, which is returned inside kernel to modify return to process. | |
f93b9c36 SW |
196 | .Sh EXAMPLES |
197 | Let's suppose that we want to pass an integer value to the kernel. | |
198 | From the user point of view, this is like writing to the kernel. | |
199 | So we define the ioctl as: | |
200 | .Bd -literal -offset indent | |
201 | #define MYDEVIOCTL _IOW('i', 25, int) | |
202 | .Ed | |
203 | .Pp | |
204 | Within the | |
205 | .Fn *_ioctl | |
206 | routine of the driver, it can be then accessed like: | |
207 | .Bd -literal -offset indent | |
208 | int | |
f685c57d | 209 | mydev_ioctl(struct dev_ioctl_args *ap) |
f93b9c36 SW |
210 | { |
211 | int error; | |
212 | int *a; | |
213 | ||
214 | switch (ap->a_cmd) { | |
215 | case MYDEVIOCTL: | |
216 | a = (int *)ap->data; | |
217 | kprintf("Value passed from userspace: %d\\n", *a); | |
218 | return (0); /* Success */ | |
219 | break; | |
220 | ||
221 | /* Handle other ioctls here */ | |
222 | ||
223 | default: | |
224 | /* Inappropriate ioctl for device */ | |
225 | error = ENOTTY; | |
226 | break; | |
227 | } | |
228 | ||
229 | return (error); | |
230 | } | |
231 | .Ed | |
232 | .Pp | |
233 | In userspace: | |
234 | .Bd -literal -offset indent | |
235 | int a = 101; | |
236 | if (ioctl(fd, MYDEVIOCTL, \*[Am]a) == -1) { | |
237 | /* Handle failure */ | |
238 | } | |
239 | .Ed | |
f93b9c36 SW |
240 | .Sh SEE ALSO |
241 | .Xr ioctl 2 |