--- name: "cap_clone" section: "3" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/cap_clone" --- # cap\_clone(3) library for handling application capabilities ## NAME **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 capabilities ## LIBRARY library “libcasper” ## SYNOPSIS **#define WITH\_CASPER** **#include \** **#include \** *cap\_channel\_t \**\ **cap\_init**(*void*); *cap\_channel\_t \**\ **cap\_wrap**(*int sock*, *int flags*); *int*\ **cap\_unwrap**(*cap\_channel\_t \*chan*, *int \*flags*); *int*\ **cap\_sock**(*const cap\_channel\_t \*chan*); *cap\_channel\_t \**\ **cap\_clone**(*const cap\_channel\_t \*chan*); *void*\ **cap\_close**(*cap\_channel\_t \*chan*); *int*\ **cap\_limit\_get**(*const cap\_channel\_t \*chan*, *nvlist\_t \*\*limitsp*); *int*\ **cap\_limit\_set**(*const cap\_channel\_t \*chan*, *nvlist\_t \*limits*); *int*\ **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*); ## DESCRIPTION The **libcasper** library provides for the control of application capabilities through the casper process. An application capability, represented by the *cap\_channel\_t* type, is a communication channel between the caller and the casper daemon or an instance of one of the daemon's services. A capability to the casper process, obtained with the **cap\_init**() function, allows a program to create capabilities to access the casper daemon's services via the **cap\_service\_open**() function. The **cap\_init**() function instantiates a capability to allow a program to access the casper daemon. 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)](/execve/2.md) system call, or sent over a [unix(4)](/unix/4.md) 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)](/unix/4.md) 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)](/unix/4.md) domain socket descriptor associated with the given capability for use with system calls such as: [kevent(2)](/kevent/2.md), [poll(2)](/poll/2.md), and [select(2)](/select/2.md). 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)](/nvlist/9.md). 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)](/nvlist/9.md) 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)](/nvlist/9.md) over the given capability. The **cap\_xfer\_nvlist**() function sends the given [nvlist(9)](/nvlist/9.md), destroys it, and receives a new [nvlist(9)](/nvlist/9.md) in response over the given capability. It does not matter if the function succeeds or fails, the [nvlist(9)](/nvlist/9.md) 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)](/getgrent/3.md) compatible API - system.net provides a libc compatible network API - system.netdb provides libc compatible network proto API - system.pwd provides a [getpwent(3)](/getpwent/3.md) compatible API - system.sysctl provides a [sysctlbyname(3)](/sysctlbyname/3.md) compatible API - system.syslog provides a [syslog(3)](/syslog/3.md) 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. ## RETURN VALUES 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 return -1 and set the *errno* variable on failure. The **cap\_close**(), **cap\_sock**() and **cap\_unwrap**() functions always succeed. ## SEE ALSO [errno(2)](/errno/2.md), [execve(2)](/execve/2.md), [kevent(2)](/kevent/2.md), [poll(2)](/poll/2.md), [select(2)](/select/2.md), [cap\_dns(3)](/cap_dns/3.md), [cap\_fileargs(3)](/cap_fileargs/3.md), [cap\_grp(3)](/cap_grp/3.md), [cap\_net(3)](/cap_net/3.md), [cap\_netdb(3)](/cap_netdb/3.md), [cap\_pwd(3)](/cap_pwd/3.md), [cap\_sysctl(3)](/cap_sysctl/3.md), [cap\_syslog(3)](/cap_syslog/3.md), [libcasper\_service(3)](/libcasper_service/3.md), [capsicum(4)](/capsicum/4.md), [unix(4)](/unix/4.md), [nv(9)](/nv/9.md) ## HISTORY The **libcasper** library first appeared in FreeBSD 10.3. ## AUTHORS The **libcasper** library was implemented by Pawel Jakub Dawidek ⟨*pawel@dawidek.net*⟩ under sponsorship from the FreeBSD Foundation. The **libcasper** new architecture was implemented by Mariusz Zaborski ⟨*oshogbo@FreeBSD.org*⟩