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