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