Debian Codegraph @

upstream/debian-unstable/man2/capget.2

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