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 August 10, 2015
  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 'd'
 106 .Xr drm 4
 107 .It 'f'
 108 generic file-descriptor
 109 .It 'F'
 110 frame buffer
 111 .It 'h'
 112 .Xr HAMMER 5
 113 .It 'i'
 114 .Xr iic 4
 115 .It 'i'
 116 .Xr carp 4
 117 .It 'i'
 118 .Xr gre 4
 119 .It 'k'
 120 .Xr keyboard 4
 121 and
 122 .Xr syscons 4
 123 .It 'm'
 124 .Xr mem 4
 125 .It 'm'
 126 .Pa /dev/midi
 127 .It 'm'
 128 .Xr mtio 4
 129 .It 'M'
 130 .Xr sound 4
 131 mixer
 132 .It 'n'
 133 .Xr smb 4
 134 .It 'n'
 135 NetWare volume mount
 136 .It 'p'
 137 .Pa /dev/dsp
 138 and
 139 .Pa /dev/audio
 140 .It 'p'
 141 .Xr pci 4
 142 .It 'p'
 143 .Xr ppbus 4
 144 .It 'p'
 145 .Xr procfs 5
 146 .It 'P'
 147 .Nm apm (deprecated)
 148 .It 'q'
 149 .Pa /dev/sequencer
 150 .It 'r'
 151 random number generator
 152 .It 't'
 153 .Xr tty 4
 154 .It 't'
 155 .Xr ppp 4
 156 .It 't'
 157 .Xr tap 4
 158 .It 't'
 159 .Xr tun 4
 160 .It 't'
 161 SLIP ttys
 162 .It 'T'
 163 .Xr snp 4
 164 .\".It 'V'
 165 .\"VMware
 166 .El
 167 .It Fa n
 168 This number uniquely identifies the ioctl within the group.
 169 That said, two subsystems may share the same
 170 .Fa g ,
 171 but there may be only one
 172 .Fa n
 173 for a given
 174 .Fa g .
 175 This is an unsigned 8 bit number.
 176 .It Fa t
 177 This specifies the type of the passed parameter.
 178 This one gets internally transformed to the size of the parameter, so
 179 for example, if you want to pass a structure, then you have to specify that
 180 structure and not a pointer to it or sizeof(struct MYDEV).
 181 .El
 182 .Pp
 183 In order for the new ioctl to be visible to the system, it is installed
 184 in either
 185 .In sys/ioctl.h or one of the files that are reached from
 186 .In sys/ioctl.h .
 187 .Sh RETURN VALUES
 188 A distinction must be made at this point.
 189 All
 190 .Fn *_ioctl
 191 routines from
 192 .Em within kernel
 193 should return either 0 for success
 194 or a defined error code, as described in
 195 .In sys/errno.h .
 196 At the libc level though a conversion takes place, so that eventually
 197 .Xr ioctl 2
 198 returns either 0 for success or -1 for failure, in which case the
 199 .Va errno
 200 variable is set accordingly.
 201 .Pp
 202 The use of magic numbers such as -1, to indicate that a given ioctl
 203 code was not handled, is strongly discouraged.
 204 The value -1 is bound to the
 205 .Er ERESTART
 206 pseudo-error, which is returned inside kernel to modify return to process.
 207 .Sh EXAMPLES
 208 Let's suppose that we want to pass an integer value to the kernel.
 209 From the user point of view, this is like writing to the kernel.
 210 So we define the ioctl as:
 211 .Bd -literal -offset indent
 212 #define MYDEVIOCTL      _IOW('i', 25, int)
 213 .Ed
 214 .Pp
 215 Within the
 216 .Fn *_ioctl
 217 routine of the driver, it can be then accessed like:
 218 .Bd -literal -offset indent
 219 int
 220 mydev_ioctl(struct dev_ioctl_args *ap)
 221 {
 222         int error;
 223         int *a;
 224
 225         switch (ap->a_cmd) {
 226         case MYDEVIOCTL:
 227                 a = (int *)ap->data;
 228                 kprintf("Value passed from userspace: %d\\n", *a);
 229                 return (0);    /* Success */
 230                 break;
 231
 232         /* Handle other ioctls here */
 233
 234         default:
 235                 /* Inappropriate ioctl for device */
 236                 error = ENOTTY;
 237                 break;
 238         }
 239
 240         return (error);
 241 }
 242 .Ed
 243 .Pp
 244 In userspace:
 245 .Bd -literal -offset indent
 246 int a = 101;
 247 if (ioctl(fd, MYDEVIOCTL, \*[Am]a) == -1) {
 248         /* Handle failure */
 249 }
 250 .Ed
 251 .Sh SEE ALSO
 252 .Xr ioctl 2