diff options
Diffstat (limited to 'static/netbsd/man9/ioctl.9')
| -rw-r--r-- | static/netbsd/man9/ioctl.9 | 317 |
1 files changed, 317 insertions, 0 deletions
diff --git a/static/netbsd/man9/ioctl.9 b/static/netbsd/man9/ioctl.9 new file mode 100644 index 00000000..bd0977af --- /dev/null +++ b/static/netbsd/man9/ioctl.9 @@ -0,0 +1,317 @@ +.\" $NetBSD: ioctl.9,v 1.37 2025/12/10 19:25:24 andvar 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 July 7, 2022 +.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 '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 '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 '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' +pci(4) +.It 'P' +compat/ossaudio and soundcard.h +.It 'P' +.Xr sparc/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 rnd 4 +.It 's' +the socket layer +.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 +.Aq Pa sys/ioctl.h +or one of the files that are reached from +.Aq Pa sys/ioctl.h . +.Sh RETURN VALUES +All +.Fn 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 EXAMPLES +.Bd -literal -offset indent +#define FOOIOCTL _IOWR('i', 23, int) + +int a = 3; +error = ioctl(s, FOOIOCTL, &a); +.Ed +.Pp +Within the +.Fn ioctl Ns No -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 +.Fn _IOWR +form not the +.Fn _IOR , +as passing the name of the card to the +kernel already consists of writing data. +.Sh SEE ALSO +.Xr ioctl 2 |