1.\" $NetBSD: ioctl.9,v 1.31 2013/03/06 22:07:54 wiz 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 December 11, 2010 31.Dt IOCTL 9 32.Os 33.Sh NAME 34.Nm ioctl 35.Nd "how to implement a new ioctl call to access device drivers" 36.Sh SYNOPSIS 37.In sys/ioctl.h 38.In sys/ioccom.h 39.Ft int 40.Fn ioctl "int" "unsigned long" "..." 41.Sh DESCRIPTION 42.Nm 43are internally defined as 44.Bl -tag -width define 45.It #define FOOIOCTL fun(t,n,pt) 46.El 47.Pp 48where the different variables and functions are: 49.Bl -tag -width FOOIOCTL 50.It Cm FOOIOCTL 51the name which will later be given in the 52.Xr ioctl 2 53system call as second argument, e.g., 54.Dl ioctl(s, FOOIOCTL, ...) . 55.It Fn fun 56a macro which can be one of 57.Bl -tag -width _IOWR 58.It _IO 59the call is a simple message to the kernel by itself. 60It does not copy anything into the kernel, nor does it want anything back. 61.It _IOR 62the call only reads parameters from the kernel and does not 63pass any to it 64.It _IOW 65the call only writes parameters to the kernel, but does not want anything 66back 67.It _IOWR 68the call writes data to the kernel and wants information back. 69.El 70.It Ar t 71This integer describes to which subsystem the ioctl applies. 72.Ar t 73can be one of 74.Bl -tag -width xxxxx -compact 75.It '1' 76pulse-per-second interface 77.It '4' 78.Xr isdn 4 79.It 'a' 80ISO networking 81.It 'A' 82ac devices (hp300) 83.It 'A' 84Advanced Power Management (hpcmips, i386, sparc), see 85.Xr apm 4 86.It 'A' 87ADB devices (mac68k, macppc) 88.It 'A' 89.Xr audio 4 90.It 'A' 91.Xr isdntel 4 92.It 'b' 93.Xr \&tb 4 94.It 'b' 95Bluetooth HCI sockets, see 96.Xr bluetooth 4 97.It 'b' 98Bluetooth Hub Control, see 99.Xr bthub 4 100.It 'b' 101Bluetooth SCO audio driver, see 102.Xr btsco 4 103.It 'B' 104bell device (x68k) 105.It 'B' 106.Xr bpf 4 107.It 'c' 108coda 109.It 'c' 110.Xr \&cd 4 111.It 'c' 112.Xr \&ch 4 113.It 'C' 114clock devices (amiga, atari, hp300, x68k) 115.It 'C' 116.Xr isdnctl 4 117.It 'd' 118the disk subsystem 119.It 'E' 120.Xr envsys 4 121.It 'f' 122files 123.It 'F' 124Sun-compatible framebuffers 125.It 'F' 126.Xr ccd 4 127and 128.Xr vnd 4 129.It 'g' 130qdss framebuffers 131.It 'G' 132grf devices (amiga, atari, hp300, mac68k, x68k) 133.It 'h' 134HIL devices (hp300) 135.It 'H' 136HIL devices (hp300) 137.It 'H' 138HPc framebuffers 139.It 'i' 140a (pseudo) interface 141.It 'I' 142.Xr ite 4 143(mac68k) 144.It 'J' 145ISA joystick interface 146.It 'k' 147Sun-compatible (and other) keyboards 148.It 'l' 149leo devices (atari) 150.It 'm' 151.Xr mtio 4 152.It 'M' 153mouse devices (atari) 154.It 'M' 155.Xr mlx 4 156.It 'n' 157virtual console device (arm32) 158.It 'n' 159SMB networking 160.It 'O' 161OpenPROM and OpenFirmware 162.It 'p' 163power control (x68k) 164.It 'P' 165parallel port (amiga, x68k) 166.It 'P' 167profiling (arm32) 168.It 'P' 169printer/plotter interface (hp300) 170.It 'P' 171pci(4) 172.It 'P' 173compat/ossaudio and soundcard.h 174.It 'P' 175.Xr magma 4 176bpp (sparc) 177.It 'q' 178.Xr altq 9 179.It 'q' 180pmax graphics devices 181.It 'Q' 182.Xr altq 9 183.It 'Q' 184raw SCSI commands 185.It 'r' 186the routing subsystem 187.It 'r' 188.Xr \&md 4 189.It 'R' 190.Xr isdnbchan 4 191.It 'R' 192.Xr rnd 4 193.It 's' 194the socket layer 195.It 's' 196satlink devices 197.It 'S' 198SCSI disks (arc, hp300, pmax) 199.It 'S' 200watchdog devices (sh3) 201.It 'S' 202ISA speaker devices 203.It 'S' 204stic devices 205.It 'S' 206scanners 207.It 't' 208the tty layer 209.It 'u' 210user defined ??? 211.It 'U' 212scsibus (see 213.Xr scsi 4 ) 214.It 'v' 215Sun-compatible 216.Dq firm events 217.It 'V' 218view device (amiga, atari) 219.It 'V' 220sram device (x68k) 221.It 'w' 222watchdog devices 223.It 'W' 224wt devices 225.It 'W' 226wscons devices 227.It 'x' 228bt8xx devices 229.It 'Z' 230ite devices (amiga, atari, x68k) 231.It 'Z' 232passthrough ioctls 233.El 234.It Ar n 235This numbers the ioctl within the group. 236There may be only one 237.Ar n 238for a given 239.Ar t . 240This is an unsigned 8 bit number. 241.It Ar pt 242This specifies the type of the passed parameter. 243This one gets internally transformed to the size of the parameter, so 244for example, if you want to pass a structure, then you have to specify that 245structure and not a pointer to it or sizeof(struct foo) 246.El 247.Pp 248In order for the new ioctl to be known to the system it is installed 249in either 250.Aq Pa sys/ioctl.h 251or one of the files that are reached from 252.Aq Pa sys/ioctl.h . 253.Sh RETURN VALUES 254All 255.Fn ioctl 256routines should return either 0 or a defined error code. 257The use of magic numbers such as \-1, to indicate that a given ioctl 258code was not handled is strongly discouraged. 259The value \-1 coincides with the historic value for 260.Cm ERESTART 261which was shown to produce user space code that never returned from 262a call to 263.Xr ioctl 2 . 264.Pp 265For ioctl codes that 266are not handled by a given routine, the pseudo error value 267.Cm EPASSTHROUGH 268is provided. 269.Cm EPASSTHROUGH 270indicates that no error occurred during processing (it did not fail), 271but neither was anything processed (it did not succeed). 272This supersedes the use of either 273.Cm ENOTTY 274(which is an explicit failure) or \-1 (which has no contextual meaning) 275as a return value. 276.Cm ENOTTY 277will get passed directly back to user space and bypass any further 278processing by other ioctl layers. 279Only code that wishes to suppress possible further processing of an 280ioctl code (e.g., the tty line discipline code) should return 281.Cm ENOTTY . 282All other code should return 283.Cm EPASSTHROUGH , 284even if it knows that no other layers will be called upon. 285.Pp 286If the value 287.Cm EPASSTHROUGH 288is returned to 289.Fn sys_ioctl , 290then it will there be changed to 291.Cm ENOTTY 292to be returned to user space, thereby providing the proper error 293notification to the application. 294.Sh EXAMPLES 295.Bd -literal -offset indent 296#define FOOIOCTL _IOWR('i', 23, int) 297 298int a = 3; 299error = ioctl(s, FOOICTL, \*[Am]a); 300.Ed 301.Pp 302Within the 303.Fn ioctl Ns No -routine 304of the driver, it can be then accessed like 305.Bd -literal -offset indent 306driver_ioctl(..., u_long cmd, void *data) 307{ 308 ... 309 switch (cmd) { 310 311 case FOOIOCTL: 312 int *a = (int *)data; 313 printf(" Value passed: %d\en", *a); 314 break; 315 } 316} 317.Ed 318.Sh NOTES 319Note that if you for example try to read information from an ethernet 320driver where the name of the card is included in the third argument 321(e.g., ioctl(s, READFROMETH, struct ifreq *)), then you have to use 322the 323.Fn _IOWR 324form not the 325.Fn _IOR , 326as passing the name of the card to the 327kernel already consists of writing data. 328.Sh SEE ALSO 329.Xr ioctl 2 330