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 2015-07-23 "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 .sp
  21 .BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
  22 .sp
  23 .BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
  24 .SH DESCRIPTION
  25 As of 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 .sp
  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 .sp
  59 .nf
  60 .in +4n
  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 .fi
  86 .in -4n
  87 .sp
  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
 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
 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
 121 On kernels that support file capabilities (VFS capability 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
 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 capability support
 133 VFS Capability support creates a file-attribute method for adding
 134 capabilities to privileged executables.
 135 This privilege model obsoletes kernel support for one process
 136 asynchronously setting the capabilities of another.
 137 That is, with VFS support, for
 138 .BR capset ()
 139 calls the only permitted values for
 140 .I hdrp->pid
 141 are 0 or
 142 .BR gettid (2),
 143 which are equivalent.
 144 .SS Without VFS capability support
 145 When the kernel does not support VFS capabilities,
 146 .BR capset ()
 147 calls can operate on the capabilities of the thread specified by the
 148 .I pid
 149 field of
 150 .I hdrp
 151 when that is nonzero, or on the capabilities of the calling thread if
 152 .I pid
 153 is 0.
 154 If
 155 .I pid
 156 refers to a single-threaded process, then
 157 .I pid
 158 can be specified as a traditional process ID;
 159 operating on a thread of a multithreaded process requires a thread ID
 160 of the type returned by
 161 .BR gettid (2).
 162 For
 163 .BR capset (),
 164 .I pid
 165 can also be: \-1, meaning perform the change on all threads except the
 166 caller and
 167 .BR init (1);
 168 or a value less than \-1, in which case the change is applied
 169 to all members of the process group whose ID is \-\fIpid\fP.
 170
 171 For details on the data, see
 172 .BR capabilities (7).
 173 .SH RETURN VALUE
 174 On success, zero is returned.
 175 On error, \-1 is returned, and
 176 .I errno
 177 is set appropriately.
 178
 179 The calls will fail with the error
 180 .BR EINVAL ,
 181 and set the
 182 .I version
 183 field of
 184 .I hdrp
 185 to the kernel preferred value of
 186 .B _LINUX_CAPABILITY_VERSION_?
 187 when an unsupported
 188 .I version
 189 value is specified.
 190 In this way, one can probe what the current
 191 preferred capability revision is.
 192 .SH ERRORS
 193 .TP
 194 .B EFAULT
 195 Bad memory address.
 196 .I hdrp
 197 must not be NULL.
 198 .I datap
 199 may be NULL only when the user is trying to determine the preferred
 200 capability version format supported by the kernel.
 201 .TP
 202 .B EINVAL
 203 One of the arguments was invalid.
 204 .TP
 205 .B EPERM
 206 An attempt was made to add a capability to the Permitted set, or to set
 207 a capability in the Effective or Inheritable sets that is not in the
 208 Permitted set.
 209 .TP
 210 .B EPERM
 211 The caller attempted to use
 212 .BR capset ()
 213 to modify the capabilities of a thread other than itself,
 214 but lacked sufficient privilege.
 215 For kernels supporting VFS
 216 capabilities, this is never permitted.
 217 For kernels lacking VFS
 218 support, the
 219 .B CAP_SETPCAP
 220 capability is required.
 221 (A bug in kernels before 2.6.11 meant that this error could also
 222 occur if a thread without this capability tried to change its
 223 own capabilities by specifying the
 224 .I pid
 225 field as a nonzero value (i.e., the value returned by
 226 .BR getpid (2))
 227 instead of 0.)
 228 .TP
 229 .B ESRCH
 230 No such thread.
 231 .SH CONFORMING TO
 232 These system calls are Linux-specific.
 233 .SH NOTES
 234 The portable interface to the capability querying and setting
 235 functions is provided by the
 236 .I libcap
 237 library and is available here:
 238 .br
 239 .UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git
 240 .UE
 241 .SH SEE ALSO
 242 .BR clone (2),
 243 .BR gettid (2),
 244 .BR capabilities (7)