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

FreeBSD Manual Pages


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

     cap_init, cap_wrap, cap_unwrap, cap_sock, cap_clone, cap_close,
     cap_limit_get, cap_limit_set, cap_send_nvlist, cap_recv_nvlist,
     cap_xfer_nvlist, cap_service_open -- library for handling application ca-

     library "libcasper"

     #define WITH_CASPER
     #include <sys/nv.h>
     #include <libcasper.h>

     cap_channel_t *

     cap_channel_t *
     cap_wrap(int sock,	int flags);

     cap_unwrap(cap_channel_t *chan, int *flags);

     cap_sock(const cap_channel_t *chan);

     cap_channel_t *
     cap_clone(const cap_channel_t *chan);

     cap_close(cap_channel_t *chan);

     cap_limit_get(const cap_channel_t *chan, nvlist_t **limitsp);

     cap_limit_set(const cap_channel_t *chan, nvlist_t *limits);

     cap_send_nvlist(const cap_channel_t *chan,	const nvlist_t *nvl);

     nvlist_t *
     cap_recv_nvlist(const cap_channel_t *chan);

     nvlist_t *
     cap_xfer_nvlist(const cap_channel_t *chan,	nvlist_t *nvl);

     cap_channel_t *
     cap_service_open(const cap_channel_t *chan, const char *name);

     The libcasper library allows to manage application	capabilities through
     the casper	process.

     The application capability	(represented by	the cap_channel_t type)	is a
     communication channel between the caller and the casper process daemon or
     an	instance of one	of its services.  A capability to the casper process
     obtained with the cap_init() function allows to create capabilities to
     casper's services via the cap_service_open() function.

     The cap_init() function opens capability to the casper process.

     The cap_wrap() function creates cap_channel_t based on the	given socket.
     The function is used when capability is inherited through execve(2) or
     send over unix(4) domain socket as	a regular file descriptor and has to
     be	represented as cap_channel_t again.  The flags argument	defines	the
     channel behavior.	The supported flags are:

	   The communication between process and casper	uses no	unique version
	   of nvlist.

     The cap_unwrap() function is the opposite of the cap_wrap() function.  It
     frees the cap_channel_t structure and returns unix(4) domain socket asso-
     ciated with it.

     The cap_clone() function clones the given capability.

     The cap_close() function closes the given capability.

     The cap_sock() function returns unix(4) domain socket descriptor associ-
     ated with the given capability for	use with system	calls like kevent(2),
     poll(2) and select(2).

     The cap_limit_get() function stores current limits	of the given capabil-
     ity in the	limitsp	argument.  If the function return 0 and	NULL is	stored
     in	limitsp	it means there are no limits set.

     The cap_limit_set() function sets limits for the given capability.	 The
     limits are	provided as a nvlist(9).  The exact format depends on the ser-
     vice the capability represents.  cap_limit_set() frees the	limits regard-
     less of whether the operation succeeds or fails.

     The cap_send_nvlist() function sends the given nvlist(9) over the given
     capability.  This is low level interface to communicate with casper ser-
     vices.  Most services should provide higher level API.

     The cap_recv_nvlist() function receives the given nvlist(9) over the
     given capability.

     The cap_xfer_nvlist() function sends the given nvlist(9), destroys	it and
     receives new nvlist(9) in response	over the given capability.  It does
     not matter	if the function	succeeds or fails, the nvlist(9) given for
     sending will always be destroyed once the function	returns.

     The cap_service_open() function opens casper service of the given name
     through casper capability obtained	via the	cap_init() function.  The
     function returns capability that provides access to opened	service.
     Casper supports the following services in the base	system:

	   system.dns	  provides DNS libc compatible API
	   system.grp	  provides getgrent(3) compatible API	  provides network libc	compatible API
	   system.pwd	  provides getpwent(3) compatible API
	   system.sysctl  provides sysctlbyname(3) compatible API
	   system.syslog  provides syslog(3) compatible	API

     The cap_clone(), cap_init(), cap_recv_nvlist(), cap_service_open(),
     cap_wrap()	and cap_xfer_nvlist() functions	return NULL and	set the	errno
     variable on failure.

     The cap_limit_get(), cap_limit_set() and cap_send_nvlist()	functions re-
     turn -1 and set the errno variable	on failure.

     The cap_close(), cap_sock() and cap_unwrap() functions always succeed.

     errno(2), execve(2), kevent(2), poll(2), select(2), cap_dns(3),
     cap_grp(3), cap_net(3), cap_pwd(3), cap_sysctl(3),	cap_syslog(3),
     libcasper_service(3), capsicum(4),	unix(4), nv(9)

     The libcasper library first appeared in FreeBSD 10.3.

     The libcasper library was implemented by Pawel Jakub Dawidek
     <> under sponsorship from	the FreeBSD Foundation.	 The
     libcasper new architecture	was implemented	by
     Mariusz Zaborski <>

FreeBSD	13.0			January	3, 2021			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help