cap_envl(3C)

NAME
     cap_envl, cap_envp - ensure sufficient process privilege

SYNOPSIS
     #include <sys/capability.h>

     int cap_envl(int flags, ... /* cap_value_t */)

     int cap_envp(int flags, size_t ncap, const cap_value_t *caps)

DESCRIPTION
     cap_envl and cap_envp ensure that the calling process will have
     sufficient privilege to perform actions requiring the specified
     capabilities.

     cap_envl accepts a variable argument list of capability values,
     terminated by an argument of 0 (or CAP_NOT_A_CID).

     cap_envp accepts a counted array of capability values, whose size is
     specified by ncap and whose address is caps.

     cap_envl and cap_envp also understand several flags, which may be
     bitwise-ored together:

     CAP_ENV_SETUID  If successful, set the process' effective userid to its
                     real userid.

     CAP_ENV_RECALC  If successful, set the CAP_FLAG_PURE_RECALC capability
                     flag.

     cap_envl and cap_envp will return an error if they cannot give the
     calling process privilege equivalent to having the capabilities specified
     in caps, or if the optional actions specified by flags were not
     successful.

RETURN VALUES
     cap_envl and cap_envp return 0 if successful, or -1 on error.

ERRORS
     cap_envl:

     EINVAL          One of the specified capabilties is invalid.

     EPERM           The calling process has insufficient privilege to perform
                     privileged actions requiring the requested capabilities.

     cap_envp:

     EINVAL          ncap is 0, caps is NULL, or one of the specified
                     capabilties is invalid.
     EPERM           The calling process has insufficient privilege to perform
                     privileged actions requiring the requested capabilities.

SEE ALSO
     cap_set_proc(3c), capabilities(4).