Manual Pages  — LIBCASPER

The cap_wrap() function creates a cap_channel_t based on the socket supplied in the call. The function is used when a capability is inherited through the execve(2) system call, or sent over a unix(4) domain socket as a file descriptor, and has to be converted into a cap_channel_t. The flags argument defines the channel behavior. The supported flags are:

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

The cap_unwrap() function returns the unix(4) domain socket used by the daemon service, and frees the cap_channel_t structure.

The cap_clone() function returns a clone of the capability passed as its only argument.

The cap_close() function closes, and frees, the given capability.

The cap_sock() function returns the unix(4) domain socket descriptor associated with the given capability for use with system calls such as: kevent(2), poll(2), and select(2).

The cap_limit_get() function stores the current limits of the given capability in the limitsp argument. If the function returns 0 and NULL is stored in the limitsp argument, there are no limits set.

The cap_limit_set() function sets limits for the given capability. The limits are provided as an nvlist(9). The exact format of the limits depends on the service that the capability represents. cap_limit_set() frees the limits passed to the call, whether or not the operation succeeds or fails.

The cap_send_nvlist() function sends the given nvlist(9) over the given capability. This is a low level interface to communicate with casper services. It is expected that most services will provide a 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 a 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 before the function returns.

The cap_service_open() function opens the casper service named in the call using the casper capability obtained via the cap_init() function. The cap_service_open() function returns a capability that provides access to the opened service. Casper supports the following services in the base system:

system.dns	provides libc compatible DNS API
system.fileargs
	provides an API for opening files specified on a command line
system.grp	provides a getgrent(3) compatible API
system.net	provides a libc compatible network API
system.netdb	provides libc compatible network proto API
system.pwd	provides a getpwent(3) compatible API
system.sysctl
	provides a sysctlbyname(3) compatible API
system.syslog
	provides a syslog(3) compatible API

cap_init() must be called from a single-threaded context. cap_clone(), cap_close(), cap_limit_get(), cap_limit_set(), cap_send_nvlist(), cap_recv_nvlist(), and cap_service_open() are reentrant but not thread-safe. That is, they may be called from separate threads only with different cap_channel_t arguments or with synchronization.