7f5d84a942f243c02c33769a26e4b15660520a38
[dragonfly.git] / share / man / man9 / ioctl.9
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 .\"
30 .Dd February 27, 2009
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
41 .In sys/ioctl.h
42 .In sys/ioccom.h
43 .Ft int
44 .Fn ioctl "int d" "unsigned long request" "..."
45 .Fn _IO "g" "t"
46 .Fn _IOR "g" "n" "t"
47 .Fn _IOW "g" "n" "t"
48 .Fn _IOWR "g" "n" "t"
49 .Sh DESCRIPTION
50 Whenever an
51 .Xr ioctl 2
52 call is made, the kernel dispatches it to the device driver
53 which can then interpret the request number and data in a specialized
54 manner.
55 Ioctls are defined as:
56 .Bd -literal
57 #define MYDEVIOCTL   fun(g, n, t)
58 .Ed
59 .Pp
60 where the different symbols correspond to:
61 .Bl -tag -width ".Dv MYDEVIOCTL"
62 .It Dv MYDEVIOCTL
63 The name which will later be given in the
64 .Xr ioctl 2
65 system call as second argument, e.g.,
66 .Bd -literal
67 ioctl(fd, MYDEVIOCTL, ...)
68 .Ed
69 .It Fn fun
70 A macro which can be one of:
71 .Bl -tag -width ".Fn _IOWR"
72 .It Fn  _IO
73 The call is a simple message to the kernel by itself.
74 It does not copy anything into the kernel, nor does it want anything back.
75 .It Fn _IOR
76 The call only reads parameters from the kernel and does not
77 pass any to it.
78 .It Fn _IOW
79 The call only writes parameters to the kernel, but does not want anything
80 back.
81 .It Fn _IOWR
82 The call writes data to the kernel and wants information back.
83 .El
84 .Pp
85 We always consider reading or writing to the kernel, from the user perspective.
86 .It Fa g
87 This integer describes to which subsystem the ioctl applies.
88 Here are some examples:
89 .Pp
90 .Bl -tag -width xxxxx -compact
91 .It '5'
92 .Xr perfmon 4
93 .It '8'
94 .Xr aac 4
95 .It 'a'
96 .Xr nata 4
97 .It 'B'
98 .Xr bpf 4
99 .It 'C'
100 .Xr ciss 4
101 .It 'd'
102 .Xr disklabel 5
103 .It 'd'
104 diskslice
105 .It 'f'
106 generic file-descriptor
107 .It 'F'
108 frame buffer
109 .It 'h'
110 .Xr HAMMER 5
111 .It 'i'
112 .Xr iic 4
113 .It 'i'
114 .Xr carp 4
115 .It 'i'
116 .Xr gre 4
117 .It 'k'
118 .Xr keyboard 4
119 and
120 .Xr syscons 4
121 .It 'm'
122 .Xr mem 4
123 .It 'm'
124 .Pa /dev/midi
125 .It 'm'
126 .Xr mtio 4
127 .It 'n'
128 .Xr smb 4
129 .It 'n'
130 NetWare volume mount
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
139 .It 'P'
140 .Xr apm 4
141 .It 'q'
142 .Pa /dev/sequencer
143 .It 'r'
144 .Xr ipf 4
145 .It 'r'
146 random number generator
147 .It 't'
148 .Xr tty 4
149 .It 't'
150 .Xr ppp 4
151 .It 't'
152 .Xr tap 4
153 .It 't'
154 .Xr tun 4
155 .It 't'
156 SLIP ttys
157 .It 'T'
158 .Xr snp 4
159 .\".It 'V'
160 .\"VMware
161 .El
162 .It Fa n
163 This number uniquely identifies the ioctl within the group.
164 That said, two subsystems may share the same
165 .Fa g ,
166 but there may be only one
167 .Fa n
168 for a given
169 .Fa g .
170 This is an unsigned 8 bit number.
171 .It Fa t
172 This specifies the type of the passed parameter.
173 This one gets internally transformed to the size of the parameter, so
174 for example, if you want to pass a structure, then you have to specify that
175 structure and not a pointer to it or sizeof(struct MYDEV).
176 .El
177 .Pp
178 In order for the new ioctl to be visible to the system, it is installed
179 in either
180 .In sys/ioctl.h or one of the files that are reached from
181 .In sys/ioctl.h .
182 .Sh EXAMPLES
183 Let's suppose that we want to pass an integer value to the kernel.
184 From the user point of view, this is like writing to the kernel.
185 So we define the ioctl as:
186 .Bd -literal -offset indent
187 #define MYDEVIOCTL      _IOW('i', 25, int)
188 .Ed
189 .Pp
190 Within the
191 .Fn *_ioctl
192 routine of the driver, it can be then accessed like:
193 .Bd -literal -offset indent
194 int
195 mydev_ioctl(struct dev_ioctl_args *ap)
196 {
197         int error;
198         int *a;
199
200         switch (ap->a_cmd) {
201         case MYDEVIOCTL:
202                 a = (int *)ap->data;
203                 kprintf("Value passed from userspace: %d\\n", *a);
204                 return (0);    /* Success */
205                 break;
206
207         /* Handle other ioctls here */
208
209         default:
210                 /* Inappropriate ioctl for device */
211                 error = ENOTTY;
212                 break;
213         }
214
215         return (error);
216 }
217 .Ed
218 .Pp
219 In userspace:
220 .Bd -literal -offset indent
221 int a = 101;
222 if (ioctl(fd, MYDEVIOCTL, \*[Am]a) == -1) {
223         /* Handle failure */
224 }
225 .Ed
226 .Sh RETURN VALUES
227 A distinction must be made at this point.
228 All
229 .Fn *_ioctl
230 routines from
231 .Em within kernel
232 should return either 0 for success
233 or a defined error code, as described in
234 .In sys/errno.h .
235 At the libc level though a conversion takes place, so that eventually
236 .Xr ioctl 2
237 returns either 0 for success or -1 for failure, in which case the
238 .Va errno
239 variable is set accordingly.
240 .Pp
241 The use of magic numbers such as -1, to indicate that a given ioctl
242 code was not handled, is strongly discouraged.
243 The value -1 is bound to the
244 .Er ERESTART
245 pseudo-error, which is returned inside kernel to modify return to process.
246 .Sh SEE ALSO
247 .Xr ioctl 2