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