NAME

       cap_get_proc,   cap_set_proc,   capgetp,   cap_get_bound,   cap_drop_bound   -  capability
       manipulation on processes

SYNOPSIS

       #include <sys/capability.h>

       cap_t cap_get_proc(void);

       int cap_set_proc(cap_t cap_p);

       int cap_get_bound(cap_value_t cap);

       CAP_IS_SUPPORTED(cap_value_t cap);

       int cap_drop_bound(cap_value_t cap);

       #include <sys/types.h>

       cap_t cap_get_pid(pid_t pid);

       Link with -lcap.

DESCRIPTION

       cap_get_proc() allocates a capability state in working storage, sets its state to that  of
       the  calling  process,  and returns a pointer to this newly created capability state.  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_set_proc()  sets  the  values  for  all  capability  flags for all capabilities to the
       capability state identified by cap_p.  The new capability state of  the  process  will  be
       completely  determined by the contents of cap_p upon successful return from this function.
       If any flag in cap_p is set for any capability not currently  permitted  for  the  calling
       process,  the  function  will  fail,  and  the capability state of the process will remain
       unchanged.

       cap_get_pid() returns cap_d, see cap_init(3), with the process capabilities of the process
       indicated by pid.  This information can also be obtained from the /proc/<pid>/status file.

       cap_get_bound()  with  a cap as an argument returns the current value of this bounding set
       capability flag in effect for the current process. This operation is unpriveged.  Note,  a
       macro function CAP_IS_SUPPORTED(cap_value_t cap) is provided that evaluates to true (1) if
       the system supports the specified capability, cap.  If the system  does  not  support  the
       capability,  this  function  returns 0. This macro works by testing for an error condition
       with cap_get_bound().

       cap_drop_bound() can be used to lower the  specified  bounding  set  capability,  cap,  To
       complete  successfully,  the  prevailing  effective  capability  set  must  have  a raised
       CAP_SETPCAP.

RETURN VALUE

       The functions cap_get_proc() and cap_get_pid() return a non-NULL  value  on  success,  and
       NULL on failure.

       The  function cap_get_bound() returns -1 if the requested capability is unknown, otherwise
       the return value reflects the current state of that capability in the prevailing  bounding
       set. Note, a macro function,

       The  functions  cap_set_proc()  and  cap_drop_bound()  return  zero for success, and -1 on
       failure.

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

CONFORMING TO

       cap_set_proc()  and  cap_get_proc()  are  specified  in  the  withdrawn   POSIX.1e   draft
       specification.  cap_get_pid() is a Linux extension.

NOTES

       The library also supports the deprecated functions:

       int capgetp(pid_t pid, cap_t cap_d);

       int capsetp(pid_t pid, cap_t cap_d);

       capgetp()  attempts  to  obtain  the  capabilities  of  some  other  process;  storing the
       capabilities in a pre-allocated cap_d.See cap_init()  for  information  on  allocating  an
       empty   capability   set.   This  function,  capgetp(),  is  deprecated,  you  should  use
       cap_get_pid().

       capsetp() attempts to set the capabilities of some other  process(es),  pid.   If  pid  is
       positive  it  refers  to  a  specific  process;   if  it is zero, it refers to the current
       process; -1 refers to all processes  other  than  the  current  process  and  process  '1'
       (typically  init(8));  other negative values refer to the -pid process group.  In order to
       use this function,  the  kernel  must  support  it  and  the  current  process  must  have
       CAP_SETPCAP  raised  in  its  Effective capability set. The capabilities set in the target
       process(es) are those contained in cap_d.  Kernels that  support  filesystem  capabilities
       redefine  the  semantics of CAP_SETPCAP and on such systems this function will always fail
       for any target not equal to the current process.  capsetp() returns zero for success,  and
       -1 on failure.

       Where  supported  by  the  kernel,  the  function  capsetp() should be used with care.  It
       existed, primarily, to  overcome  an  early  lack  of  support  for  capabilities  in  the
       filesystems  supported  by  Linux.   Note  that,  by default, the only processes that have
       CAP_SETPCAP available to them are processes started as a kernel thread.   (Typically  this
       includes  init(8),  kflushd  and  kswapd). You will need to recompile the kernel to modify
       this default.

EXAMPLE

       The code segment below raises the CAP_FOWNER and CAP_SETFCAP  effective  capabilities  for
       the caller:

           cap_t caps;
           cap_value_t cap_list[2];

           if (!CAP_IS_SUPPORTED(CAP_SETFCAP))
               /* handle error */

           caps = cap_get_proc();
           if (caps == NULL)
               /* handle error */;

           cap_list[0] = CAP_FOWNER;
           cap_list[1] = CAP_SETFCAP;
           if (cap_set_flag(caps, CAP_EFFECTIVE, 2, cap_list, CAP_SET) == -1)
               /* handle error */;

           if (cap_set_proc(caps) == -1)
               /* handle error */;

           if (cap_free(caps) == -1)
               /* handle error */;

SEE ALSO

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

                                            2008-05-11                            CAP_GET_PROC(3)