ioctl.9 revision 1.3
$NetBSD: ioctl.9,v 1.3 1999/09/15 09:41:51 hwr Exp $
Copyright (c) 1999 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Heiko W.Rupp <hwr@pilhuhn.de>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgement:
This product includes software developed by the NetBSD
Foundation, Inc. and its contributors.
4. Neither the name of the The NetBSD Foundation nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd March 7, 1999 .Dt IOCTL 9 .Os .Sh NAME .Nm ioctl .Nd how to implement a new ioctl call to access device drivers .Sh SYNOPSIS .Fd #include <sys/ioctl.h> .Fd #include <sys/ioccom.h> .Ft int .Fn ioctl int, unsigned long, ... .Sh DESCRIPTION .Nm Ioctl are internally defined as l -tag -witdh define t #define FOOIOCTL fun(t,n,pt) .El where the different wariables and funcions are: l -tag -width FOOIOCTL t Fn FOOIOCTL the name as the ioctl is later known in a as second argument to a .Xr ioctl system call. E.g. ioctl(s,FOOIOCTL,...) t Fn fun a macro which can be one of l -tag -withh _IOWR t _IOR the call only reads parameters from the kernel and does not pass any to it t _IOW the call only writes parameters to the kernel, but does not want anything back t _IOWR the call writes data to the kernel and wants information back. .El t t This integer describes to which subsystem the ioctl applies. T can be one of l -tag -with 'a' t 'd' the disk subsystem t 'f' files t 'i' a (pseudo) interface t 'r' the routing subsystem t 's' the socket layer t 't' the tty layer t 'u' user defined ??? .El t n This numbers the ioctl within the group. There may be only one .Fn n for a given .Fn t . This is a unsigned 8 bit number. t pt This specifyies the type of the passed parameter. This one gets internally transformed to the size of the parameter, so if you e.g. want to pass a structure, then you have to specify that structure and not a pointer to it or sizeof(struct foo) .El In order for the new ioctl to be known to the system it is installed in either <sys/ioctl.h> or one of the files that are reached from <sys/ioctl.h>. .Sh EXAMPLE #define FOOIOCTL _IOWR('i',23,int) int a=3; error = ioctl(s,FOOICTL, &a); Within the ioctl()-routine of the driver, it can be then accessd like driver_ioctl(..,cmd,data) u_long cmd; caddr_t data; ... switch(cmd) { case FOOIOCTL: int *a = (int *)data; printf(" Value passed: %d\n",a); } .Sh NOTES Note that if you e.g. try to read information from e.g. a ethernet driver where the name of the card is included in the third argument (e.g. ioctl(s,READFROMETH,struct ifreq *)), then you have to use the _IOWR() form not the _IOR(), as passing the name of the card to the kernel already consists of writing data. .Sh SEE ALSO .Xr ioctl 2
Copyright (c) 1999 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Heiko W.Rupp <hwr@pilhuhn.de>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgement:
This product includes software developed by the NetBSD
Foundation, Inc. and its contributors.
4. Neither the name of the The NetBSD Foundation nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd March 7, 1999 .Dt IOCTL 9 .Os .Sh NAME .Nm ioctl .Nd how to implement a new ioctl call to access device drivers .Sh SYNOPSIS .Fd #include <sys/ioctl.h> .Fd #include <sys/ioccom.h> .Ft int .Fn ioctl int, unsigned long, ... .Sh DESCRIPTION .Nm Ioctl are internally defined as l -tag -witdh define t #define FOOIOCTL fun(t,n,pt) .El where the different wariables and funcions are: l -tag -width FOOIOCTL t Fn FOOIOCTL the name as the ioctl is later known in a as second argument to a .Xr ioctl system call. E.g. ioctl(s,FOOIOCTL,...) t Fn fun a macro which can be one of l -tag -withh _IOWR t _IOR the call only reads parameters from the kernel and does not pass any to it t _IOW the call only writes parameters to the kernel, but does not want anything back t _IOWR the call writes data to the kernel and wants information back. .El t t This integer describes to which subsystem the ioctl applies. T can be one of l -tag -with 'a' t 'd' the disk subsystem t 'f' files t 'i' a (pseudo) interface t 'r' the routing subsystem t 's' the socket layer t 't' the tty layer t 'u' user defined ??? .El t n This numbers the ioctl within the group. There may be only one .Fn n for a given .Fn t . This is a unsigned 8 bit number. t pt This specifyies the type of the passed parameter. This one gets internally transformed to the size of the parameter, so if you e.g. want to pass a structure, then you have to specify that structure and not a pointer to it or sizeof(struct foo) .El In order for the new ioctl to be known to the system it is installed in either <sys/ioctl.h> or one of the files that are reached from <sys/ioctl.h>. .Sh EXAMPLE #define FOOIOCTL _IOWR('i',23,int) int a=3; error = ioctl(s,FOOICTL, &a); Within the ioctl()-routine of the driver, it can be then accessd like driver_ioctl(..,cmd,data) u_long cmd; caddr_t data; ... switch(cmd) { case FOOIOCTL: int *a = (int *)data; printf(" Value passed: %d\n",a); } .Sh NOTES Note that if you e.g. try to read information from e.g. a ethernet driver where the name of the card is included in the third argument (e.g. ioctl(s,READFROMETH,struct ifreq *)), then you have to use the _IOWR() form not the _IOR(), as passing the name of the card to the kernel already consists of writing data. .Sh SEE ALSO .Xr ioctl 2