+.\" written by Andrew Morgan <morgan@kernel.org>
.\"
-.\" $Id: capget.2,v 1.4 1999/09/09 16:43:26 morgan Exp $
-.\" written by Andrew Morgan <morgan@linux.kernel.org>
+.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
.\" may be distributed as per GPL
+.\" %%%LICENSE_END
+.\"
.\" Modified by David A. Wheeler <dwheeler@ida.org>
.\" Modified 2004-05-27, mtk
.\" Modified 2004-06-21, aeb
+.\" Modified 2008-04-28, morgan of kernel.org
+.\" Update in line with addition of file capabilities and
+.\" 64-bit capability sets in kernel 2.6.2[45].
+.\" Modified 2009-01-26, andi kleen
.\"
-.TH CAPGET 2 2004-06-21 "Linux 2.6.6" "Linux Programmer's Manual"
+.TH CAPGET 2 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
-capget, capset \- set/get capabilities
+capget, capset \- set/get capabilities of thread(s)
.SH SYNOPSIS
-.B #undef _POSIX_SOURCE
-.br
.B #include <sys/capability.h>
-.sp
+.PP
.BI "int capget(cap_user_header_t " hdrp ", cap_user_data_t " datap );
-.sp
+.PP
.BI "int capset(cap_user_header_t " hdrp ", const cap_user_data_t " datap );
.SH DESCRIPTION
-As of Linux 2.2, the power of the superuser (root) has been partitioned into
-a set of discrete capabilities.
-Every thread has a set of effective capabilities identifying
-which capabilities (if any) it may currently exercise.
-Every thread also has a set of inheritable capabilities that may be
-passed through an
-.BR execve (2)
-call, and a set of permitted capabilities
-that it can make effective or inheritable.
-.PP
-These two functions are the raw kernel interface for getting and
-setting capabilities.
+These two system calls are the raw kernel interface for getting and
+setting thread capabilities.
Not only are these system calls specific to Linux,
but the kernel API is likely to change and use of
-these functions (in particular the format of the
-.B cap_user_*_t
-types) is subject to change with each kernel revision.
-.sp
+these system calls (in particular the format of the
+.I cap_user_*_t
+types) is subject to extension with each kernel revision,
+but old programs will keep working.
+.PP
The portable interfaces are
.BR cap_set_proc (3)
and
.BR cap_get_proc (3);
-if possible you should use those interfaces in applications.
-If you wish to use the Linux extensions in applications, you should
-use the easier-to-use interfaces
-.BR capsetp (3)
-and
-.BR capgetp (3).
-.SS "Current details"
+if possible, you should use those interfaces in applications.
+.\"
+.SS Current details
Now that you have been warned, some current kernel details.
-The structs are defined as follows.
-.sp
-.nf
+The structures are defined as follows.
+.PP
.in +4n
-#define _LINUX_CAPABILITY_VERSION 0x19980330
+.EX
+#define _LINUX_CAPABILITY_VERSION_1 0x19980330
+#define _LINUX_CAPABILITY_U32S_1 1
+
+ /* V2 added in Linux 2.6.25; deprecated */
+#define _LINUX_CAPABILITY_VERSION_2 0x20071026
+.\" commit e338d263a76af78fe8f38a72131188b58fceb591
+.\" Added 64 bit capability support
+#define _LINUX_CAPABILITY_U32S_2 2
+
+ /* V3 added in Linux 2.6.26 */
+#define _LINUX_CAPABILITY_VERSION_3 0x20080522
+.\" commit ca05a99a54db1db5bca72eccb5866d2a86f8517f
+#define _LINUX_CAPABILITY_U32S_3 2
typedef struct __user_cap_header_struct {
- int version;
- int pid;
+ __u32 version;
+ int pid;
} *cap_user_header_t;
typedef struct __user_cap_data_struct {
- int effective;
- int permitted;
- int inheritable;
+ __u32 effective;
+ __u32 permitted;
+ __u32 inheritable;
} *cap_user_data_t;
-.fi
-.in -4n
-.sp
-The calls will return EINVAL, and set the
-.I version
-field of
-.I hdr
-to _LINUX_CAPABILITY_VERSION when another version was specified.
-
-The calls operate on the capabilities of the thread specified by the
+.EE
+.in
+.PP
+The
+.IR effective ,
+.IR permitted ,
+and
+.I inheritable
+fields are bit masks of the capabilities defined in
+.BR capabilities (7).
+Note that the
+.B CAP_*
+values are bit indexes and need to be bit-shifted before ORing into
+the bit fields.
+To define the structures for passing to the system call, you have to use the
+.I struct __user_cap_header_struct
+and
+.I struct __user_cap_data_struct
+names because the typedefs are only pointers.
+.PP
+Kernels prior to 2.6.25 prefer
+32-bit capabilities with version
+.BR _LINUX_CAPABILITY_VERSION_1 .
+Linux 2.6.25 added 64-bit capability sets, with version
+.BR _LINUX_CAPABILITY_VERSION_2 .
+There was, however, an API glitch, and Linux 2.6.26 added
+.BR _LINUX_CAPABILITY_VERSION_3
+to fix the problem.
+.PP
+Note that 64-bit capabilities use
+.IR datap [0]
+and
+.IR datap [1],
+whereas 32-bit capabilities use only
+.IR datap [0].
+.PP
+On kernels that support file capabilities (VFS capabilities support),
+these system calls behave slightly differently.
+This support was added as an option in Linux 2.6.24,
+and became fixed (nonoptional) in Linux 2.6.33.
+.PP
+For
+.BR capget ()
+calls, one can probe the capabilities of any process by specifying its
+process ID with the
+.I hdrp->pid
+field value.
+.PP
+For details on the data, see
+.BR capabilities (7).
+.\"
+.SS With VFS capabilities support
+VFS capabilities employ a file extended attribute (see
+.BR xattr (7))
+to allow capabilities to be attached to executables.
+This privilege model obsoletes kernel support for one process
+asynchronously setting the capabilities of another.
+That is, on kernels that have VFS capabilities support, when calling
+.BR capset (),
+the only permitted values for
+.I hdrp->pid
+are 0 or, equivalently, the value returned by
+.BR gettid (2).
+.\"
+.SS Without VFS capabilities support
+On older kernels that do not provide VFS capabilities support
+.BR capset ()
+can, if the caller has the
+.BR CAP_SETPCAP
+capability, be used to change not only the caller's own capabilities,
+but also the capabilities of other threads.
+The call operates on the capabilities of the thread specified by the
.I pid
field of
-.I hdr
-when that is non-zero, or on the capabilities of the calling thread if
+.I hdrp
+when that is nonzero, or on the capabilities of the calling thread if
.I pid
is 0.
If
.I pid
can also be: \-1, meaning perform the change on all threads except the
caller and
-.BR init (8);
+.BR init (1);
or a value less than \-1, in which case the change is applied
to all members of the process group whose ID is \-\fIpid\fP.
-
-For details on the data, see
-.BR capabilities (7).
-.SH "RETURN VALUE"
+.SH RETURN VALUE
On success, zero is returned.
On error, \-1 is returned, and
.I errno
is set appropriately.
+.PP
+The calls fail with the error
+.BR EINVAL ,
+and set the
+.I version
+field of
+.I hdrp
+to the kernel preferred value of
+.B _LINUX_CAPABILITY_VERSION_?
+when an unsupported
+.I version
+value is specified.
+In this way, one can probe what the current
+preferred capability revision is.
.SH ERRORS
.TP
.B EFAULT
Bad memory address.
-Neither of
.I hdrp
-and
+must not be NULL.
.I datap
-may be NULL.
+may be NULL only when the user is trying to determine the preferred
+capability version format supported by the kernel.
.TP
.B EINVAL
One of the arguments was invalid.
The caller attempted to use
.BR capset ()
to modify the capabilities of a thread other than itself,
-but lacked sufficient privilege; the
+but lacked sufficient privilege.
+For kernels supporting VFS
+capabilities, this is never permitted.
+For kernels lacking VFS
+support, the
.B CAP_SETPCAP
capability is required.
(A bug in kernels before 2.6.11 meant that this error could also
occur if a thread without this capability tried to change its
own capabilities by specifying the
.I pid
-field as a non-zero value (i.e., the value returned by
+field as a nonzero value (i.e., the value returned by
.BR getpid (2))
instead of 0.)
.TP
.B ESRCH
No such thread.
-.SH "CONFORMING TO"
-These system calls are Linux specific.
+.SH CONFORMING TO
+These system calls are Linux-specific.
.SH NOTES
The portable interface to the capability querying and setting
functions is provided by the
-.B libcap
-library and is available from here:
+.I libcap
+library and is available here:
.br
-.B ftp://ftp.kernel.org/pub/linux/libs/security/linux-privs
-.SH "SEE ALSO"
+.UR http://git.kernel.org/cgit\:/linux\:/kernel\:/git\:/morgan\:\:/libcap.git
+.UE
+.SH SEE ALSO
.BR clone (2),
.BR gettid (2),
.BR capabilities (7)
projects / thirdparty / man-pages.git / blobdiff