man2/capget.2

   1 .\" written by Andrew Morgan <morgan@kernel.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   4 .\" may be distributed as per GPL
   5 .\" %%%LICENSE_END
   6 .\"
   7 .\" Modified by David A. Wheeler <dwheeler@ida.org>
   8 .\" Modified 2004-05-27, mtk
   9 .\" Modified 2004-06-21, aeb
  10 .\" Modified 2008-04-28, morgan of kernel.org
  11 .\"     Update in line with addition of file capabilities and
  12 .\"     64-bit capability sets in kernel 2.6.2[45].
  13 .\" Modified 2009-01-26, andi kleen
  14 .\"
  15 .TH CAPGET 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  16 .SH NAME
  17 capget, capset \- set/get capabilities of thread(s)
  18 .SH SYNOPSIS
  19 .B #include <sys/capability.h>
  20 .PP
  21 .BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
  22 .PP
  23 .BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
  24 .SH DESCRIPTION
  25 Since Linux 2.2,
  26 the power of the superuser (root) has been partitioned into
  27 a set of discrete capabilities.
  28 Each thread has a set of effective capabilities identifying
  29 which capabilities (if any) it may currently exercise.
  30 Each thread also has a set of inheritable capabilities that may be
  31 passed through an
  32 .BR execve (2)
  33 call, and a set of permitted capabilities
  34 that it can make effective or inheritable.
  35 .PP
  36 These two system calls are the raw kernel interface for getting and
  37 setting thread capabilities.
  38 Not only are these system calls specific to Linux,
  39 but the kernel API is likely to change and use of
  40 these system calls (in particular the format of the
  41 .I cap_user_*_t
  42 types) is subject to extension with each kernel revision,
  43 but old programs will keep working.
  44 .PP
  45 The portable interfaces are
  46 .BR cap_set_proc (3)
  47 and
  48 .BR cap_get_proc (3);
  49 if possible, you should use those interfaces in applications.
  50 If you wish to use the Linux extensions in applications, you should
  51 use the easier-to-use interfaces
  52 .BR capsetp (3)
  53 and
  54 .BR capgetp (3).
  55 .SS Current details
  56 Now that you have been warned, some current kernel details.
  57 The structures are defined as follows.
  58 .PP
  59 .in +4n
  60 .EX
  61 #define _LINUX_CAPABILITY_VERSION_1  0x19980330
  62 #define _LINUX_CAPABILITY_U32S_1     1
  63
  64         /* V2 added in Linux 2.6.25; deprecated */
  65 #define _LINUX_CAPABILITY_VERSION_2  0x20071026
  66 .\" commit e338d263a76af78fe8f38a72131188b58fceb591
  67 .\" Added 64 bit capability support
  68 #define _LINUX_CAPABILITY_U32S_2     2
  69
  70         /* V3 added in Linux 2.6.26 */
  71 #define _LINUX_CAPABILITY_VERSION_3  0x20080522
  72 .\" commit ca05a99a54db1db5bca72eccb5866d2a86f8517f
  73 #define _LINUX_CAPABILITY_U32S_3     2
  74
  75 typedef struct __user_cap_header_struct {
  76    __u32 version;
  77    int pid;
  78 } *cap_user_header_t;
  79
  80 typedef struct __user_cap_data_struct {
  81    __u32 effective;
  82    __u32 permitted;
  83    __u32 inheritable;
  84 } *cap_user_data_t;
  85 .EE
  86 .in
  87 .PP
  88 The
  89 .IR effective ,
  90 .IR permitted ,
  91 and
  92 .I inheritable
  93 fields are bit masks of the capabilities defined in
  94 .BR capabilities (7).
  95 Note that the
  96 .B CAP_*
  97 values are bit indexes and need to be bit-shifted before ORing into
  98 the bit fields.
  99 To define the structures for passing to the system call, you have to use the
 100 .I struct __user_cap_header_struct
 101 and
 102 .I struct __user_cap_data_struct
 103 names because the typedefs are only pointers.
 104 .PP
 105 Kernels prior to 2.6.25 prefer
 106 32-bit capabilities with version
 107 .BR _LINUX_CAPABILITY_VERSION_1 .
 108 Linux 2.6.25 added 64-bit capability sets, with version
 109 .BR _LINUX_CAPABILITY_VERSION_2 .
 110 There was, however, an API glitch, and Linux 2.6.26 added
 111 .BR _LINUX_CAPABILITY_VERSION_3
 112 to fix the problem.
 113 .PP
 114 Note that 64-bit capabilities use
 115 .IR datap [0]
 116 and
 117 .IR datap [1],
 118 whereas 32-bit capabilities use only
 119 .IR datap [0].
 120 .PP
 121 On kernels that support file capabilities (VFS capabilities support),
 122 these system calls behave slightly differently.
 123 This support was added as an option in Linux 2.6.24,
 124 and became fixed (nonoptional) in Linux 2.6.33.
 125 .PP
 126 For
 127 .BR capget ()
 128 calls, one can probe the capabilities of any process by specifying its
 129 process ID with the
 130 .I hdrp->pid
 131 field value.
 132 .SS With VFS capabilities support
 133 VFS capabilities support creates a file-attribute method for attaching
 134 capabilities to executables.
 135 This privilege model obsoletes kernel support for one process
 136 asynchronously setting the capabilities of another.
 137 That is, on kernels that have VFS capabilities support, when calling
 138 .BR capset (),
 139 the only permitted values for
 140 .I hdrp->pid
 141 are 0 or, equivalently, the value returned by
 142 .BR gettid (2).
 143 .\"
 144 .SS Without VFS capabilities support
 145 On older kernels that do not provide VFS capabilities support
 146 .BR capset ()
 147 can, if the caller has the
 148 .BR CAP_SETPCAP
 149 capability, be used to change not only the caller's own capabilities,
 150 but also the capabilities of other threads.
 151 The call operates on the capabilities of the thread specified by the
 152 .I pid
 153 field of
 154 .I hdrp
 155 when that is nonzero, or on the capabilities of the calling thread if
 156 .I pid
 157 is 0.
 158 If
 159 .I pid
 160 refers to a single-threaded process, then
 161 .I pid
 162 can be specified as a traditional process ID;
 163 operating on a thread of a multithreaded process requires a thread ID
 164 of the type returned by
 165 .BR gettid (2).
 166 For
 167 .BR capset (),
 168 .I pid
 169 can also be: \-1, meaning perform the change on all threads except the
 170 caller and
 171 .BR init (1);
 172 or a value less than \-1, in which case the change is applied
 173 to all members of the process group whose ID is \-\fIpid\fP.
 174 .PP
 175 For details on the data, see
 176 .BR capabilities (7).
 177 .SH RETURN VALUE
 178 On success, zero is returned.
 179 On error, \-1 is returned, and
 180 .I errno
 181 is set appropriately.
 182 .PP
 183 The calls fail with the error
 184 .BR EINVAL ,
 185 and set the
 186 .I version
 187 field of
 188 .I hdrp
 189 to the kernel preferred value of
 190 .B _LINUX_CAPABILITY_VERSION_?
 191 when an unsupported
 192 .I version
 193 value is specified.
 194 In this way, one can probe what the current
 195 preferred capability revision is.
 196 .SH ERRORS
 197 .TP
 198 .B EFAULT
 199 Bad memory address.
 200 .I hdrp
 201 must not be NULL.
 202 .I datap
 203 may be NULL only when the user is trying to determine the preferred
 204 capability version format supported by the kernel.
 205 .TP
 206 .B EINVAL
 207 One of the arguments was invalid.
 208 .TP
 209 .B EPERM
 210 An attempt was made to add a capability to the Permitted set, or to set
 211 a capability in the Effective or Inheritable sets that is not in the
 212 Permitted set.
 213 .TP
 214 .B EPERM
 215 The caller attempted to use
 216 .BR capset ()
 217 to modify the capabilities of a thread other than itself,
 218 but lacked sufficient privilege.
 219 For kernels supporting VFS
 220 capabilities, this is never permitted.
 221 For kernels lacking VFS
 222 support, the
 223 .B CAP_SETPCAP
 224 capability is required.
 225 (A bug in kernels before 2.6.11 meant that this error could also
 226 occur if a thread without this capability tried to change its
 227 own capabilities by specifying the
 228 .I pid
 229 field as a nonzero value (i.e., the value returned by
 230 .BR getpid (2))
 231 instead of 0.)
 232 .TP
 233 .B ESRCH
 234 No such thread.
 235 .SH CONFORMING TO
 236 These system calls are Linux-specific.
 237 .SH NOTES
 238 The portable interface to the capability querying and setting
 239 functions is provided by the
 240 .I libcap
 241 library and is available here:
 242 .br
 243 .UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git
 244 .UE
 245 .SH SEE ALSO
 246 .BR clone (2),
 247 .BR gettid (2),
 248 .BR capabilities (7)