1 .\" $NetBSD: ioctl.9,v 1.26 2008/11/12 12:35:54 ad Exp $
3 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Heiko W.Rupp <hwr@pilhuhn.de>
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
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.
39 .Nd "how to implement a new ioctl call to access device drivers"
44 .Fn ioctl "int d" "unsigned long request" "..."
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
55 Ioctls are defined as:
57 #define MYDEVIOCTL fun(g, n, t)
60 where the different symbols correspond to:
61 .Bl -tag -width ".Dv MYDEVIOCTL"
63 The name which will later be given in the
65 system call as second argument, e.g.,
67 ioctl(fd, MYDEVIOCTL, ...)
70 A macro which can be one of:
71 .Bl -tag -width ".Fn _IOWR"
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.
76 The call only reads parameters from the kernel and does not
79 The call only writes parameters to the kernel, but does not want anything
82 The call writes data to the kernel and wants information back.
85 We always consider reading or writing to the kernel, from the user perspective.
87 This integer describes to which subsystem the ioctl applies.
88 Here are some examples:
90 .Bl -tag -width xxxxx -compact
106 generic file-descriptor
144 random number generator
161 This number uniquely identifies the ioctl within the group.
162 That said, two subsystems may share the same
164 but there may be only one
168 This is an unsigned 8 bit number.
170 This specifies the type of the passed parameter.
171 This one gets internally transformed to the size of the parameter, so
172 for example, if you want to pass a structure, then you have to specify that
173 structure and not a pointer to it or sizeof(struct MYDEV).
176 In order for the new ioctl to be visible to the system, it is installed
178 .In sys/ioctl.h or one of the files that are reached from
181 A distinction must be made at this point.
186 should return either 0 for success
187 or a defined error code, as described in
189 At the libc level though a conversion takes place, so that eventually
191 returns either 0 for success or -1 for failure, in which case the
193 variable is set accordingly.
195 The use of magic numbers such as -1, to indicate that a given ioctl
196 code was not handled, is strongly discouraged.
197 The value -1 is bound to the
199 pseudo-error, which is returned inside kernel to modify return to process.
201 Let's suppose that we want to pass an integer value to the kernel.
202 From the user point of view, this is like writing to the kernel.
203 So we define the ioctl as:
204 .Bd -literal -offset indent
205 #define MYDEVIOCTL _IOW('i', 25, int)
210 routine of the driver, it can be then accessed like:
211 .Bd -literal -offset indent
213 mydev_ioctl(struct dev_ioctl_args *ap)
221 kprintf("Value passed from userspace: %d\\n", *a);
222 return (0); /* Success */
225 /* Handle other ioctls here */
228 /* Inappropriate ioctl for device */
238 .Bd -literal -offset indent
240 if (ioctl(fd, MYDEVIOCTL, \*[Am]a) == -1) {