---
name: "libcap"
section: "3"
platform: "linux"
package: "libcap"
version: "2.78-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libcap"
---

# libcap(3)

capability data object manipulation

## NAME

cap\_clear, cap\_clear\_flag, cap\_compare, cap\_copy\_ext, cap\_copy\_int, cap\_drop\_bound, cap\_dup, cap\_fill, cap\_fill\_flag, cap\_free, cap\_from\_name, cap\_from\_text, cap\_get\_ambient, cap\_get\_bound, cap\_get\_fd, cap\_get\_file, cap\_get\_flag, cap\_get\_mode, cap\_get\_nsowner, cap\_get\_pid, cap\_get\_pid, cap\_get\_proc, cap\_get\_secbits, cap\_init, cap\_max\_bits, cap\_prctl, cap\_prctlw, cap\_proc\_root, cap\_reset\_ambient, cap\_set\_ambient, cap\_set\_fd, cap\_set\_file, cap\_set\_flag, cap\_setgroups, cap\_set\_mode, cap\_set\_nsowner, cap\_set\_proc, cap\_set\_secbits, cap\_setuid, cap\_size, cap\_to\_name, cap\_to\_text - capability data object manipulation

## SYNOPSIS

```
#include <sys/capability.h>
int cap_clear(cap_t cap_p);
int cap_fill(cap_t cap_p, cap_flag_t to, cap_flag_t from);
int cap_fill_flag(cap_t cap_p, cap_flag_t to, const cap_t ref, cap_flag_t from);
int cap_clear_flag(cap_t cap_p, cap_flag_t flag);
int cap_compare(cap_t cap_a, cap_t cap_b);
ssize_t cap_copy_ext(void *ext_p, cap_t cap_p, ssize_t size);
cap_t cap_copy_int(const void *ext_p);
int cap_free(void *obj_d);
int cap_from_name(const char *name, cap_value_t *cap_p);
cap_t cap_from_text(const char *buf_p);
cap_t cap_get_fd(int fd);
cap_t cap_get_file(const char *path_p);
int cap_get_flag(cap_t cap_p, cap_value_t cap ,
                 cap_flag_t flag, cap_flag_value_t *value_p);
cap_value_t cap_max_bits();
#include <sys/types.h>
cap_t cap_get_pid(pid_t pid);
cap_t cap_get_proc(void);
int cap_set_fd(int fd, cap_t caps);
int cap_set_file(const char *path_p, cap_t cap_p);
int cap_set_flag(cap_t cap_p, cap_flag_t flag, int ncap ,
                 const cap_value_t *caps, cap_flag_value_t value);
int cap_set_proc(cap_t cap_p);
ssize_t cap_size(cap_t cap_p);
char *cap_to_name(cap_value_t cap);
char *cap_to_text(cap_t caps, ssize_t *length_p);
cap_t cap_get_pid(pid_t pid);
cap_t cap_init();
cap_t cap_dup(cap_t cap_p);
char *cap_proc_root(const char *root);
int cap_get_nsowner(cap_t cap_p);
int cap_set_nsowner(cap_t cap_p, uid_t rootuid);
int cap_get_bound(cap_value_t cap);
int cap_drop_bound(cap_value_t cap);
int cap_get_ambient(cap_value_t cap);
int cap_set_ambient(cap_value_t cap, cap_flag_value_t value);
int cap_reset_ambient(void);
int cap_set_mode(cap_mode_t flavor);
cap_mode_t cap_get_mode(void);
const char *cap_mode_name(cap_mode_t flavor);
unsigned cap_get_secbits();
int cap_set_secbits(unsigned bits);
int cap_prctl(long int pr_cmd, long int arg1, long int arg2, long int arg3,
              long int arg4, long int arg5);
int cap_prctlw(long int pr_cmd, long int arg1, long int arg2, long int arg3,
               long int arg4, long int arg5);
int cap_setuid(uid_t uid);
int cap_setgroups(gid_t gid, size_t ngroups, const gid_t groups[]);
```

Link with *-lcap*.

## DESCRIPTION

These primary functions work on a capability state held in working storage and attempt to complete the POSIX.1e (draft) user space API for Capability based privilege.

A *cap\_t* holds information about the capabilities in each of the three sets, Permitted, Inheritable, and Effective.  Each capability in a set may be clear (disabled, 0) or set (enabled, 1).

These functions work with the following data types:

- *cap\_value\_t*

  identifies a capability, such as **CAP\_CHOWN**.

- *cap\_flag\_t*

  identifies one of the three flags associated with a capability (i.e., it identifies one of the three capability sets). Valid values for this type are **CAP\_EFFECTIVE**, **CAP\_INHERITABLE** or **CAP\_PERMITTED**.

- *cap\_flag\_value\_t*

  identifies the setting of a particular capability flag (i.e, the value of a capability in a set). Valid values for this type are **CAP\_CLEAR**(0) or **CAP\_SET**(1).

## RETURN VALUE

The return value is generally specific to the individual function called. On failure, *errno* is set appropriately.

## CONFORMING TO

These functions are as per the withdrawn POSIX.1e draft specification. The following functions are Linux extensions: **cap\_clear\_flag**(), **cap\_drop\_bound**(), **cap\_fill**(), **cap\_fill\_flag**(), **cap\_from\_name**(), **cap\_get\_ambient**(), **cap\_get\_bound**(), **cap\_get\_mode**(), **cap\_get\_nsowner**(), **cap\_get\_secbits**(), **cap\_mode\_name**(), **cap\_proc\_root**(), **cap\_prctl**(), **cap\_prctlw**(), **cap\_reset\_ambient**(), **cap\_setgroups**(), **cap\_setuid**(), **cap\_set\_ambient**(), **cap\_set\_mode**(), **cap\_set\_nsowner**(), **cap\_set\_secbits**(), **cap\_to\_name**() and **cap\_compare**().

A Linux, *IAB*, extension of Inheritable, Bounding and Ambient tuple capability vectors are also supported by **libcap**. Those functions are described in a companion man page: [**cap\_iab**(3)](/cap_iab/3.md). Further, for managing the complexity of launching a sub-process, **libcap** supports the abstraction: [**cap\_launch**(3)](/cap_launch/3.md).

In addition to the **cap\_** prefixed **libcap** API, the library also provides prototypes for the Linux system calls that provide the native API for process capabilities. These prototypes are:

```
int capget(cap_user_header_t header, cap_user_data_t data);
int capset(cap_user_header_t header, const cap_user_data_t data);
```

Further, **libcap** provides a set-up function,

```
void cap_set_syscall(
        long int (*new_syscall)(long int, long int, long int, long int),
        long int (*new_syscall6)(long int,
                                 long int, long int, long int,
                                 long int, long int, long int));
```

which can be used to redirect its use of the **capset**() and other system calls that write kernel managed state. This is especially useful when supporting POSIX semantics for security state. When a program is linked against [**libpsx**(3)](/libpsx/3.md) as described in that man page, this function is used to connect **libcap** to POSIX semantics system calls.

## REPORTING BUGS

The **libcap** library is distributed from https://sites.google.com/site/fullycapable/ where the release notes may already cover recent issues.  Please report newly discovered bugs via:

- https://bugzilla.kernel.org/buglist.cgi?component=libcap&list\_id=1090757

  ## SEE ALSO

[**cap\_clear**(3)](/cap_clear/3.md), [**cap\_copy\_ext**(3)](/cap_copy_ext/3.md), [**cap\_from\_text**(3)](/cap_from_text/3.md), [**cap\_get\_file**(3)](/cap_get_file/3.md), [**cap\_get\_proc**(3)](/cap_get_proc/3.md), [**cap\_iab**(3)](/cap_iab/3.md), [**cap\_init**(3)](/cap_init/3.md), [**cap\_launch**(3)](/cap_launch/3.md), [**capabilities**(7)](/capabilities/7.md), [**getpid**(2)](/getpid/2.md), [**capsh**(1)](/capsh/1.md), [**captree**(8)](/captree/8.md), [**getcap**(8)](/getcap/8.md), [**getpcaps**(8)](/getpcaps/8.md), [**setcap**(8)](/setcap/8.md) and [**libpsx**(3)](/libpsx/3.md).