No empty .Rs/.Re

[netbsd-mini2440.git] / share / man / man9 / ioctl.9

.\" $NetBSD: ioctl.9,v 1.26 2008/11/12 12:35:54 ad 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.
.\"
.\" 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 December 7, 2001
.Dt IOCTL 9
.Os
.Sh NAME
.Nm ioctl
.Nd "how to implement a new ioctl call to access device drivers"
.Sh SYNOPSIS
.In sys/ioctl.h
.In sys/ioccom.h
.Ft int
.Fn ioctl "int" "unsigned long" "..."
.Sh DESCRIPTION
.Nm
are internally defined as
.Bl -tag -width define
.It #define FOOIOCTL   fun(t,n,pt)
.El
.Pp
where the different variables and functions are:
.Bl -tag -width FOOIOCTL
.It Cm FOOIOCTL
the name which will later be given in the
.Xr ioctl 2
system call as second argument, e.g.,
.Dl ioctl(s, FOOIOCTL, ...) .
.It Fn fun
a macro which can be one of
.Bl -tag -width _IOWR
.It _IO
the call is a simple message to the kernel by itself.
It does not copy anything into the kernel, nor does it want anything back.
.It _IOR
the call only reads parameters from the kernel and does not
pass any to it
.It _IOW
the call only writes parameters to the kernel, but does not want anything
back
.It _IOWR
the call writes data to the kernel and wants information back.
.El
.It Ar t
This integer describes to which subsystem the ioctl applies.
.Ar t
can be one of
.Bl -tag -width xxxxx -compact
.It '1'
pulse-per-second interface
.It '4'
.Xr isdn 4
.It 'a'
ISO networking
.It 'A'
ac devices (hp300)
.It 'A'
Advanced Power Management (hpcmips, i386, sparc), see
.Xr apm 4
.It 'A'
ADB devices (mac68k, macppc)
.It 'A'
.Xr audio 4
.It 'A'
.Xr isdntel 4
.It 'b'
.Xr \&tb 4
.It 'b'
Bluetooth HCI sockets, see
.Xr bluetooth 4
.It 'b'
Bluetooth Hub Control, see
.Xr bthub 4
.It 'b'
Bluetooth SCO audio driver, see
.Xr btsco 4
.It 'B'
bell device (x68k)
.It 'B'
.Xr bpf 4
.It 'c'
coda
.It 'c'
.Xr \&cd 4
.It 'c'
.Xr \&ch 4
.It 'C'
clock devices (amiga, atari, hp300, x68k)
.It 'C'
.Xr isdnctl 4
.It 'd'
the disk subsystem
.It 'E'
.Xr envsys 4
.It 'f'
files
.It 'F'
Sun-compatible framebuffers
.It 'F'
.Xr ccd 4
and
.Xr vnd 4
.It 'g'
qdss framebuffers
.It 'G'
grf devices (amiga, atari, hp300, mac68k, x68k)
.It 'h'
HIL devices (hp300)
.It 'H'
HIL devices (hp300)
.It 'H'
HPc framebuffers
.It 'i'
a (pseudo) interface
.It 'I'
.Xr ite 4
(mac68k)
.It 'J'
ISA joystick interface
.It 'k'
Sun-compatible (and other) keyboards
.It 'l'
leo devices (atari)
.It 'm'
.Xr mtio 4
.It 'M'
mouse devices (atari)
.It 'M'
.Xr mlx 4
.It 'n'
virtual console device (arm32)
.It 'n'
SMB networking
.It 'O'
OpenPROM and OpenFirmware
.It 'p'
power control (x68k)
.It 'P'
parallel port (amiga, x68k)
.It 'P'
profiling (arm32)
.It 'P'
printer/plotter interface (hp300)
.It 'P'
.Xr magma 4
bpp (sparc)
.It 'q'
.Xr altq 9
.It 'q'
pmax graphics devices
.It 'Q'
.Xr altq 9
.It 'Q'
raw SCSI commands
.It 'r'
the routing subsystem
.It 'r'
.Xr \&md 4
.It 'R'
.Xr isdnbchan 4
.It 'R'
.Xr rnd 4
.It 's'
the socket layer
.It 's'
satlink devices
.It 'S'
SCSI disks (arc, hp300, pmax)
.It 'S'
watchdog devices (sh3)
.It 'S'
ISA speaker devices
.It 'S'
stic devices
.It 'S'
scanners
.It 't'
the tty layer
.It 'u'
user defined ???
.It 'U'
scsibus (see
.Xr scsi 4 )
.It 'v'
Sun-compatible
.Dq firm events
.It 'V'
view device (amiga, atari)
.It 'V'
sram device (x68k)
.It 'w'
watchdog devices
.It 'W'
wt devices
.It 'W'
wscons devices
.It 'x'
bt8xx devices
.It 'Z'
ite devices (amiga, atari, x68k)
.It 'Z'
passthrough ioctls
.El
.It Ar n
This numbers the ioctl within the group.
There may be only one
.Ar n
for a given
.Ar t .
This is an unsigned 8 bit number.
.It Ar pt
This specifies the type of the passed parameter.
This one gets internally transformed to the size of the parameter, so
for example, if you want to pass a structure, then you have to specify that
structure and not a pointer to it or sizeof(struct foo)
.El
.Pp
In order for the new ioctl to be known to the system it is installed
in either \*[Lt]sys/ioctl.h\*[Gt] or one of the files that are reached from
\*[Lt]sys/ioctl.h\*[Gt].
.Sh EXAMPLES
.Bd -literal -offset indent
#define FOOIOCTL        _IOWR('i', 23, int)

int a = 3;
error = ioctl(s, FOOICTL, \*[Am]a);
.Ed
.Pp
Within the ioctl()-routine of the driver, it can be then accessed like
.Bd -literal -offset indent
driver_ioctl(..., u_long cmd, void *data)
{
        ...
        switch (cmd) {

        case FOOIOCTL:
                int *a = (int *)data;
                printf(" Value passed: %d\en", *a);
                break;
        }
}
.Ed
.Sh NOTES
Note that if you for example try to read information from an 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 RETURN VALUES
All ioctl() routines should return either 0 or a defined error code.
The use of magic numbers such as -1, to indicate that a given ioctl
code was not handled is strongly discouraged.
The value -1 coincides with the historic value for
.Cm ERESTART
which was shown to produce user space code that never returned from
a call to
.Xr ioctl 2 .
.Pp
For ioctl codes that
are not handled by a given routine, the pseudo error value
.Cm EPASSTHROUGH
is provided.
.Cm EPASSTHROUGH
indicates that no error occurred during processing (it did not fail),
but neither was anything processed (it did not succeed).
This supersedes the use of either
.Cm ENOTTY
(which is an explicit failure) or -1 (which has no contextual meaning)
as a return value.
.Cm ENOTTY
will get passed directly back to user space and bypass any further
processing by other ioctl layers.
Only code that wishes to suppress possible further processing of an
ioctl code (e.g., the tty line discipline code) should return
.Cm ENOTTY .
All other code should return
.Cm EPASSTHROUGH ,
even if it knows that no other layers will be called upon.
.Pp
If the value
.Cm EPASSTHROUGH
is returned to
.Fn sys_ioctl ,
then it will there be changed to
.Cm ENOTTY
to be returned to user space, thereby providing the proper error
notification to the application.
.Sh SEE ALSO
.Xr ioctl 2