CAP_INIT(3)               Linux Programmer's Manual              CAP_INIT(3)

NAME         top

       cap_init,  cap_free, cap_dup - capability data object storage manage‐

SYNOPSIS         top

       #include <sys/capability.h>

       cap_t cap_init(void);

       int cap_free(void *obj_d);

       cap_t cap_dup(cap_t cap_p);

       Link with -lcap.

DESCRIPTION         top

       The capabilities associated with a file or process are never edited
       directly.  Instead, working storage is allocated to contain a
       representation of the capability state.  Capabilities are edited and
       manipulated only within this working storage area.  Once editing of
       the capability state is complete, the updated capability state is
       used to replace the capability state associated with the file or

       cap_init() creates a capability state in working storage and returns
       a pointer to the capability state.  The initial value of all flags
       are cleared.  The caller should free any releasable memory, when the
       capability state in working storage is no longer required, by calling
       cap_free() with the cap_t as an argument.

       cap_free() liberates any releasable memory that has been allocated to
       the capability state identified by obj_d.  The obj_d argument may
       identify either a cap_t entity, or a char * entity allocated by the
       cap_to_text() function.

       cap_dup() returns a duplicate capability state in working storage
       given by the source object cap_p, allocating any memory necessary,
       and returning a pointer to the newly created capability state.  Once
       duplicated, no operation on either capability state affects the other
       in any way.  When the duplicated capability state in working storage
       is no longer required, the caller should free any releasable memory
       by calling cap_free() with the cap_t as an argument.

RETURN VALUE         top

       cap_init() and cap_dup() return a non-NULL value on success, and NULL
       on failure.

       cap_free() returns zero on success, and -1 on failure.

       On failure, errno is set to EINVAL or ENOMEM.

CONFORMING TO         top

       These functions are specified in the withdrawn POSIX.1e draft

SEE ALSO         top

       libcap(3), cap_clear(3), cap_copy_ext(3), cap_from_text(3),
       cap_get_file(3), cap_get_proc(3), capabilities(7)

COLOPHON         top

       This page is part of the libcap (capabilities commands and library)
       project.  Information about the project can be found at 
       ⟨⟩.  If
       you have a bug report for this manual page, send it to (please put "libcap" in the Subject line).  This
       page was obtained from the project's upstream Git repository 
       ⟨git://⟩ on
       2017-03-13.  If you discover any rendering problems in this HTML ver‐
       sion of the page, or you believe there is a better or more up-to-date
       source for the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original man‐
       ual page), send a mail to

                                 2008-05-11                      CAP_INIT(3)