packages/net/common/v2_0/doc/manpages/sys/ioctl.2

   1 .\"     $OpenBSD: ioctl.2,v 1.11 2001/07/30 01:12:43 deraadt Exp $
   2 .\"     $NetBSD: ioctl.2,v 1.5 1995/02/27 12:33:47 cgd Exp $
   3 .\"
   4 .\" Copyright (c) 1980, 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)ioctl.2     8.2 (Berkeley) 12/11/93
  36 .\"
  37 .Dd December 11, 1993
  38 .Dt IOCTL 2
  39 .Os
  40 .Sh NAME
  41 .Nm ioctl
  42 .Nd control device
  43 .Sh SYNOPSIS
  44 .Fd #include <sys/ioctl.h>
  45 .Ft int
  46 .Fn ioctl "int d" "unsigned long request" "..."
  47 .Sh DESCRIPTION
  48 The
  49 .Fn ioctl
  50 function manipulates the underlying device parameters of special files.
  51 In particular, many operating
  52 characteristics of character special files (e.g., terminals)
  53 may be controlled with
  54 .Fn ioctl
  55 requests.
  56 .Pp
  57 The argument
  58 .Fa d
  59 must be an open file descriptor. The third argument is called
  60 .Fa arg
  61 and contains additional information needed by this device
  62 to perform the requested function.
  63 .Fa arg
  64 is either an
  65 .Li int
  66 or a pointer to a device-specific data structure, depending upon
  67 the given
  68 .Fa request .
  69 .Pp
  70 An
  71 .Nm
  72 .Fa request
  73 has encoded in it whether the argument is an
  74 .Dq in
  75 parameter
  76 or
  77 .Dq out
  78 parameter, and the size of the third argument
  79 .Pq Fa arg
  80 in bytes.
  81 Macros and defines used in specifying an ioctl
  82 .Fa request
  83 are located in the file
  84 .Ao Pa sys/ioctl.h Ac .
  85 .Sh RETURN VALUES
  86 If an error has occurred, a value of \-1 is returned and
  87 .Va errno
  88 is set to indicate the error.
  89 .Sh ERRORS
  90 .Fn ioctl
  91 will fail if:
  92 .Bl -tag -width Er
  93 .It Bq Er EBADF
  94 .Fa d
  95 is not a valid descriptor.
  96 .It Bq Er ENOTTY
  97 .Fa d
  98 is not associated with a character
  99 special device.
 100 .It Bq Er ENOTTY
 101 The specified request does not apply to the kind
 102 of object that the descriptor
 103 .Fa d
 104 references.
 105 .It Bq Er EINVAL
 106 .Fa request
 107 or
 108 .Fa arg
 109 is not valid.
 110 .It Bq Er EFAULT
 111 .Fa arg
 112 points outside the process's allocated address space.
 113 .El
 114 .Sh SEE ALSO
 115 .Xr cdio 1 ,
 116 .Xr chio 1 ,
 117 .Xr mt 1 ,
 118 .Xr execve 2 ,
 119 .Xr fcntl 2 ,
 120 .Xr intro 4 ,
 121 .Xr tty 4
 122 .Sh HISTORY
 123 An
 124 .Fn ioctl
 125 function call appeared in
 126 .At v7 .