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