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