Provided by: manpages-dev_3.01-1_all bug

NAME

       capget, capset - set/get capabilities

SYNOPSIS

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

       int capget(cap_user_header_t hdrp, cap_user_data_t datap);

       int capset(cap_user_header_t hdrp, const cap_user_data_t datap);

DESCRIPTION

       As of Linux 2.2, the power of the superuser (root) has been partitioned
       into a set of  discrete  capabilities.   Every  thread  has  a  set  of
       effective  capabilities  identifying which capabilities (if any) it may
       currently exercise.   Every  thread  also  has  a  set  of  inheritable
       capabilities that may be passed through an execve(2) call, and a set of
       permitted capabilities that it can make effective or inheritable.

       These two functions are  the  raw  kernel  interface  for  getting  and
       setting  capabilities.   Not  only  are  these system calls specific to
       Linux, but the kernel  API  is  likely  to  change  and  use  of  these
       functions  (in  particular  the  format  of  the cap_user_*_t types) is
       subject to change with each kernel revision.

       The portable interfaces are  cap_set_proc(3)  and  cap_get_proc(3);  if
       possible  you should use those interfaces in applications.  If you wish
       to use the Linux extensions in applications, you should use the easier-
       to-use interfaces capsetp(3) and capgetp(3).

   Current details
       Now  that  you  have  been  warned,  some  current kernel details.  The
       structs are defined as follows.

           #define _LINUX_CAPABILITY_VERSION  0x19980330

           typedef struct __user_cap_header_struct {
               int version;
               int pid;
           } *cap_user_header_t;

           typedef struct __user_cap_data_struct {
               int effective;
               int permitted;
               int inheritable;
           } *cap_user_data_t;

       The calls will return EINVAL, and set the  version  field  of  hdrp  to
       _LINUX_CAPABILITY_VERSION when another version was specified.

       The  calls  operate  on the capabilities of the thread specified by the
       pid field of hdrp when that is non-zero, or on the capabilities of  the
       calling  thread  if  pid  is  0.   If  pid  refers to a single-threaded
       process, then pid  can  be  specified  as  a  traditional  process  ID;
       operating  on  a thread of a multithreaded process requires a thread ID
       of the type returned by gettid(2).  For capset(), pid can also be:  -1,
       meaning  perform  the  change  on  all  threads  except  the caller and
       init(8); or a value less than -1, in which case the change  is  applied
       to all members of the process group whose ID is -pid.

       For details on the data, see capabilities(7).

RETURN VALUE

       On  success,  zero is returned.  On error, -1 is returned, and errno is
       set appropriately.

ERRORS

       EFAULT Bad memory address.  Neither of hdrp and datap may be NULL.

       EINVAL One of the arguments was invalid.

       EPERM  An attempt was made to add a capability to the Permitted set, or
              to set a capability in the Effective or Inheritable sets that is
              not in the Permitted set.

       EPERM  The caller attempted to use capset() to modify the  capabilities
              of  a thread other than itself, but lacked sufficient privilege;
              the CAP_SETPCAP capability  is  required.   (A  bug  in  kernels
              before 2.6.11 meant that this error could also occur if a thread
              without this capability tried to change its own capabilities  by
              specifying  the  pid  field as a non-zero value (i.e., the value
              returned by getpid(2)) instead of 0.)

       ESRCH  No such thread.

CONFORMING TO

       These system calls are Linux-specific.

NOTES

       The portable interface to the capability querying and setting functions
       is provided by the libcap library and is available here:
       ftp://ftp.kernel.org/pub/linux/libs/security/linux-privs

SEE ALSO

       clone(2), gettid(2), capabilities(7)

COLOPHON

       This  page  is  part of release 3.01 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://www.kernel.org/doc/man-pages/.