Command Section
CAP_RIGHTS_INIT(3)     FreeBSD Library Functions Manual     CAP_RIGHTS_INIT(3)

     cap_rights_init, cap_rights_set, cap_rights_clear, cap_rights_is_set,
     cap_rights_is_valid, cap_rights_merge, cap_rights_remove,
     cap_rights_contains - manage cap_rights_t structure

     Standard C Library (libc, -lc)

     #include <sys/capsicum.h>

     cap_rights_t *
     cap_rights_init(cap_rights_t *rights, ...);

     cap_rights_t *
     cap_rights_set(cap_rights_t *rights, ...);

     cap_rights_t *
     cap_rights_clear(cap_rights_t *rights, ...);

     cap_rights_is_set(const cap_rights_t *rights, ...);

     cap_rights_is_valid(const cap_rights_t *rights);

     cap_rights_t *
     cap_rights_merge(cap_rights_t *dst, const cap_rights_t *src);

     cap_rights_t *
     cap_rights_remove(cap_rights_t *dst, const cap_rights_t *src);

     cap_rights_contains(const cap_rights_t *big, const cap_rights_t *little);

     The functions documented here allow to manage the cap_rights_t structure.

     Capability rights should be separated with comma when passed to the
     cap_rights_init(), cap_rights_set(), cap_rights_clear() and
     cap_rights_is_set() functions.  For example:

     cap_rights_set(&rights, CAP_READ, CAP_WRITE, CAP_FSTAT, CAP_SEEK);

     The complete list of the capability rights can be found in the rights(4)
     manual page.

     The cap_rights_init() function initialize provided 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 cap_rights_set() function later.
     For even more convenience pointer to the given structure is returned, so
     it can be directly passed to cap_rights_limit(2):

     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");

     The cap_rights_set() function adds the given capability rights to the
     given cap_rights_t structure.

     The cap_rights_clear() function removes the given capability rights from
     the given cap_rights_t structure.

     The cap_rights_is_set() function checks if all the given capability
     rights are set for the given cap_rights_t structure.

     The cap_rights_is_valid() function verifies if the given cap_rights_t
     structure is valid.

     The cap_rights_merge() function merges all capability rights present in
     the src structure into the dst structure.

     The cap_rights_remove() function removes all capability rights present in
     the src structure from the dst structure.

     The cap_rights_contains() function checks if the big structure contains
     all capability rights present in the little structure.

     The functions never fail.  In case an invalid capability right or an
     invalid cap_rights_t structure is given as an argument, the program will
     be aborted.

     The cap_rights_init(), cap_rights_set() and cap_rights_clear() functions
     return pointer to the cap_rights_t structure given in the rights

     The cap_rights_merge() and cap_rights_remove() functions return pointer
     to the cap_rights_t structure given in the dst argument.

     The cap_rights_is_set() returns true if all the given capability rights
     are set in the rights argument.

     The cap_rights_is_valid() function performs various checks to see if the
     given cap_rights_t structure is valid and returns true if it is.

     The cap_rights_contains() function returns true if all capability rights
     set in the little structure are also present in the big structure.

     The following example demonstrates how to prepare a cap_rights_t
     structure to be passed to the cap_rights_limit(2) system call.

     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");

     cap_rights_limit(2), open(2), capsicum(4), rights(4)

     Support for capabilities and capabilities mode was developed as part of
     the TrustedBSD Project.

     This family of functions was created by Pawel Jakub Dawidek
     <[email protected]> under sponsorship from the FreeBSD Foundation.

FreeBSD 11.1-RELEASE-p4         March 27, 2014         FreeBSD 11.1-RELEASE-p4
Command Section