| blob | 1e155075f731c995e5af153f041ab18763d6e6ef |
1 .\" Copyright: written by Andrew Morgan <morgan@kernel.org>
2 .\" and Copyright 2006, 2008, Michael Kerrisk <tmk.manpages@gmail.com>
3 .\"
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\"
6 .\" Modified by David A. Wheeler <dwheeler@ida.org>
7 .\" Modified 2004-05-27, mtk
8 .\" Modified 2004-06-21, aeb
9 .\" Modified 2008-04-28, morgan of kernel.org
10 .\" Update in line with addition of file capabilities and
11 .\" 64-bit capability sets in kernel 2.6.2[45].
12 .\" Modified 2009-01-26, andi kleen
13 .\"
14 .TH CAPGET 2 2021-03-22 "Linux man-pages (unreleased)"
15 .SH NAME
16 capget, capset \- set/get capabilities of thread(s)
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ", " \-lc )
20 .SH SYNOPSIS
21 .nf
22 .BR "#include <linux/capability.h>" " /* Definition of " CAP_* " and"
23 .BR " _LINUX_CAPABILITY_*" " constants */"
24 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
25 .B #include <unistd.h>
26 .PP
27 .BI "int syscall(SYS_capget, cap_user_header_t " hdrp ,
28 .BI " cap_user_data_t " datap );
29 .BI "int syscall(SYS_capset, cap_user_header_t " hdrp ,
30 .BI " const cap_user_data_t " datap );
31 .fi
32 .PP
33 .IR Note :
34 glibc provides no wrappers for these system calls,
35 necessitating the use of
36 .BR syscall (2).
37 .SH DESCRIPTION
38 These two system calls are the raw kernel interface for getting and
39 setting thread capabilities.
40 Not only are these system calls specific to Linux,
41 but the kernel API is likely to change and use of
42 these system calls (in particular the format of the
43 .I cap_user_*_t
44 types) is subject to extension with each kernel revision,
45 but old programs will keep working.
46 .PP
47 The portable interfaces are
48 .BR cap_set_proc (3)
49 and
50 .BR cap_get_proc (3);
51 if possible, you should use those interfaces in applications; see NOTES.
52 .\"
53 .SS Current details
54 Now that you have been warned, some current kernel details.
55 The structures are defined as follows.
56 .PP
57 .in +4n
58 .EX
59 #define _LINUX_CAPABILITY_VERSION_1 0x19980330
60 #define _LINUX_CAPABILITY_U32S_1 1
62 /* V2 added in Linux 2.6.25; deprecated */
63 #define _LINUX_CAPABILITY_VERSION_2 0x20071026
64 .\" commit e338d263a76af78fe8f38a72131188b58fceb591
65 .\" Added 64 bit capability support
66 #define _LINUX_CAPABILITY_U32S_2 2
68 /* V3 added in Linux 2.6.26 */
69 #define _LINUX_CAPABILITY_VERSION_3 0x20080522
70 .\" commit ca05a99a54db1db5bca72eccb5866d2a86f8517f
71 #define _LINUX_CAPABILITY_U32S_3 2
73 typedef struct __user_cap_header_struct {
74 uint32_t version;
75 int pid;
76 } *cap_user_header_t;
78 typedef struct __user_cap_data_struct {
79 uint32_t effective;
80 uint32_t permitted;
81 uint32_t inheritable;
82 } *cap_user_data_t;
83 .EE
84 .in
85 .PP
86 The
87 .IR effective ,
88 .IR permitted ,
89 and
90 .I inheritable
91 fields are bit masks of the capabilities defined in
92 .BR capabilities (7).
93 Note that the
94 .B CAP_*
95 values are bit indexes and need to be bit-shifted before ORing into
96 the bit fields.
97 To define the structures for passing to the system call, you have to use the
98 .I struct __user_cap_header_struct
99 and
100 .I struct __user_cap_data_struct
101 names because the typedefs are only pointers.
102 .PP
103 Kernels prior to 2.6.25 prefer
104 32-bit capabilities with version
105 .BR _LINUX_CAPABILITY_VERSION_1 .
106 Linux 2.6.25 added 64-bit capability sets, with version
107 .BR _LINUX_CAPABILITY_VERSION_2 .
108 There was, however, an API glitch, and Linux 2.6.26 added
109 .B _LINUX_CAPABILITY_VERSION_3
110 to fix the problem.
111 .PP
112 Note that 64-bit capabilities use
113 .I datap[0]
114 and
115 .IR datap[1] ,
116 whereas 32-bit capabilities use only
117 .IR datap[0] .
118 .PP
119 On kernels that support file capabilities (VFS capabilities support),
120 these system calls behave slightly differently.
121 This support was added as an option in Linux 2.6.24,
122 and became fixed (nonoptional) in Linux 2.6.33.
123 .PP
124 For
125 .BR capget ()
126 calls, one can probe the capabilities of any process by specifying its
127 process ID with the
128 .I hdrp\->pid
129 field value.
130 .PP
131 For details on the data, see
132 .BR capabilities (7).
133 .\"
134 .SS With VFS capabilities support
135 VFS capabilities employ a file extended attribute (see
136 .BR xattr (7))
137 to allow capabilities to be attached to executables.
138 This privilege model obsoletes kernel support for one process
139 asynchronously setting the capabilities of another.
140 That is, on kernels that have VFS capabilities support, when calling
141 .BR capset (),
142 the only permitted values for
143 .I hdrp\->pid
144 are 0 or, equivalently, the value returned by
145 .BR gettid (2).
146 .\"
147 .SS Without VFS capabilities support
148 On older kernels that do not provide VFS capabilities support
149 .BR capset ()
150 can, if the caller has the
151 .B CAP_SETPCAP
152 capability, be used to change not only the caller's own capabilities,
153 but also the capabilities of other threads.
154 The call operates on the capabilities of the thread specified by the
155 .I pid
156 field of
157 .I hdrp
158 when that is nonzero, or on the capabilities of the calling thread if
159 .I pid
160 is 0.
161 If
162 .I pid
163 refers to a single-threaded process, then
164 .I pid
165 can be specified as a traditional process ID;
166 operating on a thread of a multithreaded process requires a thread ID
167 of the type returned by
168 .BR gettid (2).
169 For
170 .BR capset (),
171 .I pid
172 can also be: \-1, meaning perform the change on all threads except the
173 caller and
174 .BR init (1);
175 or a value less than \-1, in which case the change is applied
176 to all members of the process group whose ID is \-\fIpid\fP.
177 .SH RETURN VALUE
178 On success, zero is returned.
179 On error, \-1 is returned, and
180 .I errno
181 is set to indicate the error.
182 .PP
183 The calls fail with the error
184 .BR EINVAL ,
185 and set the
186 .I version
187 field of
188 .I hdrp
189 to the kernel preferred value of
190 .B _LINUX_CAPABILITY_VERSION_?
191 when an unsupported
192 .I version
193 value is specified.
194 In this way, one can probe what the current
195 preferred capability revision is.
196 .SH ERRORS
197 .TP
198 .B EFAULT
199 Bad memory address.
200 .I hdrp
201 must not be NULL.
202 .I datap
203 may be NULL only when the user is trying to determine the preferred
204 capability version format supported by the kernel.
205 .TP
206 .B EINVAL
207 One of the arguments was invalid.
208 .TP
209 .B EPERM
210 An attempt was made to add a capability to the permitted set, or to set
211 a capability in the effective set that is not in the
212 permitted set.
213 .TP
214 .B EPERM
215 An attempt was made to add a capability to the inheritable set, and either:
216 .RS
217 .IP * 3
218 that capability was not in the caller's bounding set; or
219 .IP *
220 the capability was not in the caller's permitted set
221 and the caller lacked the
222 .B CAP_SETPCAP
223 capability in its effective set.
224 .RE
225 .TP
226 .B EPERM
227 The caller attempted to use
228 .BR capset ()
229 to modify the capabilities of a thread other than itself,
230 but lacked sufficient privilege.
231 For kernels supporting VFS
232 capabilities, this is never permitted.
233 For kernels lacking VFS
234 support, the
235 .B CAP_SETPCAP
236 capability is required.
237 (A bug in kernels before 2.6.11 meant that this error could also
238 occur if a thread without this capability tried to change its
239 own capabilities by specifying the
240 .I pid
241 field as a nonzero value (i.e., the value returned by
242 .BR getpid (2))
243 instead of 0.)
244 .TP
245 .B ESRCH
246 No such thread.
247 .SH STANDARDS
248 These system calls are Linux-specific.
249 .SH NOTES
250 The portable interface to the capability querying and setting
251 functions is provided by the
252 .I libcap
253 library and is available here:
254 .br
255 .UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git
256 .UE
257 .SH SEE ALSO
258 .BR clone (2),
259 .BR gettid (2),
260 .BR capabilities (7)