003 File Manager
Current Path:
/usr/src/lib/libc/capability
usr
/
src
/
lib
/
libc
/
capability
/
📁
..
📄
Makefile.inc
(508 B)
📄
Symbol.map
(200 B)
📄
cap_rights_init.3
(6.21 KB)
Editing: cap_rights_init.3
.\" .\" Copyright (c) 2013 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by Pawel Jakub Dawidek under sponsorship .\" from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 5, 2020 .Dt CAP_RIGHTS_INIT 3 .Os .Sh NAME .Nm cap_rights_init , .Nm cap_rights_set , .Nm cap_rights_clear , .Nm cap_rights_is_set , .Nm cap_rights_is_valid , .Nm cap_rights_merge , .Nm cap_rights_remove , .Nm cap_rights_contains .Nd manage cap_rights_t structure .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capsicum.h .Ft cap_rights_t * .Fn cap_rights_init "cap_rights_t *rights" "..." .Ft cap_rights_t * .Fn cap_rights_set "cap_rights_t *rights" "..." .Ft cap_rights_t * .Fn cap_rights_clear "cap_rights_t *rights" "..." .Ft bool .Fn cap_rights_is_set "const cap_rights_t *rights" "..." .Ft bool .Fn cap_rights_is_valid "const cap_rights_t *rights" .Ft cap_rights_t * .Fn cap_rights_merge "cap_rights_t *dst" "const cap_rights_t *src" .Ft cap_rights_t * .Fn cap_rights_remove "cap_rights_t *dst" "const cap_rights_t *src" .Ft bool .Fn cap_rights_contains "const cap_rights_t *big" "const cap_rights_t *little" .Sh DESCRIPTION The functions documented here allow to manage the .Vt cap_rights_t structure. .Pp Capability rights should be separated with comma when passed to the .Fn cap_rights_init , .Fn cap_rights_set , .Fn cap_rights_clear and .Fn cap_rights_is_set functions. For example: .Bd -literal cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK); .Ed .Pp The complete list of the capability rights can be found in the .Xr rights 4 manual page. .Pp The .Fn cap_rights_init function initialize provided .Vt cap_rights_t structure. Only properly initialized structure can be passed to the remaining functions. For convenience the structure can be filled with capability rights instead of calling the .Fn cap_rights_set function later. For even more convenience pointer to the given structure is returned, so it can be directly passed to .Xr cap_rights_limit 2 : .Bd -literal cap_rights_t rights; if (cap_rights_limit(fd, cap_rights_init(&rights, CAP_READ, CAP_WRITE)) < 0) err(1, "Unable to limit capability rights"); .Ed .Pp The .Fn cap_rights_set function adds the given capability rights to the given .Vt cap_rights_t structure. .Pp The .Fn cap_rights_clear function removes the given capability rights from the given .Vt cap_rights_t structure. .Pp The .Fn cap_rights_is_set function checks if all the given capability rights are set for the given .Vt cap_rights_t structure. .Pp The .Fn cap_rights_is_valid function verifies if the given .Vt cap_rights_t structure is valid. .Pp The .Fn cap_rights_merge function merges all capability rights present in the .Fa src structure into the .Fa dst structure. .Pp The .Fn cap_rights_remove function removes all capability rights present in the .Fa src structure from the .Fa dst structure. .Pp The .Fn cap_rights_contains function checks if the .Fa big structure contains all capability rights present in the .Fa little structure. .Sh RETURN VALUES The functions never fail. In case an invalid capability right or an invalid .Vt cap_rights_t structure is given as an argument, the program will be aborted. .Pp The .Fn cap_rights_init , .Fn cap_rights_set and .Fn cap_rights_clear functions return pointer to the .Vt cap_rights_t structure given in the .Fa rights argument. .Pp The .Fn cap_rights_merge and .Fn cap_rights_remove functions return pointer to the .Vt cap_rights_t structure given in the .Fa dst argument. .Pp The .Fn cap_rights_is_set returns .Va true if all the given capability rights are set in the .Fa rights argument. .Pp The .Fn cap_rights_is_valid function performs various checks to see if the given .Vt cap_rights_t structure is valid and returns .Va true if it is. .Pp The .Fn cap_rights_contains function returns .Va true if all capability rights set in the .Fa little structure are also present in the .Fa big structure. .Sh EXAMPLES The following example demonstrates how to prepare a .Vt cap_rights_t structure to be passed to the .Xr cap_rights_limit 2 system call. .Bd -literal cap_rights_t rights; int fd; fd = open("/tmp/foo", O_RDWR); if (fd < 0) err(1, "open() failed"); cap_rights_init(&rights, CAP_FSTAT, CAP_READ); if (allow_write_and_seek) cap_rights_set(&rights, CAP_WRITE, CAP_SEEK); if (dont_allow_seek) cap_rights_clear(&rights, CAP_SEEK); if (cap_rights_limit(fd, &rights) < 0 && errno != ENOSYS) err(1, "cap_rights_limit() failed"); .Ed .Sh SEE ALSO .Xr cap_rights_limit 2 , .Xr open 2 , .Xr capsicum 4 , .Xr rights 4 .Sh HISTORY The functions .Fn cap_rights_init , .Fn cap_rights_set , .Fn cap_rights_clear , .Fn cap_rights_is_set , .Fn cap_rights_is_valid , .Fn cap_rights_merge , .Fn cap_rights_remove and .Fn cap_rights_contains first appeared in .Fx 8.3 . Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. .Sh AUTHORS This family of functions was created by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship from the FreeBSD Foundation.
Upload File
Create Folder