huschi.net

CAPGET(2)                  Linux Programmer's Manual                 CAPGET(2)

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  effec-
       tive  capabilities  identifying which capabilities (if any) it may cur-
       rently exercise.  Every thread also has a set of inheritable  capabili-
       ties that may be passed through an execve(2) call, and a set of permit-
       ted capabilities that it can make effective or inheritable.
       These two functions are the raw kernel interface for getting  and  set-
       ting  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  hdr  to
       _LINUX_CAPABILITY_VERSION when another version was specified.
       The  calls  operate  on the capabilities of the thread specified by the
       pid field of hdr when that is non-zero, or on the capabilities  of  the
       calling  thread  if  pid is 0.  If pid refers to a single-threaded pro-
       cess, 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
       effect  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.
FURTHER INFORMATION
       The portable interface to the capability querying and setting functions
       is provided by the libcap library and is available from here:
       ftp://ftp.kernel.org/pub/linux/libs/security/linux-privs
SEE ALSO
       clone(2), gettid(2), capabilities(7)

Linux 2.6.6                       2004-06-21                         CAPGET(2)