1.\" $NetBSD: ioctl.9,v 1.15 2002/04/28 14:13:38 atatat 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.Fd #include \*[Lt]sys/ioctl.h\*[Gt] 45.Fd #include \*[Lt]sys/ioccom.h\*[Gt] 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. It does not copy 67anything 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 i4b 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 i4btel 4 99.It 'b' 100.Xr \&tb 4 101.It 'B' 102bell device (x68k) 103.It 'B' 104.Xr bpf 4 105.It 'c' 106coda 107.It 'c' 108.Xr \&cd 4 109.It 'c' 110.Xr \&ch 4 111.It 'C' 112clock devices (amiga, atari, hp300, x68k) 113.It 'C' 114.Xr i4bctl 4 115.It 'd' 116the disk subsystem 117.It 'E' 118.Xr envsys 4 119.It 'f' 120files 121.It 'F' 122Sun-compatible framebuffers 123.It 'F' 124.Xr ccd 4 125and 126.Xr vnd 4 127.It 'g' 128qdss framebuffers 129.It 'G' 130grf devices (amiga, atari, hp300, mac68k, x68k) 131.It 'h' 132HIL devices (hp300) 133.It 'H' 134HIL devices (hp300) 135.It 'H' 136HPc framebuffers 137.It 'i' 138a (pseudo) interface 139.It 'I' 140.Xr ite 4 141(mac68k) 142.It 'J' 143ISA joystick interface 144.It 'k' 145Sun-compatible (and other) keyboards 146.It 'K' 147.Xr lkm 4 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' 171.Xr magma 4 172bpp (sparc) 173.It 'q' 174.Xr altq 9 175.It 'q' 176pmax graphics devices 177.It 'Q' 178.Xr altq 9 179.It 'Q' 180raw SCSI commands 181.It 'r' 182the routing subsystem 183.It 'r' 184.Xr \&md 4 185.It 'R' 186.Xr i4brbch 4 187.It 'R' 188.Xr rnd 4 189.It 's' 190the socket layer 191.It 's' 192satlink devices 193.It 'S' 194SCSI disks (arc, hp300, pmax) 195.It 'S' 196watchdog devices (sh3) 197.It 'S' 198ISA speaker devices 199.It 'S' 200stic devices 201.It 'S' 202scanners 203.It 't' 204the tty layer 205.It 'u' 206user defined ??? 207.It 'U' 208scsibus (see 209.Xr scsi 4 ) 210.It 'v' 211Sun-compatible 212.Dq firm events 213.It 'V' 214view device (amiga, atari) 215.It 'V' 216sram device (x68k) 217.It 'w' 218watchdog devices 219.It 'W' 220wt devices 221.It 'W' 222wscons devices 223.It 'x' 224bt8xx devices 225.It 'Z' 226ite devices (amiga, atari, x68k) 227.It 'Z' 228passthrough ioctls 229.El 230.It Ar n 231This numbers the ioctl within the group. There may be only one 232.Ar n 233for a given 234.Ar t . 235This is a unsigned 8 bit number. 236.It Ar pt 237This specifies the type of the passed parameter. This one gets internally 238transformed to the size of the parameter, so if you e.g. want to pass 239a structure, then you have to specify that structure and not a pointer 240to it or sizeof(struct foo) 241.El 242.Pp 243In order for the new ioctl to be known to the system it is installed 244in either \*[Lt]sys/ioctl.h\*[Gt] or one of the files that are reached from 245\*[Lt]sys/ioctl.h\*[Gt]. 246.Sh EXAMPLES 247.Bd -literal -offset indent 248#define FOOIOCTL _IOWR('i', 23, int) 249 250int a = 3; 251error = ioctl(s, FOOICTL, \*[Am]a); 252.Ed 253.Pp 254Within the ioctl()-routine of the driver, it can be then accessed like 255.Bd -literal -offset indent 256driver_ioctl(..., u_long cmd, caddr_t data) 257{ 258 ... 259 switch (cmd) { 260 261 case FOOIOCTL: 262 int *a = (int *)data; 263 printf(" Value passed: %d\en", *a); 264 break; 265 } 266} 267.Ed 268.Sh NOTES 269Note that if you e.g. try to read information from e.g. a ethernet 270driver where the name of the card is included in the third argument 271(e.g. ioctl(s, READFROMETH, struct ifreq *)), then you have to use 272the _IOWR() form not the _IOR(), as passing the name of the card to the 273kernel already consists of writing data. 274.Sh RETURN VALUES 275All ioctl() routines should return either 0 or a defined error code. 276The use of magic numbers such as -1, to indicate that a given ioctl 277code was not handled is strongly discouraged. The value -1 coincides 278with the historic value for 279.Cm ERESTART 280which was shown to produce user space code that never returned from 281a call to 282.Xr ioctl 2 . 283.Pp 284For ioctl codes that 285are not handled by a given routine, the pseudo error value 286.Cm EPASSTHROUGH 287is provided. 288.Cm EPASSTHROUGH 289indicates that no error occurred during processing (it did not fail), 290but neither was anything processed (it did not succeed). This 291supercedes the use of either 292.Cm ENOTTY 293(which is an explicit failure) or -1 (which has no contextual meaning) 294as a return value. 295.Cm ENOTTY 296will get passed directly back to user space and bypass any further 297processing by other ioctl layers. Only code that wishes to suppress 298possible further processing of an ioctl code (eg, the tty line discipline 299code) should return 300.Cm ENOTTY . 301All other code should return 302.Cm EPASSTHROUGH , 303even if it knows that no other layers will be called upon. 304.Pp 305If the value 306.Cm EPASSTHROUGH 307is returned to 308.Fn sys_ioctl , 309then it will there be changed to 310.Cm ENOTTY 311to be returned to user space, thereby providing the proper error 312notification to the application. 313.Sh SEE ALSO 314.Xr ioctl 2 315