CAP\_FROM\_TEXT(3) Linux Programmer's Manual CAP\_FROM\_TEXT(3)

# [NAME](#NAME)

cap\_from\_text, cap\_to\_text, cap\_to\_name, cap\_from\_name - capability state textual representation translation

# [SYNOPSIS](#SYNOPSIS)

```
#include <sys/capability.h>
cap_t cap_from_text(const char *buf_p);
char *cap_to_text(cap_t caps, ssize_t *len_p);
int cap_from_name(const char *name, cap_value_t *cap_p);
char *cap_to_name(cap_value_t cap);
```

Link with *-lcap*.

# [DESCRIPTION](#DESCRIPTION)

These functions translate a capability state between an internal representation and a textual one. The internal representation is managed by the capability functions in working storage. The textual representation is a structured, human-readable string suitable for display.

**cap\_from\_text**() allocates and initializes a capability state in working storage. It then sets the contents of this newly created capability state to the state represented by a human-readable, nul-terminated character string pointed to by *buf\_p*. It returns a pointer to the newly created capability state. When the capability state in working storage is no longer required, the caller should free any releasable memory by calling **cap\_free**() with *cap\_t* as an argument. The function returns an error if it cannot parse the contents of the string pointed to by *buf\_p* or does not recognize any *capability\_name* or flag character as valid. The function also returns an error if any flag is both set and cleared within a single clause.

**cap\_to\_text**() converts the capability state in working storage identified by *caps* into a nul-terminated human-readable string. This function allocates any memory necessary to contain the string, and returns a pointer to the string. If the pointer *len\_p* is not NULL, the function shall also return the full length of the string (not including the nul terminator) in the location pointed to by *len\_p*. The capability state in working storage, identified by *caps*, is completely represented in the character string. When the capability state in working storage is no longer required, the caller should free any releasable memory by calling **cap\_free**() with the returned string pointer as an argument.

**cap\_from\_name**() converts a text representation of a capability, such as "cap\_chown", to its numerical representation (**CAP\_CHOWN=0**), writing the decoded value into *\*cap\_p*. If *cap\_p* is NULL no result is written, but the return code of the function indicates whether or not the specified capability can be represented by the library.

**cap\_to\_name**() converts a capability index value, *cap*, to a libcap-allocated textual string. This string should be deallocated with **cap\_free**().

# [TEXTUAL REPRESENTATION](#TEXTUAL_REPRESENTATION)

The text format is described in the [**cap\_text\_formats**(7)](/man/os/libcap/cap_text_formats.7) man page.

# [RETURN VALUE](#RETURN_VALUE)

**cap\_from\_text**(), **cap\_to\_text**() and **cap\_to\_name**() return a non-NULL value on success, and NULL on failure. **cap\_from\_name**() returns 0 for success, and -1 on failure (unknown capability).

On failure, *errno* is set to **EINVAL**, or **ENOMEM**.

# [CONFORMING TO](#CONFORMING_TO)

**cap\_from\_text**() and **cap\_to\_text**() are specified by the withdrawn POSIX.1e draft specification. **cap\_from\_name**() and **cap\_to\_name**() are Linux extensions.

# [EXAMPLE](#EXAMPLE)

The example program below demonstrates the use of **cap\_from\_text**() and **cap\_to\_text**(). The following shell session shows some example runs:

```
$ ./a.out "cap_chown=p cap_chown+e"
caps_to_text() returned "cap_chown=ep"
$ ./a.out "all=pe cap_chown-e cap_kill-pe"
caps_to_text() returned "=ep cap_chown-e cap_kill-ep"
```

The source code of the program is as follows:

```
#include <stdlib.h>
#include <stdio.h>
#include <sys/capability.h>
#define handle_error(msg) \


    do { perror(msg); exit(EXIT_FAILURE); } while (0)
int
main(int argc, char *argv[])
{


    cap_t caps;


    char *txt_caps;


    if (argc != 2) {


        fprintf(stderr, "%s <textual-cap-set>\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    caps = cap_from_text(argv[1]);


    if (caps == NULL)


        handle_error("cap_from_text");


    txt_caps = cap_to_text(caps, NULL);


    if (txt_caps == NULL)


        handle_error("cap_to_text");


    printf("caps_to_text() returned \"%s\"\n", txt_caps);


    if (cap_free(txt_caps) != 0 || cap_free(caps) != 0)


        handle_error("cap_free");


    exit(EXIT_SUCCESS);
}
```

# [SEE ALSO](#SEE_ALSO)

[**libcap**(3)](/man/os/libcap/libcap.3), [**cap\_clear**(3)](/man/os/libcap/cap_clear.3), [**cap\_copy\_ext**(3)](/man/os/libcap/cap_copy_ext.3), [**cap\_get\_file**(3)](/man/os/libcap/cap_get_file.3), [**cap\_get\_proc**(3)](/man/os/libcap/cap_get_proc.3), [**cap\_init**(3)](/man/os/libcap/cap_init.3), [**cap\_text\_formats**(7)](/man/os/libcap/cap_text_formats.7), [**capabilities**(7)](/man/os/libcap/capabilities.7)

2025-03-19

---

Document: cap_from_text(3) from libcap 2.78-r4 (Chainguard OS)
Source: https://kernel.googlesource.com/pub/scm/libs/libcap/libcap.git