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. If the desired and current capability sets are different
     and if the desired capability set can be obtained because the process has
     the CAP_SETPCAP capability, then the capabilities in the desired will be
     acquired.

     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 capabilities 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
                     capabilities 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).