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 2021-03-22 "Linux" "Linux Programmer's Manual"
18 capget, capset \- set/get capabilities of thread(s)
21 .BR "#include <linux/capability.h>" " /* Definition of " CAP_* " and"
22 .BR " _LINUX_CAPABILITY_*" " constants */"
23 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
24 .B #include <unistd.h>
26 .BI "int syscall(SYS_capget, cap_user_header_t " hdrp ,
27 .BI " cap_user_data_t " datap );
28 .BI "int syscall(SYS_capset, cap_user_header_t " hdrp ,
29 .BI " const cap_user_data_t " datap );
33 glibc provides no wrappers for these system calls,
34 necessitating the use of
37 These two system calls are the raw kernel interface for getting and
38 setting thread capabilities.
39 Not only are these system calls specific to Linux,
40 but the kernel API is likely to change and use of
41 these system calls (in particular the format of the
43 types) is subject to extension with each kernel revision,
44 but old programs will keep working.
46 The portable interfaces are
50 if possible, you should use those interfaces in applications; see NOTES.
53 Now that you have been warned, some current kernel details.
54 The structures are defined as follows.
58 #define _LINUX_CAPABILITY_VERSION_1 0x19980330
59 #define _LINUX_CAPABILITY_U32S_1 1
61 /* V2 added in Linux 2.6.25; deprecated */
62 #define _LINUX_CAPABILITY_VERSION_2 0x20071026
63 .\" commit e338d263a76af78fe8f38a72131188b58fceb591
64 .\" Added 64 bit capability support
65 #define _LINUX_CAPABILITY_U32S_2 2
67 /* V3 added in Linux 2.6.26 */
68 #define _LINUX_CAPABILITY_VERSION_3 0x20080522
69 .\" commit ca05a99a54db1db5bca72eccb5866d2a86f8517f
70 #define _LINUX_CAPABILITY_U32S_3 2
72 typedef struct __user_cap_header_struct {
77 typedef struct __user_cap_data_struct {
90 fields are bit masks of the capabilities defined in
94 values are bit indexes and need to be bit-shifted before ORing into
96 To define the structures for passing to the system call, you have to use the
97 .I struct __user_cap_header_struct
99 .I struct __user_cap_data_struct
100 names because the typedefs are only pointers.
102 Kernels prior to 2.6.25 prefer
103 32-bit capabilities with version
104 .BR _LINUX_CAPABILITY_VERSION_1 .
105 Linux 2.6.25 added 64-bit capability sets, with version
106 .BR _LINUX_CAPABILITY_VERSION_2 .
107 There was, however, an API glitch, and Linux 2.6.26 added
108 .BR _LINUX_CAPABILITY_VERSION_3
111 Note that 64-bit capabilities use
115 whereas 32-bit capabilities use only
118 On kernels that support file capabilities (VFS capabilities support),
119 these system calls behave slightly differently.
120 This support was added as an option in Linux 2.6.24,
121 and became fixed (nonoptional) in Linux 2.6.33.
125 calls, one can probe the capabilities of any process by specifying its
130 For details on the data, see
131 .BR capabilities (7).
133 .SS With VFS capabilities support
134 VFS capabilities employ a file extended attribute (see
136 to allow capabilities to be attached to executables.
137 This privilege model obsoletes kernel support for one process
138 asynchronously setting the capabilities of another.
139 That is, on kernels that have VFS capabilities support, when calling
141 the only permitted values for
143 are 0 or, equivalently, the value returned by
146 .SS Without VFS capabilities support
147 On older kernels that do not provide VFS capabilities support
149 can, if the caller has the
151 capability, be used to change not only the caller's own capabilities,
152 but also the capabilities of other threads.
153 The call operates on the capabilities of the thread specified by the
157 when that is nonzero, or on the capabilities of the calling thread if
162 refers to a single-threaded process, then
164 can be specified as a traditional process ID;
165 operating on a thread of a multithreaded process requires a thread ID
166 of the type returned by
171 can also be: \-1, meaning perform the change on all threads except the
174 or a value less than \-1, in which case the change is applied
175 to all members of the process group whose ID is \-\fIpid\fP.
177 On success, zero is returned.
178 On error, \-1 is returned, and
180 is set to indicate the error.
182 The calls fail with the error
188 to the kernel preferred value of
189 .B _LINUX_CAPABILITY_VERSION_?
193 In this way, one can probe what the current
194 preferred capability revision is.
202 may be NULL only when the user is trying to determine the preferred
203 capability version format supported by the kernel.
206 One of the arguments was invalid.
209 An attempt was made to add a capability to the permitted set, or to set
210 a capability in the effective set that is not in the
214 An attempt was made to add a capability to the inheritable set, and either:
217 that capability was not in the caller's bounding set; or
219 the capability was not in the caller's permitted set
220 and the caller lacked the
222 capability in its effective set.
226 The caller attempted to use
228 to modify the capabilities of a thread other than itself,
229 but lacked sufficient privilege.
230 For kernels supporting VFS
231 capabilities, this is never permitted.
232 For kernels lacking VFS
235 capability is required.
236 (A bug in kernels before 2.6.11 meant that this error could also
237 occur if a thread without this capability tried to change its
238 own capabilities by specifying the
240 field as a nonzero value (i.e., the value returned by
247 These system calls are Linux-specific.
249 The portable interface to the capability querying and setting
250 functions is provided by the
252 library and is available here:
254 .UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git