1.\" $NetBSD: ioctl.9,v 1.4 1999/11/19 01:12:42 enami 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 Ioctl 50are internally defined as 51.Bl -tag -witdh define 52.It #define FOOIOCTL fun(t,n,pt) 53.El 54 55where the different wariables and funcions 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 60system call. E.g. ioctl(s,FOOIOCTL,...) 61.It Fn fun 62a macro which can be one of 63.Bl -tag -withh _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 -with 'a' 78.It 'd' the disk subsystem 79.It 'f' files 80.It 'i' a (pseudo) interface 81.It 'r' the routing subsystem 82.It 's' the socket layer 83.It 't' the tty layer 84.It 'u' user defined ??? 85.El 86.It n 87This numbers the ioctl within the group. There may be only one 88.Fn n 89for a given 90.Fn t . 91This is a unsigned 8 bit number. 92.It pt 93This specifyies the type of the passed parameter. This one gets internally 94transformed to the size of the parameter, so if you e.g. want to pass 95a structure, then you have to specify that structure and not a pointer 96to it or sizeof(struct foo) 97.El 98 99In order for the new ioctl to be known to the system it is installed 100in either <sys/ioctl.h> or one of the files that are reached from 101<sys/ioctl.h>. 102.Sh EXAMPLE 103 104 #define FOOIOCTL _IOWR('i',23,int) 105 106 int a=3; 107 error = ioctl(s,FOOICTL, &a); 108 109Within the ioctl()-routine of the driver, it can be then accessd like 110 111 driver_ioctl(..,cmd,data) 112 u_long cmd; 113 caddr_t data; 114 115 ... 116 switch(cmd) { 117 case FOOIOCTL: 118 int *a = (int *)data; 119 printf(" Value passed: %d\n",a); 120 } 121 122.Sh NOTES 123Note that if you e.g. try to read information from e.g. a ethernet 124driver where the name of the card is included in the third argument 125(e.g. ioctl(s,READFROMETH,struct ifreq *)), then you have to use 126the _IOWR() form not the _IOR(), as passing the name of the card to the 127kernel already consists of writing data. 128.Sh SEE ALSO 129.Xr ioctl 2 130