Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 260 insertions, 0 deletions

diff --git a/man/man2/capget.2 b/man/man2/capget.2
new file mode 100644
index 0000000..8857fcb
--- /dev/null
+++ b/man/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 2024-05-02 "Linux man-pages (unreleased)"
+.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>
+.P
+.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
+.P
+.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.
+.P
+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.
+.P
+.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
+.P
+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.
+.P
+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.
+.P
+Note that 64-bit capabilities use
+.I datap[0]
+and
+.IR datap[1] ,
+whereas 32-bit capabilities use only
+.IR datap[0] .
+.P
+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.
+.P
+For
+.BR capget ()
+calls, one can probe the capabilities of any process by specifying its
+process ID with the
+.I hdrp\->pid
+field value.
+.P
+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.
+.P
+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
+Linux.
+.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)