1.\" $NetBSD: ioctl.9,v 1.9 2001/07/26 14:29:09 bjh21 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 _IOR 65the call only reads parameters from the kernel and does not 66pass any to it 67.It _IOW 68the call only writes parameters to the kernel, but does not want anything 69back 70.It _IOWR 71the call writes data to the kernel and wants information back. 72.El 73.It t 74This integer describes to which subsystem the ioctl applies. 75T 76can be one of 77.Bl -tag -width 'a' -compact 78.It '1' pulse-per-second interface 79.It '4' Xr i4b 4 80.It 'a' ISO networking 81.It 'A' ac devices (hp300) 82.It 'A' Advanced Power Management (hpcmips, i386, sparc) Xr apm 4 83.It 'A' ADB devices (mac68k, macppc) 84.It 'A' Xr audio 4 85.It 'A' Xr i4btel 4 86.It 'b' Xr tb 4 87.It 'B' bell device (x68k) 88.It 'B' Xr bpf 4 89.It 'c' coda 90.It 'c' Xr cd 4 91.It 'c' Xr ch 4 92.It 'C' clock devices (amiga, atari, hp300, x68k) 93.It 'C' Xr i4bctl 4 94.It 'd' the disk subsystem 95.It 'E' Xr envsys 4 96.It 'f' files 97.It 'F' Sun-compatible framebuffers 98.It 'F' Xr ccd 4 \& and Xr vnd 4 99.It 'g' qdss framebuffers 100.It 'G' grf devices (amiga, atari, hp300, mac68k, x68k) 101.It 'h' HIL devices (hp300) 102.It 'H' HIL devices (hp300) 103.It 'H' HPc framebuffers 104.It 'i' a (pseudo) interface 105.It 'I' Xr ite 4 \& (mac68k) 106.It 'J' ISA joystick interface 107.It 'k' Sun-compatible (and other) keyboards 108.It 'K' Xr lkm 4 109.It 'l' leo devices (atari) 110.It 'm' Xr mtio 4 111.It 'M' mouse devices (atari) 112.It 'M' Xr mlx 4 113.It 'n' virtual console device (arm32) 114.It 'n' SMB networking 115.It 'O' OpenPROM and OpenFirmware 116.It 'p' power control (x68k) 117.It 'P' parallel port (amiga, x68k) 118.It 'P' profiling (arm32) 119.It 'P' printer/plotter interface (hp300) 120.It 'P' Xr magma 4 \& bpp (sparc) 121.It 'q' Xr altq 4 122.It 'q' pmax graphics devices 123.It 'Q' Xr altq 4 124.It 'Q' raw SCSI commands 125.It 'r' the routing subsystem 126.It 'r' Xr md 4 127.It 'R' Xr i4brbch 4 128.It 'R' Xr rnd 4 129.It 's' the socket layer 130.It 's' satlink devices 131.It 'S' SCSI disks (arc, hp300, pmax) 132.It 'S' watchdog devices (sh3) 133.It 'S' ISA speaker devices 134.It 'S' stic devices 135.It 'S' scanners 136.It 't' the tty layer 137.It 'u' user defined ??? 138.It 'U' scsibus Pq Xr scsi 4 139.It 'v' Sun-compatible Dq firm events 140.It 'V' view device (amiga, atari) 141.It 'V' sram device (x68k) 142.It 'w' watchdog devices 143.It 'W' wt devices 144.It 'W' wscons devices 145.It 'x' bt8xx devices 146.It 'Z' ite devices (amiga, atari, x68k) 147.It 'Z' passthrough ioctls 148.El 149.It n 150This numbers the ioctl within the group. There may be only one 151.Fn n 152for a given 153.Fn t . 154This is a unsigned 8 bit number. 155.It pt 156This specifies the type of the passed parameter. This one gets internally 157transformed to the size of the parameter, so if you e.g. want to pass 158a structure, then you have to specify that structure and not a pointer 159to it or sizeof(struct foo) 160.El 161 162In order for the new ioctl to be known to the system it is installed 163in either <sys/ioctl.h> or one of the files that are reached from 164<sys/ioctl.h>. 165.Sh EXAMPLE 166 167 #define FOOIOCTL _IOWR('i',23,int) 168 169 int a=3; 170 error = ioctl(s,FOOICTL, &a); 171 172Within the ioctl()-routine of the driver, it can be then accessed like 173 174 driver_ioctl(..,cmd,data) 175 u_long cmd; 176 caddr_t data; 177 178 ... 179 switch(cmd) { 180 case FOOIOCTL: 181 int *a = (int *)data; 182 printf(" Value passed: %d\n",a); 183 } 184 185.Sh NOTES 186Note that if you e.g. try to read information from e.g. a ethernet 187driver where the name of the card is included in the third argument 188(e.g. ioctl(s,READFROMETH,struct ifreq *)), then you have to use 189the _IOWR() form not the _IOR(), as passing the name of the card to the 190kernel already consists of writing data. 191.Sh SEE ALSO 192.Xr ioctl 2 193