---
name: "cap_rights_init"
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_rights_clear"
---

# cap\_rights\_init(3)

manage cap\_rights\_t structure

Part of [cap\_rights\_clear(3)](/cap_rights_clear/3.md).

## NAME

**cap\_rights\_init**, **cap\_rights\_set**, **cap\_rights\_clear**, **cap\_rights\_is\_set**, **cap\_rights\_is\_empty**, **cap\_rights\_is\_valid**, **cap\_rights\_intersect**, **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\_empty**(*const cap\_rights\_t \*rights*);

*bool*\

**cap\_rights\_is\_valid**(*const cap\_rights\_t \*rights*);

*cap\_rights\_t* *\**\

**cap\_rights\_intersect**(*cap\_rights\_t \*dst*, *const cap\_rights\_t \*src*);

*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)](/rights/4.md) manual page.

The **cap\_rights\_init**() function initialize provided *cap\_rights\_t* structure. 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_limit/2.md):

```
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\_empty**() function checks if the *rights* structure is empty.

The **cap\_rights\_is\_valid**() function verifies if the given *cap\_rights\_t* structure is valid.

The **cap\_rights\_intersect**() function clears all capability rights from the *dst* structure that are not present in the *src* structure, leaving only the rights common to both.

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* argument.

The **cap\_rights\_merge**(), **cap\_rights\_remove**() and **cap\_rights\_intersect**() 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\_empty**() function returns *true* if none of the capability rights are set in the *rights* structure.

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* structure to be passed to the [cap\_rights\_limit(2)](/cap_rights_limit/2.md) 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)](/cap_rights_limit/2.md), [open(2)](/open/2.md), [capsicum(4)](/capsicum/4.md), [rights(4)](/rights/4.md)

## HISTORY

The functions **cap\_rights\_init**(), **cap\_rights\_set**(), **cap\_rights\_clear**(), **cap\_rights\_is\_set**(), **cap\_rights\_is\_valid**(), **cap\_rights\_merge**(), **cap\_rights\_remove**() and **cap\_rights\_contains**() first appeared in FreeBSD 8.3. 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.