lib/libc/sys/cap_ioctls_limit.2

   1 .\"
   2 .\" Copyright (c) 2012 The FreeBSD Foundation
   3 .\" All rights reserved.
   4 .\"
   5 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
   6 .\" the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd March 27, 2014
  32 .Dt CAP_IOCTLS_LIMIT 2
  33 .Os
  34 .Sh NAME
  35 .Nm cap_ioctls_limit ,
  36 .Nm cap_ioctls_get
  37 .Nd manage allowed ioctl commands
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/capsicum.h
  42 .Ft int
  43 .Fn cap_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds"
  44 .Ft ssize_t
  45 .Fn cap_ioctls_get "int fd" "unsigned long *cmds" "size_t maxcmds"
  46 .Sh DESCRIPTION
  47 If a file descriptor is granted the
  48 .Dv CAP_IOCTL
  49 capability right, the list of allowed
  50 .Xr ioctl 2
  51 commands can be selectively reduced (but never expanded) with the
  52 .Fn cap_ioctls_limit
  53 system call.
  54 The
  55 .Fa cmds
  56 argument is an array of
  57 .Xr ioctl 2
  58 commands and the
  59 .Fa ncmds
  60 argument specifies the number of elements in the array.
  61 There can be up to
  62 .Va 256
  63 elements in the array.
  64 .Pp
  65 The list of allowed ioctl commands for a given file descriptor can be obtained
  66 with the
  67 .Fn cap_ioctls_get
  68 system call.
  69 The
  70 .Fa cmds
  71 argument points at memory that can hold up to
  72 .Fa maxcmds
  73 values.
  74 The function populates the provided buffer with up to
  75 .Fa maxcmds
  76 elements, but always returns the total number of ioctl commands allowed for the
  77 given file descriptor.
  78 The total number of ioctls commands for the given file descriptor can be
  79 obtained by passing
  80 .Dv NULL as the
  81 .Fa cmds
  82 argument and
  83 .Va 0
  84 as the
  85 .Fa maxcmds
  86 argument.
  87 If all ioctl commands are allowed
  88 .Dv ( CAP_IOCTL
  89 capability right is assigned to the file descriptor and the
  90 .Fn cap_ioctls_limit
  91 system call was never called for this file descriptor), the
  92 .Fn cap_ioctls_get
  93 system call will return
  94 .Dv CAP_IOCTLS_ALL
  95 and won't modify the buffer pointed to by the
  96 .Fa cmds
  97 argument.
  98 .Sh RETURN VALUES
  99 .Rv -std cap_ioctls_limit
 100 .Pp
 101 The
 102 .Fn cap_ioctls_get
 103 function, if successful, returns the total number of allowed ioctl commands or
 104 the value
 105 .Dv CAP_IOCTLS_ALL
 106 if all ioctls commands are allowed.
 107 On failure the value
 108 .Va -1
 109 is returned and the global variable errno is set to indicate the error.
 110 .Sh ERRORS
 111 .Fn cap_ioctls_limit
 112 succeeds unless:
 113 .Bl -tag -width Er
 114 .It Bq Er EBADF
 115 The
 116 .Fa fd
 117 argument is not a valid descriptor.
 118 .It Bq Er EFAULT
 119 The
 120 .Fa cmds
 121 argument points at an invalid address.
 122 .It Bq Er EINVAL
 123 The
 124 .Fa ncmds
 125 argument is greater than
 126 .Va 256 .
 127 .It Bq Er ENOTCAPABLE
 128 .Fa cmds
 129 would expand the list of allowed
 130 .Xr ioctl 2
 131 commands.
 132 .El
 133 .Pp
 134 .Fn cap_ioctls_get
 135 succeeds unless:
 136 .Bl -tag -width Er
 137 .It Bq Er EBADF
 138 The
 139 .Fa fd
 140 argument is not a valid descriptor.
 141 .It Bq Er EFAULT
 142 The
 143 .Fa cmds
 144 argument points at invalid address.
 145 .El
 146 .Sh SEE ALSO
 147 .Xr cap_fcntls_limit 2 ,
 148 .Xr cap_rights_limit 2 ,
 149 .Xr ioctl 2
 150 .Sh HISTORY
 151 Support for capabilities and capabilities mode was developed as part of the
 152 .Tn TrustedBSD
 153 Project.
 154 .Sh AUTHORS
 155 This function was created by
 156 .An Pawel Jakub Dawidek Aq pawel@dawidek.net
 157 under sponsorship of the FreeBSD Foundation.