Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CAP_RIGHTS_INIT(3)     FreeBSD Library Functions Manual	    CAP_RIGHTS_INIT(3)

NAME
     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

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #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, ...);

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

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

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

DESCRIPTION
     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 struc-
     ture.  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.

RETURN VALUES
     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 argu-
     ment.

     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.

EXAMPLES
     The following example demonstrates	how to prepare a cap_rights_t struc-
     ture 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");

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

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

AUTHORS
     This family of functions was created by Pawel Jakub Dawidek
     <pawel@dawidek.net> under sponsorship from	the FreeBSD Foundation.

FreeBSD	Ports 11.2		March 27, 2014		    FreeBSD Ports 11.2

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cap_rights_init&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help