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