original/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 2000-09-21 "Linux" "Linux Programmer's Manual"
  42 .SH NAME
  43 ioctl \- control device
  44 .SH SYNOPSIS
  45 .B #include <sys/ioctl.h>
  46 .sp
  47 .BI "int ioctl(int " d ", int " request ", ...);"
  48 .SH DESCRIPTION
  49 The
  50 .BR ioctl ()
  51 function manipulates the underlying device parameters of special files.
  52 In particular, many operating characteristics of character special files
  53 (e.g., terminals) may be controlled with
  54 .BR ioctl ()
  55 requests.
  56 The argument
  57 .I d
  58 must be an open file descriptor.
  59 .PP
  60 The second argument is a device-dependent request code.
  61 The third argument is an untyped pointer to memory.
  62 It's traditionally
  63 .BI "char *" argp
  64 (from the days before
  65 .B "void *"
  66 was valid C), and will be so named for this discussion.
  67 .PP
  68 An
  69 .BR ioctl ()
  70 .I request
  71 has encoded in it whether the argument is an
  72 .I in
  73 parameter or
  74 .I out
  75 parameter, and the size of the argument
  76 .I argp
  77 in bytes.
  78 Macros and defines used in specifying an
  79 .BR ioctl ()
  80 .I request
  81 are located in the file
  82 .IR <sys/ioctl.h> .
  83 .SH RETURN VALUE
  84 Usually, on success zero is returned.
  85 A few
  86 .BR ioctl ()
  87 requests use the return value as an output parameter
  88 and return a nonnegative value on success.
  89 On error, \-1 is returned, and
  90 .I errno
  91 is set appropriately.
  92 .SH ERRORS
  93 .TP 0.7i
  94 .B EBADF
  95 .I d
  96 is not a valid descriptor.
  97 .TP
  98 .B EFAULT
  99 .I argp
 100 references an inaccessible memory area.
 101 .TP
 102 .B EINVAL
 103 .I Request
 104 or
 105 .I argp
 106 is not valid.
 107 .TP
 108 .B ENOTTY
 109 .I d
 110 is not associated with a character special device.
 111 .TP
 112 .B ENOTTY
 113 The specified request does not apply to the kind of object that the
 114 descriptor
 115 .I d
 116 references.
 117 .SH CONFORMING TO
 118 No single standard.
 119 Arguments, returns, and semantics of
 120 .BR ioctl ()
 121 vary according to the device driver in question (the call is used as a
 122 catch-all for operations that don't cleanly fit the UNIX stream I/O
 123 model).
 124 See
 125 .BR ioctl_list (2)
 126 for a list of many of the known
 127 .BR ioctl ()
 128 calls.
 129 The
 130 .BR ioctl ()
 131 function call appeared in Version 7 AT&T UNIX.
 132 .SH NOTES
 133 In order to use this call, one needs an open file descriptor.
 134 Often the
 135 .BR open (2)
 136 call has unwanted side effects, that can be avoided under Linux
 137 by giving it the
 138 .B O_NONBLOCK
 139 flag.
 140 .SH SEE ALSO
 141 .BR execve (2),
 142 .BR fcntl (2),
 143 .BR ioctl_list (2),
 144 .BR open (2),
 145 .\" .BR mt (4),
 146 .BR sd (4),
 147 .BR tty (4)