man2/ioctl.2

   1 .\" Copyright (c) 1980, 1991 Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     @(#)ioctl.2     6.4 (Berkeley) 3/10/91
  35 .\"
  36 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
  37 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
  38 .\" Modified 1999-06-25 by Rachael Munns <vashti@dream.org.uk>
  39 .\" Modified 2000-09-21 by Andries Brouwer <aeb@cwi.nl>
  40 .\"
  41 .TH IOCTL 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  42 .SH NAME
  43 ioctl \- control device
  44 .SH SYNOPSIS
  45 .nf
  46 .B #include <sys/ioctl.h>
  47 .PP
  48 .BI "int ioctl(int " fd ", unsigned long " request ", ...);"
  49 .\" POSIX says 'request' is int, but glibc has the above
  50 .\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705
  51 .fi
  52 .SH DESCRIPTION
  53 The
  54 .BR ioctl ()
  55 system call manipulates the underlying device parameters of special files.
  56 In particular, many operating characteristics of character special files
  57 (e.g., terminals) may be controlled with
  58 .BR ioctl ()
  59 requests.
  60 The argument
  61 .I fd
  62 must be an open file descriptor.
  63 .PP
  64 The second argument is a device-dependent request code.
  65 The third argument is an untyped pointer to memory.
  66 It's traditionally
  67 .BI "char *" argp
  68 (from the days before
  69 .B "void *"
  70 was valid C), and will be so named for this discussion.
  71 .PP
  72 An
  73 .BR ioctl ()
  74 .I request
  75 has encoded in it whether the argument is an
  76 .I in
  77 parameter or
  78 .I out
  79 parameter, and the size of the argument
  80 .I argp
  81 in bytes.
  82 Macros and defines used in specifying an
  83 .BR ioctl ()
  84 .I request
  85 are located in the file
  86 .IR <sys/ioctl.h> .
  87 See NOTES.
  88 .SH RETURN VALUE
  89 Usually, on success zero is returned.
  90 A few
  91 .BR ioctl ()
  92 requests use the return value as an output parameter
  93 and return a nonnegative value on success.
  94 On error, \-1 is returned, and
  95 .I errno
  96 is set to indicate the error.
  97 .SH ERRORS
  98 .TP
  99 .B EBADF
 100 .I fd
 101 is not a valid file descriptor.
 102 .TP
 103 .B EFAULT
 104 .I argp
 105 references an inaccessible memory area.
 106 .TP
 107 .B EINVAL
 108 .I request
 109 or
 110 .I argp
 111 is not valid.
 112 .TP
 113 .B ENOTTY
 114 .I fd
 115 is not associated with a character special device.
 116 .TP
 117 .B ENOTTY
 118 The specified request does not apply to the kind of object that the
 119 file descriptor
 120 .I fd
 121 references.
 122 .SH CONFORMING TO
 123 No single standard.
 124 Arguments, returns, and semantics of
 125 .BR ioctl ()
 126 vary according to the device driver in question (the call is used as a
 127 catch-all for operations that don't cleanly fit the UNIX stream I/O
 128 model).
 129 .PP
 130 The
 131 .BR ioctl ()
 132 system call appeared in Version 7 AT&T UNIX.
 133 .SH NOTES
 134 In order to use this call, one needs an open file descriptor.
 135 Often the
 136 .BR open (2)
 137 call has unwanted side effects, that can be avoided under Linux
 138 by giving it the
 139 .B O_NONBLOCK
 140 flag.
 141 .\"
 142 .SS ioctl structure
 143 .\" added two sections - aeb
 144 Ioctl command values are 32-bit constants.
 145 In principle these constants are completely arbitrary, but people have
 146 tried to build some structure into them.
 147 .PP
 148 The old Linux situation was that of mostly 16-bit constants, where the
 149 last byte is a serial number, and the preceding byte(s) give a type
 150 indicating the driver.
 151 Sometimes the major number was used: 0x03
 152 for the
 153 .B HDIO_*
 154 ioctls, 0x06 for the
 155 .B LP*
 156 ioctls.
 157 And sometimes
 158 one or more ASCII letters were used.
 159 For example,
 160 .B TCGETS
 161 has value
 162 0x00005401, with 0x54 = \(aqT\(aq indicating the terminal driver, and
 163 .B CYGETTIMEOUT
 164 has value 0x00435906, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq
 165 indicating the cyclades driver.
 166 .PP
 167 Later (0.98p5) some more information was built into the number.
 168 One has 2 direction bits
 169 (00: none, 01: write, 10: read, 11: read/write)
 170 followed by 14 size bits (giving the size of the argument),
 171 followed by an 8-bit type (collecting the ioctls in groups
 172 for a common purpose or a common driver), and an 8-bit
 173 serial number.
 174 .PP
 175 The macros describing this structure live in
 176 .I <asm/ioctl.h>
 177 and are
 178 .B _IO(type,nr)
 179 and
 180 .BR "{_IOR,_IOW,_IOWR}(type,nr,size)" .
 181 They use
 182 .I sizeof(size)
 183 so that size is a
 184 misnomer here: this third argument is a data type.
 185 .PP
 186 Note that the size bits are very unreliable: in lots of cases
 187 they are wrong, either because of buggy macros using
 188 .IR sizeof(sizeof(struct)) ,
 189 or because of legacy values.
 190 .PP
 191 Thus, it seems that the new structure only gave disadvantages:
 192 it does not help in checking, but it causes varying values
 193 for the various architectures.
 194 .SH SEE ALSO
 195 .BR execve (2),
 196 .BR fcntl (2),
 197 .BR ioctl_console (2),
 198 .BR ioctl_fat (2),
 199 .BR ioctl_ficlonerange (2),
 200 .BR ioctl_fideduperange (2),
 201 .BR ioctl_fslabel (2),
 202 .BR ioctl_getfsmap (2),
 203 .BR ioctl_iflags (2),
 204 .BR ioctl_ns (2),
 205 .BR ioctl_tty (2),
 206 .BR ioctl_userfaultfd (2),
 207 .BR open (2),
 208 .\" .BR mt (4),
 209 .BR sd (4),
 210 .BR tty (4)