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 May 5, 2020 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 47If a file descriptor is granted the 48.Dv CAP_IOCTL 49capability right, the list of allowed 50.Xr ioctl 2 51commands can be selectively reduced (but never expanded) with the 52.Fn cap_ioctls_limit 53system call. 54The 55.Fa cmds 56argument is an array of 57.Xr ioctl 2 58commands and the 59.Fa ncmds 60argument specifies the number of elements in the array. 61There can be up to 62.Va 256 63elements in the array. 64Including an element that has been previously revoked will generate an error. 65After a successful call only those listed in the array may be used. 66.Pp 67The list of allowed ioctl commands for a given file descriptor can be obtained 68with the 69.Fn cap_ioctls_get 70system call. 71The 72.Fa cmds 73argument points at memory that can hold up to 74.Fa maxcmds 75values. 76The function populates the provided buffer with up to 77.Fa maxcmds 78elements, but always returns the total number of ioctl commands allowed for the 79given file descriptor. 80The total number of ioctls commands for the given file descriptor can be 81obtained by passing 82.Dv NULL as the 83.Fa cmds 84argument and 85.Va 0 86as the 87.Fa maxcmds 88argument. 89If all ioctl commands are allowed 90.Dv ( CAP_IOCTL 91capability right is assigned to the file descriptor and the 92.Fn cap_ioctls_limit 93system call was never called for this file descriptor), the 94.Fn cap_ioctls_get 95system call will return 96.Dv CAP_IOCTLS_ALL 97and will not modify the buffer pointed to by the 98.Fa cmds 99argument. 100.Sh RETURN VALUES 101.Rv -std cap_ioctls_limit 102.Pp 103The 104.Fn cap_ioctls_get 105function, if successful, returns the total number of allowed ioctl commands or 106the value 107.Dv CAP_IOCTLS_ALL 108if all ioctls commands are allowed. 109On failure the value 110.Va -1 111is returned and the global variable errno is set to indicate the error. 112.Sh ERRORS 113.Fn cap_ioctls_limit 114succeeds unless: 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 EINVAL 125The 126.Fa ncmds 127argument is greater than 128.Va 256 . 129.It Bq Er ENOTCAPABLE 130.Fa cmds 131would expand the list of allowed 132.Xr ioctl 2 133commands. 134.El 135.Pp 136.Fn cap_ioctls_get 137succeeds unless: 138.Bl -tag -width Er 139.It Bq Er EBADF 140The 141.Fa fd 142argument is not a valid descriptor. 143.It Bq Er EFAULT 144The 145.Fa cmds 146argument points at invalid address. 147.El 148.Sh SEE ALSO 149.Xr cap_fcntls_limit 2 , 150.Xr cap_rights_limit 2 , 151.Xr ioctl 2 152.Sh HISTORY 153The 154.Fn cap_ioctls_get 155and 156.Fn cap_ioctls_limit 157system calls first appeared in 158.Fx 8.3 . 159Support for capabilities and capabilities mode was developed as part of the 160.Tn TrustedBSD 161Project. 162.Sh AUTHORS 163This function was created by 164.An Pawel Jakub Dawidek Aq Mt [email protected] 165under sponsorship of the FreeBSD Foundation. 166