| blob | 3ac05106f3c1b8663c058ce0bb958a735b1cb3e0 |
1 .\" Copyright: written by Andrew Morgan <morgan@kernel.org>
2 .\" and Copyright 2006, 2008, Michael Kerrisk <tmk.manpages@gmail.com>
3 .\"
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" may be distributed as per GPL
6 .\" %%%LICENSE_END
7 .\"
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
15 .\"
16 .TH CAPGET 2 2021-03-22 "Linux" "Linux Programmer's Manual"
17 .SH NAME
18 capget, capset \- set/get capabilities of thread(s)
19 .SH SYNOPSIS
20 .nf
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>
25 .PP
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 );
30 .fi
31 .PP
32 .IR Note :
33 glibc provides no wrappers for these system calls,
34 necessitating the use of
35 .BR syscall (2).
36 .SH DESCRIPTION
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
42 .I cap_user_*_t
43 types) is subject to extension with each kernel revision,
44 but old programs will keep working.
45 .PP
46 The portable interfaces are
47 .BR cap_set_proc (3)
48 and
49 .BR cap_get_proc (3);
50 if possible, you should use those interfaces in applications; see NOTES.
51 .\"
52 .SS Current details
53 Now that you have been warned, some current kernel details.
54 The structures are defined as follows.
55 .PP
56 .in +4n
57 .EX
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 {
73 __u32 version;
74 int pid;
75 } *cap_user_header_t;
77 typedef struct __user_cap_data_struct {
78 __u32 effective;
79 __u32 permitted;
80 __u32 inheritable;
81 } *cap_user_data_t;
82 .EE
83 .in
84 .PP
85 The
86 .IR effective ,
87 .IR permitted ,
88 and
89 .I inheritable
90 fields are bit masks of the capabilities defined in
91 .BR capabilities (7).
92 Note that the
93 .B CAP_*
94 values are bit indexes and need to be bit-shifted before ORing into
95 the bit fields.
96 To define the structures for passing to the system call, you have to use the
97 .I struct __user_cap_header_struct
98 and
99 .I struct __user_cap_data_struct
100 names because the typedefs are only pointers.
101 .PP
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
109 to fix the problem.
110 .PP
111 Note that 64-bit capabilities use
112 .I datap[0]
113 and
114 .IR datap[1] ,
115 whereas 32-bit capabilities use only
116 .IR datap[0] .
117 .PP
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.
122 .PP
123 For
124 .BR capget ()
125 calls, one can probe the capabilities of any process by specifying its
126 process ID with the
127 .I hdrp\->pid
128 field value.
129 .PP
130 For details on the data, see
131 .BR capabilities (7).
132 .\"
133 .SS With VFS capabilities support
134 VFS capabilities employ a file extended attribute (see
135 .BR xattr (7))
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
140 .BR capset (),
141 the only permitted values for
142 .I hdrp\->pid
143 are 0 or, equivalently, the value returned by
144 .BR gettid (2).
145 .\"
146 .SS Without VFS capabilities support
147 On older kernels that do not provide VFS capabilities support
148 .BR capset ()
149 can, if the caller has the
150 .BR CAP_SETPCAP
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
154 .I pid
155 field of
156 .I hdrp
157 when that is nonzero, or on the capabilities of the calling thread if
158 .I pid
159 is 0.
160 If
161 .I pid
162 refers to a single-threaded process, then
163 .I pid
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
167 .BR gettid (2).
168 For
169 .BR capset (),
170 .I pid
171 can also be: \-1, meaning perform the change on all threads except the
172 caller and
173 .BR init (1);
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.
176 .SH RETURN VALUE
177 On success, zero is returned.
178 On error, \-1 is returned, and
179 .I errno
180 is set to indicate the error.
181 .PP
182 The calls fail with the error
183 .BR EINVAL ,
184 and set the
185 .I version
186 field of
187 .I hdrp
188 to the kernel preferred value of
189 .B _LINUX_CAPABILITY_VERSION_?
190 when an unsupported
191 .I version
192 value is specified.
193 In this way, one can probe what the current
194 preferred capability revision is.
195 .SH ERRORS
196 .TP
197 .B EFAULT
198 Bad memory address.
199 .I hdrp
200 must not be NULL.
201 .I datap
202 may be NULL only when the user is trying to determine the preferred
203 capability version format supported by the kernel.
204 .TP
205 .B EINVAL
206 One of the arguments was invalid.
207 .TP
208 .B EPERM
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
211 permitted set.
212 .TP
213 .B EPERM
214 An attempt was made to add a capability to the inheritable set, and either:
215 .RS
216 .IP * 3
217 that capability was not in the caller's bounding set; or
218 .IP *
219 the capability was not in the caller's permitted set
220 and the caller lacked the
221 .B CAP_SETPCAP
222 capability in its effective set.
223 .RE
224 .TP
225 .B EPERM
226 The caller attempted to use
227 .BR capset ()
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
233 support, the
234 .B CAP_SETPCAP
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
239 .I pid
240 field as a nonzero value (i.e., the value returned by
241 .BR getpid (2))
242 instead of 0.)
243 .TP
244 .B ESRCH
245 No such thread.
246 .SH CONFORMING TO
247 These system calls are Linux-specific.
248 .SH NOTES
249 The portable interface to the capability querying and setting
250 functions is provided by the
251 .I libcap
252 library and is available here:
253 .br
254 .UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git
255 .UE
256 .SH SEE ALSO
257 .BR clone (2),
258 .BR gettid (2),
259 .BR capabilities (7)