original/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 2013-03-11 "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 #define _LINUX_CAPABILITY_VERSION_2  0x20071026
  65 #define _LINUX_CAPABILITY_U32S_2     2
  66
  67 typedef struct __user_cap_header_struct {
  68    __u32 version;
  69    int pid;
  70 } *cap_user_header_t;
  71
  72 typedef struct __user_cap_data_struct {
  73    __u32 effective;
  74    __u32 permitted;
  75    __u32 inheritable;
  76 } *cap_user_data_t;
  77 .fi
  78 .in -4n
  79 .sp
  80 The
  81 .IR effective ,
  82 .IR permitted ,
  83 and
  84 .I inheritable
  85 fields are bit masks of the capabilities defined in
  86 .BR capabilities (7).
  87 Note the
  88 .B CAP_*
  89 values are bit indexes and need to be bit-shifted before ORing into
  90 the bit fields.
  91 To define the structures for passing to the system call you have to use the
  92 .I struct __user_cap_header_struct
  93 and
  94 .I struct __user_cap_data_struct
  95 names because the typedefs are only pointers.
  96
  97 Kernels prior to 2.6.25 prefer
  98 32-bit capabilities with version
  99 .BR _LINUX_CAPABILITY_VERSION_1 ,
 100 and kernels 2.6.25+ prefer 64-bit capabilities with version
 101 .BR _LINUX_CAPABILITY_VERSION_2 .
 102 Note, 64-bit capabilities use
 103 .IR datap [0]
 104 and
 105 .IR datap [1],
 106 whereas 32-bit capabilities use only
 107 .IR datap [0].
 108 .sp
 109 Another change affecting the behavior of these system calls is kernel
 110 support for file capabilities (VFS capability support).
 111 This support is currently a compile time option (added in kernel 2.6.24).
 112 .sp
 113 For
 114 .BR capget ()
 115 calls, one can probe the capabilities of any process by specifying its
 116 process ID with the
 117 .I hdrp->pid
 118 field value.
 119 .SS With VFS capability support
 120 VFS Capability support creates a file-attribute method for adding
 121 capabilities to privileged executables.
 122 This privilege model obsoletes kernel support for one process
 123 asynchronously setting the capabilities of another.
 124 That is, with VFS support, for
 125 .BR capset ()
 126 calls the only permitted values for
 127 .I hdrp->pid
 128 are 0 or
 129 .BR getpid (2),
 130 which are equivalent.
 131 .SS Without VFS capability support
 132 When the kernel does not support VFS capabilities,
 133 .BR capset ()
 134 calls can operate on the capabilities of the thread specified by the
 135 .I pid
 136 field of
 137 .I hdrp
 138 when that is nonzero, or on the capabilities of the calling thread if
 139 .I pid
 140 is 0.
 141 If
 142 .I pid
 143 refers to a single-threaded process, then
 144 .I pid
 145 can be specified as a traditional process ID;
 146 operating on a thread of a multithreaded process requires a thread ID
 147 of the type returned by
 148 .BR gettid (2).
 149 For
 150 .BR capset (),
 151 .I pid
 152 can also be: \-1, meaning perform the change on all threads except the
 153 caller and
 154 .BR init (8);
 155 or a value less than \-1, in which case the change is applied
 156 to all members of the process group whose ID is \-\fIpid\fP.
 157
 158 For details on the data, see
 159 .BR capabilities (7).
 160 .SH RETURN VALUE
 161 On success, zero is returned.
 162 On error, \-1 is returned, and
 163 .I errno
 164 is set appropriately.
 165
 166 The calls will fail with the error
 167 .BR EINVAL ,
 168 and set the
 169 .I version
 170 field of
 171 .I hdrp
 172 to the kernel preferred value of
 173 .B _LINUX_CAPABILITY_VERSION_?
 174 when an unsupported
 175 .I version
 176 value is specified.
 177 In this way, one can probe what the current
 178 preferred capability revision is.
 179 .SH ERRORS
 180 .TP
 181 .B EFAULT
 182 Bad memory address.
 183 .I hdrp
 184 must not be NULL.
 185 .I datap
 186 may be NULL only when the user is trying to determine the preferred
 187 capability version format supported by the kernel.
 188 .TP
 189 .B EINVAL
 190 One of the arguments was invalid.
 191 .TP
 192 .B EPERM
 193 An attempt was made to add a capability to the Permitted set, or to set
 194 a capability in the Effective or Inheritable sets that is not in the
 195 Permitted set.
 196 .TP
 197 .B EPERM
 198 The caller attempted to use
 199 .BR capset ()
 200 to modify the capabilities of a thread other than itself,
 201 but lacked sufficient privilege.
 202 For kernels supporting VFS
 203 capabilities, this is never permitted.
 204 For kernels lacking VFS
 205 support, the
 206 .B CAP_SETPCAP
 207 capability is required.
 208 (A bug in kernels before 2.6.11 meant that this error could also
 209 occur if a thread without this capability tried to change its
 210 own capabilities by specifying the
 211 .I pid
 212 field as a nonzero value (i.e., the value returned by
 213 .BR getpid (2))
 214 instead of 0.)
 215 .TP
 216 .B ESRCH
 217 No such thread.
 218 .SH CONFORMING TO
 219 These system calls are Linux-specific.
 220 .SH NOTES
 221 The portable interface to the capability querying and setting
 222 functions is provided by the
 223 .I libcap
 224 library and is available here:
 225 .br
 226 .UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git
 227 .UE
 228 .SH SEE ALSO
 229 .BR clone (2),
 230 .BR gettid (2),
 231 .BR capabilities (7)
 232 .SH COLOPHON
 233 This page is part of release 3.68 of the Linux
 234 .I man-pages
 235 project.
 236 A description of the project,
 237 information about reporting bugs,
 238 and the latest version of this page,
 239 can be found at
 240 \%http://www.kernel.org/doc/man\-pages/.