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