1.\" 2.\" Copyright (c) 2013 The FreeBSD Foundation 3.\" All rights reserved. 4.\" 5.\" This documentation was written by Pawel Jakub Dawidek under sponsorship 6.\" from 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_RIGHTS_GET 3 33.Os 34.Sh NAME 35.Nm cap_rights_get 36.Nd obtain capability rights 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In sys/capsicum.h 41.Ft int 42.Fn cap_rights_get "int fd" "cap_rights_t *rights" 43.Sh DESCRIPTION 44The 45.Nm cap_rights_get 46function allows to obtain current capability rights for the given descriptor. 47The function will fill the 48.Fa rights 49argument with all capability rights if they were not limited or capability 50rights configured during the last successful call of 51.Xr cap_rights_limit 2 52on the given descriptor. 53.Pp 54The 55.Fa rights 56argument can be inspected using 57.Xr cap_rights_init 3 58family of functions. 59.Pp 60The complete list of the capability rights can be found in the 61.Xr rights 4 62manual page. 63.Sh RETURN VALUES 64.Rv -std 65.Sh EXAMPLES 66The following example demonstrates how to limit file descriptor capability 67rights and how to obtain them. 68.Bd -literal 69cap_rights_t setrights, getrights; 70int fd; 71 72memset(&setrights, 0, sizeof(setrights)); 73memset(&getrights, 0, sizeof(getrights)); 74 75fd = open("/tmp/foo", O_RDONLY); 76if (fd < 0) 77 err(1, "open() failed"); 78 79cap_rights_init(&setrights, CAP_FSTAT, CAP_READ); 80if (cap_rights_limit(fd, &setrights) < 0 && errno != ENOSYS) 81 err(1, "cap_rights_limit() failed"); 82 83if (cap_rights_get(fd, &getrights) < 0 && errno != ENOSYS) 84 err(1, "cap_rights_get() failed"); 85 86assert(memcmp(&setrights, &getrights, sizeof(setrights)) == 0); 87.Ed 88.Sh ERRORS 89.Fn cap_rights_get 90succeeds unless: 91.Bl -tag -width Er 92.It Bq Er EBADF 93The 94.Fa fd 95argument is not a valid active descriptor. 96.It Bq Er EFAULT 97The 98.Fa rights 99argument points at an invalid address. 100.El 101.Sh SEE ALSO 102.Xr cap_rights_limit 2 , 103.Xr errno 2 , 104.Xr open 2 , 105.Xr assert 3 , 106.Xr cap_rights_init 3 , 107.Xr err 3 , 108.Xr memcmp 3 , 109.Xr memset 3 , 110.Xr capsicum 4 , 111.Xr rights 4 112.Sh HISTORY 113The 114.Fn cap_rights_get 115function first appeared in 116.Fx 9.2 . 117Support for capabilities and capabilities mode was developed as part of the 118.Tn TrustedBSD 119Project. 120.Sh AUTHORS 121This function was created by 122.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net 123under sponsorship of the FreeBSD Foundation. 124