1.\" $NetBSD: ioctl.9,v 1.11 2001/09/13 17:19:55 atatat 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of the The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd March 7, 1999 38.Dt IOCTL 9 39.Os 40.Sh NAME 41.Nm ioctl 42.Nd "how to implement a new ioctl call to access device drivers" 43.Sh SYNOPSIS 44.Fd #include <sys/ioctl.h> 45.Fd #include <sys/ioccom.h> 46.Ft int 47.Fn ioctl int, unsigned long, ... 48.Sh DESCRIPTION 49.Nm 50are internally defined as 51.Bl -tag -width define 52.It #define FOOIOCTL fun(t,n,pt) 53.El 54 55where the different variables and functions are: 56.Bl -tag -width FOOIOCTL 57.It Fn FOOIOCTL 58the name as the ioctl is later known in a as second argument to a 59.Xr ioctl 2 60system call. E.g. ioctl(s,FOOIOCTL,...) 61.It Fn fun 62a macro which can be one of 63.Bl -tag -width _IOWR 64.It _IO 65the call is a simple message to the kernel by itself. It does not copy 66anything into the kernel, nor does it want anything back. 67.It _IOR 68the call only reads parameters from the kernel and does not 69pass any to it 70.It _IOW 71the call only writes parameters to the kernel, but does not want anything 72back 73.It _IOWR 74the call writes data to the kernel and wants information back. 75.El 76.It t 77This integer describes to which subsystem the ioctl applies. 78T 79can be one of 80.Bl -tag -width 'a' -compact 81.It '1' pulse-per-second interface 82.It '4' Xr i4b 4 83.It 'a' ISO networking 84.It 'A' ac devices (hp300) 85.It 'A' Advanced Power Management (hpcmips, i386, sparc) Xr apm 4 86.It 'A' ADB devices (mac68k, macppc) 87.It 'A' Xr audio 4 88.It 'A' Xr i4btel 4 89.It 'b' Xr tb 4 90.It 'B' bell device (x68k) 91.It 'B' Xr bpf 4 92.It 'c' coda 93.It 'c' Xr cd 4 94.It 'c' Xr ch 4 95.It 'C' clock devices (amiga, atari, hp300, x68k) 96.It 'C' Xr i4bctl 4 97.It 'd' the disk subsystem 98.It 'E' Xr envsys 4 99.It 'f' files 100.It 'F' Sun-compatible framebuffers 101.It 'F' Xr ccd 4 \& and Xr vnd 4 102.It 'g' qdss framebuffers 103.It 'G' grf devices (amiga, atari, hp300, mac68k, x68k) 104.It 'h' HIL devices (hp300) 105.It 'H' HIL devices (hp300) 106.It 'H' HPc framebuffers 107.It 'i' a (pseudo) interface 108.It 'I' Xr ite 4 \& (mac68k) 109.It 'J' ISA joystick interface 110.It 'k' Sun-compatible (and other) keyboards 111.It 'K' Xr lkm 4 112.It 'l' leo devices (atari) 113.It 'm' Xr mtio 4 114.It 'M' mouse devices (atari) 115.It 'M' Xr mlx 4 116.It 'n' virtual console device (arm32) 117.It 'n' SMB networking 118.It 'O' OpenPROM and OpenFirmware 119.It 'p' power control (x68k) 120.It 'P' parallel port (amiga, x68k) 121.It 'P' profiling (arm32) 122.It 'P' printer/plotter interface (hp300) 123.It 'P' Xr magma 4 \& bpp (sparc) 124.It 'q' Xr altq 4 125.It 'q' pmax graphics devices 126.It 'Q' Xr altq 4 127.It 'Q' raw SCSI commands 128.It 'r' the routing subsystem 129.It 'r' Xr md 4 130.It 'R' Xr i4brbch 4 131.It 'R' Xr rnd 4 132.It 's' the socket layer 133.It 's' satlink devices 134.It 'S' SCSI disks (arc, hp300, pmax) 135.It 'S' watchdog devices (sh3) 136.It 'S' ISA speaker devices 137.It 'S' stic devices 138.It 'S' scanners 139.It 't' the tty layer 140.It 'u' user defined ??? 141.It 'U' scsibus Pq Xr scsi 4 142.It 'v' Sun-compatible Dq firm events 143.It 'V' view device (amiga, atari) 144.It 'V' sram device (x68k) 145.It 'w' watchdog devices 146.It 'W' wt devices 147.It 'W' wscons devices 148.It 'x' bt8xx devices 149.It 'Z' ite devices (amiga, atari, x68k) 150.It 'Z' passthrough ioctls 151.El 152.It n 153This numbers the ioctl within the group. There may be only one 154.Fn n 155for a given 156.Fn t . 157This is a unsigned 8 bit number. 158.It pt 159This specifies the type of the passed parameter. This one gets internally 160transformed to the size of the parameter, so if you e.g. want to pass 161a structure, then you have to specify that structure and not a pointer 162to it or sizeof(struct foo) 163.El 164 165In order for the new ioctl to be known to the system it is installed 166in either <sys/ioctl.h> or one of the files that are reached from 167<sys/ioctl.h>. 168.Sh EXAMPLES 169 170 #define FOOIOCTL _IOWR('i',23,int) 171 172 int a=3; 173 error = ioctl(s,FOOICTL, &a); 174 175Within the ioctl()-routine of the driver, it can be then accessed like 176 177 driver_ioctl(..,cmd,data) 178 u_long cmd; 179 caddr_t data; 180 181 ... 182 switch(cmd) { 183 case FOOIOCTL: 184 int *a = (int *)data; 185 printf(" Value passed: %d\n",a); 186 } 187 188.Sh NOTES 189Note that if you e.g. try to read information from e.g. a ethernet 190driver where the name of the card is included in the third argument 191(e.g. ioctl(s,READFROMETH,struct ifreq *)), then you have to use 192the _IOWR() form not the _IOR(), as passing the name of the card to the 193kernel already consists of writing data. 194.Sh SEE ALSO 195.Xr ioctl 2 196