1.\" $NetBSD: ioctl.9,v 1.26 2008/11/12 12:35:54 ad 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 April 4, 2018 31.Dt IOCTL 9 32.Os 33.Sh NAME 34.Nm ioctl , 35.Nm _IO , 36.Nm _IOR , 37.Nm _IOW , 38.Nm _IOWR 39.Nd "how to implement a new ioctl call to access device drivers" 40.Sh SYNOPSIS 41.In sys/ioccom.h 42.Fn _IO "g" "t" 43.Fn _IOR "g" "n" "t" 44.Fn _IOW "g" "n" "t" 45.Fn _IOWR "g" "n" "t" 46.Sh DESCRIPTION 47Whenever an 48.Xr ioctl 2 49call is made, the kernel dispatches it to the device driver 50which can then interpret the request number and data in a specialized 51manner. 52Ioctls are defined as: 53.Bd -literal 54#define MYDEVIOCTL fun(g, n, t) 55.Ed 56.Pp 57where the different symbols correspond to: 58.Bl -tag -width ".Dv MYDEVIOCTL" 59.It Dv MYDEVIOCTL 60The name which will later be given in the 61.Xr ioctl 2 62system call as second argument, e.g., 63.Bd -literal 64ioctl(fd, MYDEVIOCTL, ...) 65.Ed 66.It Fn fun 67A macro which can be one of: 68.Bl -tag -width ".Fn _IOWR" 69.It Fn _IO 70The call is a simple message to the kernel by itself. 71It does not copy anything into the kernel, nor does it want anything back. 72.It Fn _IOR 73The call only reads parameters from the kernel and does not 74pass any to it. 75.It Fn _IOW 76The call only writes parameters to the kernel, but does not want anything 77back. 78.It Fn _IOWR 79The call writes data to the kernel and wants information back. 80.El 81.Pp 82We always consider reading or writing to the kernel, from the user perspective. 83.It Fa g 84This integer describes to which subsystem the ioctl applies. 85Here are some examples: 86.Pp 87.Bl -tag -width xxxxx -compact 88.It '8' 89.Xr aac 4 90.It 'a' 91.Xr nata 4 92.It 'B' 93.Xr bpf 4 94.It 'C' 95.Xr cam 4 96.It 'C' 97.Xr ciss 4 98.It 'd' 99.Xr disklabel 5 100.It 'd' 101diskslice 102.It 'd' 103.Xr drm 4 104.It 'f' 105generic file-descriptor 106.It 'F' 107frame buffer 108.It 'h' 109.Xr HAMMER 5 110.It 'i' 111.Xr iic 4 112.It 'i' 113.Xr carp 4 114.It 'i' 115.Xr gre 4 116.It 'k' 117.Xr keyboard 4 118and 119.Xr syscons 4 120.It 'm' 121.Xr mem 4 122.It 'm' 123.Pa /dev/midi 124.It 'm' 125.Xr mtio 4 126.It 'M' 127.Xr sound 4 128mixer 129.It 'n' 130.Xr smb 4 131.It 'n' 132NetWare volume mount 133.It 'p' 134.Pa /dev/dsp 135and 136.Pa /dev/audio 137.It 'p' 138.Xr pci 4 139.It 'p' 140.Xr ppbus 4 141.It 'p' 142.Xr procfs 5 143.It 'q' 144.Pa /dev/sequencer 145.It 'r' 146random number generator 147.It 't' 148.Xr tty 4 149.It 't' 150.Xr tap 4 151.It 't' 152.Xr tun 4 153.It 't' 154SLIP ttys 155.It 'T' 156.Xr snp 4 157.El 158.It Fa n 159This number uniquely identifies the ioctl within the group. 160That said, two subsystems may share the same 161.Fa g , 162but there may be only one 163.Fa n 164for a given 165.Fa g . 166This is an unsigned 8 bit number. 167.It Fa t 168This specifies the type of the passed parameter. 169This one gets internally transformed to the size of the parameter, so 170for example, if you want to pass a structure, then you have to specify that 171structure and not a pointer to it or sizeof(struct MYDEV). 172.El 173.Pp 174In order for the new ioctl to be visible to the system, it is installed 175in either 176.In sys/ioctl.h or one of the files that are reached from 177.In sys/ioctl.h . 178.Sh RETURN VALUES 179A distinction must be made at this point. 180All 181.Fn *_ioctl 182routines from 183.Em within kernel 184should return either 0 for success 185or a defined error code, as described in 186.In sys/errno.h . 187At the libc level though a conversion takes place, so that eventually 188.Xr ioctl 2 189returns either 0 for success or -1 for failure, in which case the 190.Va errno 191variable is set accordingly. 192.Pp 193The use of magic numbers such as -1, to indicate that a given ioctl 194code was not handled, is strongly discouraged. 195The value -1 is bound to the 196.Er ERESTART 197pseudo-error, which is returned inside kernel to modify return to process. 198.Sh EXAMPLES 199Let's suppose that we want to pass an integer value to the kernel. 200From the user point of view, this is like writing to the kernel. 201So we define the ioctl as: 202.Bd -literal -offset indent 203#define MYDEVIOCTL _IOW('i', 25, int) 204.Ed 205.Pp 206Within the 207.Fn *_ioctl 208routine of the driver, it can be then accessed like: 209.Bd -literal -offset indent 210int 211mydev_ioctl(struct dev_ioctl_args *ap) 212{ 213 int error; 214 int *a; 215 216 switch (ap->a_cmd) { 217 case MYDEVIOCTL: 218 a = (int *)ap->data; 219 kprintf("Value passed from userspace: %d\\n", *a); 220 return (0); /* Success */ 221 break; 222 223 /* Handle other ioctls here */ 224 225 default: 226 /* Inappropriate ioctl for device */ 227 error = ENOTTY; 228 break; 229 } 230 231 return (error); 232} 233.Ed 234.Pp 235In userspace: 236.Bd -literal -offset indent 237int a = 101; 238if (ioctl(fd, MYDEVIOCTL, \*[Am]a) == -1) { 239 /* Handle failure */ 240} 241.Ed 242.Sh SEE ALSO 243.Xr ioctl 2 244