libcap/doc/cap_from_text.3

.\"
.\" written by Andrew Main <zefram@dcs.warwick.ac.uk>
.\"
.TH CAP_FROM_TEXT 3 "2025-03-19" "" "Linux Programmer's Manual"
.SH NAME
cap_from_text, cap_to_text, cap_to_name, cap_from_name \- capability
state textual representation translation
.SH SYNOPSIS
.nf
#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);
.fi
.sp
Link with \fI\-lcap\fP.
.SH 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.
.PP
.BR 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
.IR 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
.BR cap_free ()
with
.I cap_t
as an argument.  The function returns an error if it cannot parse the
contents of the string pointed to by
.I buf_p
or does not recognize any
.I 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.
.PP
.BR cap_to_text ()
converts the capability state in working storage identified by
.I 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
.I 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
.IR len_p .
The capability state in working storage, identified by
.IR 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
.BR cap_free ()
with the returned string pointer as an argument.
.PP
.BR cap_from_name ()
converts a text representation of a capability, such as "cap_chown",
to its numerical representation
.RB ( CAP_CHOWN=0 ),
writing the decoded value into
.IR *cap_p .
If
.I 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.
.PP
.BR cap_to_name ()
converts a capability index value,
.IR cap ,
to a libcap-allocated textual string. This string should be
deallocated with
.BR cap_free ().
.SH "TEXTUAL REPRESENTATION"
The text format is described in the
.BR cap_text_formats (7)
man page.
.SH "RETURN VALUE"
.BR cap_from_text (),
.BR cap_to_text ()
and
.BR cap_to_name ()
return a non-NULL value on success, and NULL on failure.
.BR cap_from_name ()
returns 0 for success, and \-1 on failure (unknown capability).
.PP
On failure,
.I errno
is set to 
.BR EINVAL ,
or 
.BR ENOMEM .
.SH "CONFORMING TO"
.BR cap_from_text ()
and
.BR cap_to_text ()
are specified by the withdrawn POSIX.1e draft specification.
.BR cap_from_name ()
and
.BR cap_to_name ()
are Linux extensions.
.SH EXAMPLE
The example program below demonstrates the use of
.BR cap_from_text ()
and
.BR cap_to_text ().
The following shell session shows some example runs:
.nf

$ ./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"

.fi
The source code of the program is as follows:
.nf

#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);
}
.fi
.SH "SEE ALSO"
.BR libcap (3),
.BR cap_clear (3),
.BR cap_copy_ext (3),
.BR cap_get_file (3),
.BR cap_get_proc (3),
.BR cap_init (3),
.BR cap_text_formats (7),
.BR capabilities (7)