diff options
Diffstat (limited to 'upstream/debian-bookworm/man2/capget.2')
| -rw-r--r-- | upstream/debian-bookworm/man2/capget.2 | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/capget.2 b/upstream/debian-bookworm/man2/capget.2 new file mode 100644 index 00000000..da1d5414 --- /dev/null +++ b/upstream/debian-bookworm/man2/capget.2 @@ -0,0 +1,260 @@ +.\" Copyright: written by Andrew Morgan <morgan@kernel.org> +.\" and Copyright 2006, 2008, Michael Kerrisk <tmk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-1.0-or-later +.\" +.\" 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 Linux 2.6.2[45]. +.\" Modified 2009-01-26, andi kleen +.\" +.TH capget 2 2023-02-05 "Linux man-pages 6.03" +.SH NAME +capget, capset \- set/get capabilities of thread(s) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#include <linux/capability.h>" " /* Definition of " CAP_* " and" +.BR " _LINUX_CAPABILITY_*" " constants */" +.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" +.B #include <unistd.h> +.PP +.BI "int syscall(SYS_capget, cap_user_header_t " hdrp , +.BI " cap_user_data_t " datap ); +.BI "int syscall(SYS_capset, cap_user_header_t " hdrp , +.BI " const cap_user_data_t " datap ); +.fi +.PP +.IR Note : +glibc provides no wrappers for these system calls, +necessitating the use of +.BR syscall (2). +.SH DESCRIPTION +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 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; see NOTES. +.\" +.SS Current details +Now that you have been warned, some current kernel details. +The structures are defined as follows. +.PP +.in +4n +.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 { + __u32 version; + int pid; +} *cap_user_header_t; + +typedef struct __user_cap_data_struct { + __u32 effective; + __u32 permitted; + __u32 inheritable; +} *cap_user_data_t; +.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 Linux 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 +.B _LINUX_CAPABILITY_VERSION_3 +to fix the problem. +.PP +Note that 64-bit capabilities use +.I 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 +.B 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 hdrp +when that is nonzero, or on the capabilities of the calling thread if +.I pid +is 0. +If +.I pid +refers to a single-threaded process, then +.I pid +can be specified as a traditional process ID; +operating on a thread of a multithreaded process requires a thread ID +of the type returned by +.BR gettid (2). +For +.BR capset (), +.I pid +can also be: \-1, meaning perform the change on all threads except the +caller and +.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. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.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. +.I hdrp +must not be NULL. +.I datap +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. +.TP +.B EPERM +An attempt was made to add a capability to the permitted set, or to set +a capability in the effective set that is not in the +permitted set. +.TP +.B EPERM +An attempt was made to add a capability to the inheritable set, and either: +.RS +.IP \[bu] 3 +that capability was not in the caller's bounding set; or +.IP \[bu] +the capability was not in the caller's permitted set +and the caller lacked the +.B CAP_SETPCAP +capability in its effective set. +.RE +.TP +.B EPERM +The caller attempted to use +.BR capset () +to modify the capabilities of a thread other than itself, +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 Linux 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 nonzero value (i.e., the value returned by +.BR getpid (2)) +instead of 0.) +.TP +.B ESRCH +No such thread. +.SH STANDARDS +These system calls are Linux-specific. +.SH NOTES +The portable interface to the capability querying and setting +functions is provided by the +.I libcap +library and is available here: +.br +.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) |