1 .\" Copyright: written by Andrew Morgan <morgan@kernel.org>
2 .\" and Copyright 2006, 2008, Michael Kerrisk <tmk.manpages@gmail.com>
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" may be distributed as per GPL
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
16 .TH CAPGET 2 2020-02-09 "Linux" "Linux Programmer's Manual"
18 capget, capset \- set/get capabilities of thread(s)
20 .B #include <sys/capability.h>
22 .BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
24 .BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
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
32 types) is subject to extension with each kernel revision,
33 but old programs will keep working.
35 The portable interfaces are
39 if possible, you should use those interfaces in applications.
42 Now that you have been warned, some current kernel details.
43 The structures are defined as follows.
47 #define _LINUX_CAPABILITY_VERSION_1 0x19980330
48 #define _LINUX_CAPABILITY_U32S_1 1
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
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
61 typedef struct __user_cap_header_struct {
66 typedef struct __user_cap_data_struct {
79 fields are bit masks of the capabilities defined in
83 values are bit indexes and need to be bit-shifted before ORing into
85 To define the structures for passing to the system call, you have to use the
86 .I struct __user_cap_header_struct
88 .I struct __user_cap_data_struct
89 names because the typedefs are only pointers.
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
100 Note that 64-bit capabilities use
104 whereas 32-bit capabilities use only
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.
114 calls, one can probe the capabilities of any process by specifying its
119 For details on the data, see
120 .BR capabilities (7).
122 .SS With VFS capabilities support
123 VFS capabilities employ a file extended attribute (see
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
130 the only permitted values for
132 are 0 or, equivalently, the value returned by
135 .SS Without VFS capabilities support
136 On older kernels that do not provide VFS capabilities support
138 can, if the caller has the
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
146 when that is nonzero, or on the capabilities of the calling thread if
151 refers to a single-threaded process, then
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
160 can also be: \-1, meaning perform the change on all threads except the
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.
166 On success, zero is returned.
167 On error, \-1 is returned, and
169 is set appropriately.
171 The calls fail with the error
177 to the kernel preferred value of
178 .B _LINUX_CAPABILITY_VERSION_?
182 In this way, one can probe what the current
183 preferred capability revision is.
191 may be NULL only when the user is trying to determine the preferred
192 capability version format supported by the kernel.
195 One of the arguments was invalid.
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
203 An attempt was made to add a capability to the inheritable set, and either:
206 that capability was not in the caller's bounding set; or
208 the capability was not in the caller's permitted set
209 and the caller lacked the
211 capability in its effective set.
215 The caller attempted to use
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
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
229 field as a nonzero value (i.e., the value returned by
236 These system calls are Linux-specific.
238 The portable interface to the capability querying and setting
239 functions is provided by the
241 library and is available here:
243 .UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git