man2/capget.2

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