capgetp

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



NAME
       cap_get_proc, cap_set_proc - POSIX capability manipulation on processes

       capgetp, capsetp - Linux specific capability manipulation on  arbitrary
       processes

SYNOPSIS
       #include <sys/capability.h>

       cap_t cap_get_proc(void);
       int cap_set_proc(cap_t cap_p);

       #undef _POSIX_SOURCE
       #include <sys/capability.h>

       cap_t capgetp(pid_t pid, cap_t cap_d);
       cap_t capsetp(pid_t pid, cap_t cap_d);


USAGE
       cc ... -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 capabili-
       ties with 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 pro-
       cess, the function will fail, and the capability state of  the  process
       will remain unchanged.

       capgetp  fills  an  existing  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.

       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 current process must have CAP_SETPCAP raised in  its
       Effective  capability  set.   The  capabilities  set in the target pro-
       cess(es) are those contained in cap_d.


RETURN VALUE
       cap_get_proc returns a non-NULL value on success, and NULL on  failure.

       cap_set_proc,  capgetp  and  capsetp return zero for success, and -1 on
       failure.

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

CONFORMING TO
       cap_set_proc and cap_get_proc are functions specified in the draft  for
       POSIX.1e.


NOTES
       The  function  capsetp should be used with care.  It exists, primarily,
       to overcome a lack of support for capabilities in any of  the  filesys-
       tems  supported by Linux.  The semantics of this function may change as
       it is better understood.  Please note, by default, the  only  processes
       that have CAP_SETPCAP available to them are processes started as a ker-
       nel-thread.  (Typically this includes init(8), kflushd and kswapd). You
       will need to recompile the kernel to modify this default.


SEE ALSO
       cap_clear(3),   cap_copy_ext(3),   cap_from_text(3),   cap_get_file(3),
       cap_init(3)



                                 26th May 1997                 CAP_GET_PROC(3)