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