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 February 19, 2009 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.Pp 57.Bd -literal 58#define MYDEVIOCTL fun(g, n, t) 59.Ed 60.Pp 61where the different symbols correspond to: 62.Bl -tag -width ".Dv MYDEVIOCTL" 63.It Dv MYDEVIOCTL 64The name which will later be given in the 65.Xr ioctl 2 66system call as second argument, e.g., 67.Bd -literal 68ioctl(fd, MYDEVIOCTL, ...) 69.Ed 70.It Fn fun 71A macro which can be one of: 72.Bl -tag -width ".Fn _IOWR" 73.It Fn _IO 74The call is a simple message to the kernel by itself. 75It does not copy anything into the kernel, nor does it want anything back. 76.It Fn _IOR 77The call only reads parameters from the kernel and does not 78pass any to it. 79.It Fn _IOW 80The call only writes parameters to the kernel, but does not want anything 81back. 82.It Fn _IOWR 83The call writes data to the kernel and wants information back. 84.El 85.Pp 86We always consider reading or writing to the kernel, from the user perspective. 87.It Fa g 88This integer describes to which subsystem the ioctl applies. 89Here are some examples: 90.Pp 91.Bl -tag -width xxxxx -compact 92.It 'a' 93.Xr nata 4 94.It 'b' 95.Xr bpf 4 96.It 'h' 97.Xr HAMMER 5 98.It 't' 99the tty layer 100.El 101.It Fa n 102This number uniquely identifies the ioctl within the group. 103That said, two subsystems may share the same 104.Fa g , 105but there may be only one 106.Fa n 107for a given 108.Fa g . 109This is an unsigned 8 bit number. 110.It Fa t 111This specifies the type of the passed parameter. 112This one gets internally transformed to the size of the parameter, so 113for example, if you want to pass a structure, then you have to specify that 114structure and not a pointer to it or sizeof(struct MYDEV). 115.El 116.Pp 117In order for the new ioctl to be visible to the system, it is installed 118in either 119.In sys/ioctl.h or one of the files that are reached from 120.In sys/ioctl.h . 121.Sh EXAMPLES 122Let's suppose that we want to pass an integer value to the kernel. 123From the user point of view, this is like writing to the kernel. 124So we define the ioctl as: 125.Bd -literal -offset indent 126#define MYDEVIOCTL _IOW('i', 25, int) 127.Ed 128.Pp 129Within the 130.Fn *_ioctl 131routine of the driver, it can be then accessed like: 132.Bd -literal -offset indent 133int 134mydev_ioctl(dev_ioctl_args *ap) 135{ 136 int error; 137 int *a; 138 139 switch (ap->a_cmd) { 140 case MYDEVIOCTL: 141 a = (int *)ap->data; 142 kprintf("Value passed from userspace: %d\\n", *a); 143 return (0); /* Success */ 144 break; 145 146 /* Handle other ioctls here */ 147 148 default: 149 /* Inappropriate ioctl for device */ 150 error = ENOTTY; 151 break; 152 } 153 154 return (error); 155} 156.Ed 157.Pp 158In userspace: 159.Bd -literal -offset indent 160int a = 101; 161if (ioctl(fd, MYDEVIOCTL, \*[Am]a) == -1) { 162 /* Handle failure */ 163} 164.Ed 165.Sh RETURN VALUES 166A distinction must be made at this point. 167All 168.Fn *_ioctl 169routines from 170.Em within kernel 171should return either 0 for success 172or a defined error code, as described in 173.In sys/errno.h . 174At the libc level though a conversion takes place, so that eventually 175.Xr ioctl 2 176returns either 0 for success or -1 for failure, in which case the 177.Va errno 178variable is set accordingly. 179.Pp 180The use of magic numbers such as -1, to indicate that a given ioctl 181code was not handled, is strongly discouraged. 182The value -1 is bound to the 183.Er ERESTART 184pseudo-error, which is returned inside kernel to modify return to process. 185.Sh SEE ALSO 186.Xr ioctl 2 187