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 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. 64.Pp 65The list of allowed ioctl commands for a given file descriptor can be obtained 66with the 67.Fn cap_ioctls_get 68system call. 69The 70.Fa cmds 71argument points at memory that can hold up to 72.Fa maxcmds 73values. 74The function populates the provided buffer with up to 75.Fa maxcmds 76elements, but always returns the total number of ioctl commands allowed for the 77given file descriptor. 78The total number of ioctls commands for the given file descriptor can be 79obtained by passing 80.Dv NULL as the 81.Fa cmds 82argument and 83.Va 0 84as the 85.Fa maxcmds 86argument. 87If all ioctl commands are allowed 88.Dv ( CAP_IOCTL 89capability right is assigned to the file descriptor and the 90.Fn cap_ioctls_limit 91system call was never called for this file descriptor), the 92.Fn cap_ioctls_get 93system call will return 94.Dv CAP_IOCTLS_ALL 95and won't modify the buffer pointed to by the 96.Fa cmds 97argument. 98.Sh RETURN VALUES 99.Rv -std cap_ioctls_limit 100.Pp 101The 102.Fn cap_ioctls_get 103function, if successful, returns the total number of allowed ioctl commands or 104the value 105.Dv CAP_IOCTLS_ALL 106if all ioctls commands are allowed. 107On failure the value 108.Va -1 109is returned and the global variable errno is set to indicate the error. 110.Sh ERRORS 111.Fn cap_ioctls_limit 112succeeds unless: 113.Bl -tag -width Er 114.It Bq Er EBADF 115The 116.Fa fd 117argument is not a valid descriptor. 118.It Bq Er EFAULT 119The 120.Fa cmds 121argument points at an invalid address. 122.It Bq Er EINVAL 123The 124.Fa ncmds 125argument is greater than 126.Va 256 . 127.It Bq Er ENOTCAPABLE 128.Fa cmds 129would expand the list of allowed 130.Xr ioctl 2 131commands. 132.El 133.Pp 134.Fn cap_ioctls_get 135succeeds unless: 136.Bl -tag -width Er 137.It Bq Er EBADF 138The 139.Fa fd 140argument is not a valid descriptor. 141.It Bq Er EFAULT 142The 143.Fa cmds 144argument 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 151Support for capabilities and capabilities mode was developed as part of the 152.Tn TrustedBSD 153Project. 154.Sh AUTHORS 155This function was created by 156.An Pawel Jakub Dawidek Aq pawel@dawidek.net 157under sponsorship of the FreeBSD Foundation. 158