1 .\" written by Andrew Morgan <morgan@kernel.org>
3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
4 .\" may be distributed as per GPL
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
15 .TH CAPGET 2 2013-03-11 "Linux" "Linux Programmer's Manual"
17 capget, capset \- set/get capabilities of thread(s)
19 .B #include <sys/capability.h>
21 .BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
23 .BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
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
33 call, and a set of permitted capabilities
34 that it can make effective or inheritable.
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
42 types) is subject to extension with each kernel revision,
43 but old programs will keep working.
45 The portable interfaces are
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
56 Now that you have been warned, some current kernel details.
57 The structures are defined as follows.
61 #define _LINUX_CAPABILITY_VERSION_1 0x19980330
62 #define _LINUX_CAPABILITY_U32S_1 1
64 #define _LINUX_CAPABILITY_VERSION_2 0x20071026
65 #define _LINUX_CAPABILITY_U32S_2 2
67 typedef struct __user_cap_header_struct {
72 typedef struct __user_cap_data_struct {
85 fields are bit masks of the capabilities defined in
89 values are bit indexes and need to be bit-shifted before ORing into
91 To define the structures for passing to the system call you have to use the
92 .I struct __user_cap_header_struct
94 .I struct __user_cap_data_struct
95 names because the typedefs are only pointers.
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
106 whereas 32-bit capabilities use only
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).
115 calls, one can probe the capabilities of any process by specifying its
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
126 calls the only permitted values for
130 which are equivalent.
131 .SS Without VFS capability support
132 When the kernel does not support VFS capabilities,
134 calls can operate on the capabilities of the thread specified by the
138 when that is nonzero, or on the capabilities of the calling thread if
143 refers to a single-threaded process, then
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
152 can also be: \-1, meaning perform the change on all threads except the
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.
158 For details on the data, see
159 .BR capabilities (7).
161 On success, zero is returned.
162 On error, \-1 is returned, and
164 is set appropriately.
166 The calls will fail with the error
172 to the kernel preferred value of
173 .B _LINUX_CAPABILITY_VERSION_?
177 In this way, one can probe what the current
178 preferred capability revision is.
186 may be NULL only when the user is trying to determine the preferred
187 capability version format supported by the kernel.
190 One of the arguments was invalid.
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
198 The caller attempted to use
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
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
212 field as a nonzero value (i.e., the value returned by
219 These system calls are Linux-specific.
221 The portable interface to the capability querying and setting
222 functions is provided by the
224 library and is available here:
226 .UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git
233 This page is part of release 3.78 of the Linux
236 A description of the project,
237 information about reporting bugs,
238 and the latest version of this page,
240 \%http://www.kernel.org/doc/man\-pages/.