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