man2/ioctl.2

   1 .\" Copyright (c) 1980, 1991 Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" SPDX-License-Identifier: BSD-4-Clause-UC
   5 .\"
   6 .\"     @(#)ioctl.2     6.4 (Berkeley) 3/10/91
   7 .\"
   8 .\" Modified 1993-07-23 by Rik Faith <faith@cs.unc.edu>
   9 .\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com>
  10 .\" Modified 1999-06-25 by Rachael Munns <vashti@dream.org.uk>
  11 .\" Modified 2000-09-21 by Andries Brouwer <aeb@cwi.nl>
  12 .\"
  13 .TH ioctl 2 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 ioctl \- control device
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <sys/ioctl.h>
  22 .PP
  23 .BI "int ioctl(int " fd ", unsigned long " request ", ...);"
  24 .\" POSIX says 'request' is int, but glibc has the above
  25 .\" See https://bugzilla.kernel.org/show_bug.cgi?id=42705
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .BR ioctl ()
  30 system call manipulates the underlying device parameters of special files.
  31 In particular, many operating characteristics of character special files
  32 (e.g., terminals) may be controlled with
  33 .BR ioctl ()
  34 requests.
  35 The argument
  36 .I fd
  37 must be an open file descriptor.
  38 .PP
  39 The second argument is a device-dependent request code.
  40 The third argument is an untyped pointer to memory.
  41 It's traditionally
  42 .BI "char *" argp
  43 (from the days before
  44 .B "void *"
  45 was valid C), and will be so named for this discussion.
  46 .PP
  47 An
  48 .BR ioctl ()
  49 .I request
  50 has encoded in it whether the argument is an
  51 .I in
  52 parameter or
  53 .I out
  54 parameter, and the size of the argument
  55 .I argp
  56 in bytes.
  57 Macros and defines used in specifying an
  58 .BR ioctl ()
  59 .I request
  60 are located in the file
  61 .IR <sys/ioctl.h> .
  62 See NOTES.
  63 .SH RETURN VALUE
  64 Usually, on success zero is returned.
  65 A few
  66 .BR ioctl ()
  67 requests use the return value as an output parameter
  68 and return a nonnegative value on success.
  69 On error, \-1 is returned, and
  70 .I errno
  71 is set to indicate the error.
  72 .SH ERRORS
  73 .TP
  74 .B EBADF
  75 .I fd
  76 is not a valid file descriptor.
  77 .TP
  78 .B EFAULT
  79 .I argp
  80 references an inaccessible memory area.
  81 .TP
  82 .B EINVAL
  83 .I request
  84 or
  85 .I argp
  86 is not valid.
  87 .TP
  88 .B ENOTTY
  89 .I fd
  90 is not associated with a character special device.
  91 .TP
  92 .B ENOTTY
  93 The specified request does not apply to the kind of object that the
  94 file descriptor
  95 .I fd
  96 references.
  97 .SH STANDARDS
  98 No single standard.
  99 Arguments, returns, and semantics of
 100 .BR ioctl ()
 101 vary according to the device driver in question (the call is used as a
 102 catch-all for operations that don't cleanly fit the UNIX stream I/O
 103 model).
 104 .PP
 105 The
 106 .BR ioctl ()
 107 system call appeared in Version 7 AT&T UNIX.
 108 .SH NOTES
 109 In order to use this call, one needs an open file descriptor.
 110 Often the
 111 .BR open (2)
 112 call has unwanted side effects, that can be avoided under Linux
 113 by giving it the
 114 .B O_NONBLOCK
 115 flag.
 116 .\"
 117 .SS ioctl structure
 118 .\" added two sections - aeb
 119 Ioctl command values are 32-bit constants.
 120 In principle these constants are completely arbitrary, but people have
 121 tried to build some structure into them.
 122 .PP
 123 The old Linux situation was that of mostly 16-bit constants, where the
 124 last byte is a serial number, and the preceding byte(s) give a type
 125 indicating the driver.
 126 Sometimes the major number was used: 0x03
 127 for the
 128 .B HDIO_*
 129 ioctls, 0x06 for the
 130 .B LP*
 131 ioctls.
 132 And sometimes
 133 one or more ASCII letters were used.
 134 For example,
 135 .B TCGETS
 136 has value
 137 0x00005401, with 0x54 = \(aqT\(aq indicating the terminal driver, and
 138 .B CYGETTIMEOUT
 139 has value 0x00435906, with 0x43 0x59 = \(aqC\(aq \(aqY\(aq
 140 indicating the cyclades driver.
 141 .PP
 142 Later (0.98p5) some more information was built into the number.
 143 One has 2 direction bits
 144 (00: none, 01: write, 10: read, 11: read/write)
 145 followed by 14 size bits (giving the size of the argument),
 146 followed by an 8-bit type (collecting the ioctls in groups
 147 for a common purpose or a common driver), and an 8-bit
 148 serial number.
 149 .PP
 150 The macros describing this structure live in
 151 .I <asm/ioctl.h>
 152 and are
 153 .B _IO(type,nr)
 154 and
 155 .BR "{_IOR,_IOW,_IOWR}(type,nr,size)" .
 156 They use
 157 .I sizeof(size)
 158 so that size is a
 159 misnomer here: this third argument is a data type.
 160 .PP
 161 Note that the size bits are very unreliable: in lots of cases
 162 they are wrong, either because of buggy macros using
 163 .IR sizeof(sizeof(struct)) ,
 164 or because of legacy values.
 165 .PP
 166 Thus, it seems that the new structure only gave disadvantages:
 167 it does not help in checking, but it causes varying values
 168 for the various architectures.
 169 .SH SEE ALSO
 170 .BR execve (2),
 171 .BR fcntl (2),
 172 .BR ioctl_console (2),
 173 .BR ioctl_fat (2),
 174 .BR ioctl_ficlone (2),
 175 .BR ioctl_ficlonerange (2),
 176 .BR ioctl_fideduperange (2),
 177 .BR ioctl_fslabel (2),
 178 .BR ioctl_getfsmap (2),
 179 .BR ioctl_iflags (2),
 180 .BR ioctl_ns (2),
 181 .BR ioctl_tty (2),
 182 .BR ioctl_userfaultfd (2),
 183 .BR open (2),
 184 .\" .BR mt (4),
 185 .BR sd (4),
 186 .BR tty (4)