man2/capget.2

   1 .\"
   2 .\" $Id: capget.2,v 1.4 1999/09/09 16:43:26 morgan Exp $
   3 .\" written by Andrew Morgan <morgan@linux.kernel.org>
   4 .\" may be distributed as per GPL
   5 .\" Modified by David A. Wheeler <dwheeler@ida.org>
   6 .\" Modified 2004-05-27, mtk
   7 .\" Modified 2004-06-21, aeb
   8 .\"
   9 .TH CAPGET 2 2004-06-21 "Linux" "Linux Programmer's Manual"
  10 .SH NAME
  11 capget, capset \- set/get capabilities
  12 .SH SYNOPSIS
  13 .B #undef _POSIX_SOURCE
  14 .br
  15 .B #include <sys/capability.h>
  16 .sp
  17 .BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
  18 .sp
  19 .BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
  20 .SH DESCRIPTION
  21 As of Linux 2.2, the power of the superuser (root) has been partitioned into
  22 a set of discrete capabilities.
  23 Every thread has a set of effective capabilities identifying
  24 which capabilities (if any) it may currently exercise.
  25 Every thread also has a set of inheritable capabilities that may be
  26 passed through an
  27 .BR execve (2)
  28 call, and a set of permitted capabilities
  29 that it can make effective or inheritable.
  30 .PP
  31 These two functions are the raw kernel interface for getting and
  32 setting capabilities.
  33 Not only are these system calls specific to Linux,
  34 but the kernel API is likely to change and use of
  35 these functions (in particular the format of the
  36 .B cap_user_*_t
  37 types) is subject to change with each kernel revision.
  38 .sp
  39 The portable interfaces are
  40 .BR cap_set_proc (3)
  41 and
  42 .BR cap_get_proc (3);
  43 if possible you should use those interfaces in applications.
  44 If you wish to use the Linux extensions in applications, you should
  45 use the easier-to-use interfaces
  46 .BR capsetp (3)
  47 and
  48 .BR capgetp (3).
  49 .SS "Current details"
  50 Now that you have been warned, some current kernel details.
  51 The structs are defined as follows.
  52 .sp
  53 .nf
  54 .in +4n
  55 #define _LINUX_CAPABILITY_VERSION  0x19980330
  56
  57 typedef struct __user_cap_header_struct {
  58     int version;
  59     int pid;
  60 } *cap_user_header_t;
  61
  62 typedef struct __user_cap_data_struct {
  63     int effective;
  64     int permitted;
  65     int inheritable;
  66 } *cap_user_data_t;
  67 .fi
  68 .in -4n
  69 .sp
  70 The calls will return
  71 .BR EINVAL ,
  72 and set the
  73 .I version
  74 field of
  75 .I hdr
  76 to
  77 .B _LINUX_CAPABILITY_VERSION
  78 when another version was specified.
  79
  80 The calls operate on the capabilities of the thread specified by the
  81 .I pid
  82 field of
  83 .I hdr
  84 when that is non-zero, or on the capabilities of the calling thread if
  85 .I pid
  86 is 0.
  87 If
  88 .I pid
  89 refers to a single-threaded process, then
  90 .I pid
  91 can be specified as a traditional process ID;
  92 operating on a thread of a multithreaded process requires a thread ID
  93 of the type returned by
  94 .BR gettid (2).
  95 For
  96 .BR capset (),
  97 .I pid
  98 can also be: \-1, meaning perform the change on all threads except the
  99 caller and
 100 .BR init (8);
 101 or a value less than \-1, in which case the change is applied
 102 to all members of the process group whose ID is \-\fIpid\fP.
 103
 104 For details on the data, see
 105 .BR capabilities (7).
 106 .SH "RETURN VALUE"
 107 On success, zero is returned.
 108 On error, \-1 is returned, and
 109 .I errno
 110 is set appropriately.
 111 .SH ERRORS
 112 .TP
 113 .B EFAULT
 114 Bad memory address.
 115 Neither of
 116 .I hdrp
 117 and
 118 .I datap
 119 may be NULL.
 120 .TP
 121 .B EINVAL
 122 One of the arguments was invalid.
 123 .TP
 124 .B EPERM
 125 An attempt was made to add a capability to the Permitted set, or to set
 126 a capability in the Effective or Inheritable sets that is not in the
 127 Permitted set.
 128 .TP
 129 .B EPERM
 130 The caller attempted to use
 131 .BR capset ()
 132 to modify the capabilities of a thread other than itself,
 133 but lacked sufficient privilege; the
 134 .B CAP_SETPCAP
 135 capability is required.
 136 (A bug in kernels before 2.6.11 meant that this error could also
 137 occur if a thread without this capability tried to change its
 138 own capabilities by specifying the
 139 .I pid
 140 field as a non-zero value (i.e., the value returned by
 141 .BR getpid (2))
 142 instead of 0.)
 143 .TP
 144 .B ESRCH
 145 No such thread.
 146 .SH "CONFORMING TO"
 147 These system calls are Linux specific.
 148 .SH NOTES
 149 The portable interface to the capability querying and setting
 150 functions is provided by the
 151 .I libcap
 152 library and is available from here:
 153 .br
 154 .I ftp://ftp.kernel.org/pub/linux/libs/security/linux-privs
 155 .SH "SEE ALSO"
 156 .BR clone (2),
 157 .BR gettid (2),
 158 .BR capabilities (7)