Merging upstream version 6.8.

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

1 files changed, 147 insertions, 0 deletions

diff --git a/man/man2/setresuid.2 b/man/man2/setresuid.2
new file mode 100644
index 0000000..203b770
--- /dev/null
+++ b/man/man2/setresuid.2
@@ -0,0 +1,147 @@
+.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl)
+.\" and Copyright (C) 2005, 2010, 2014, 2015, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified, 2003-05-26, Michael Kerrisk, <mtk.manpages@gmail.com>
+.TH setresuid 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+setresuid, setresgid \- set real, effective, and saved user or group ID
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
+.B #include <unistd.h>
+.P
+.BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid );
+.BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid );
+.fi
+.SH DESCRIPTION
+.BR setresuid ()
+sets the real user ID, the effective user ID, and the
+saved set-user-ID of the calling process.
+.P
+An unprivileged process may change its real UID,
+effective UID, and saved set-user-ID, each to one of:
+the current real UID, the current effective UID, or the
+current saved set-user-ID.
+.P
+A privileged process (on Linux, one having the \fBCAP_SETUID\fP capability)
+may set its real UID, effective UID, and
+saved set-user-ID to arbitrary values.
+.P
+If one of the arguments equals \-1, the corresponding value is not changed.
+.P
+Regardless of what changes are made to the real UID, effective UID,
+and saved set-user-ID, the filesystem UID is always set to the same
+value as the (possibly new) effective UID.
+.P
+Completely analogously,
+.BR setresgid ()
+sets the real GID, effective GID, and saved set-group-ID
+of the calling process (and always modifies the filesystem GID
+to be the same as the effective GID),
+with the same restrictions for unprivileged processes.
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.P
+.IR Note :
+there are cases where
+.BR setresuid ()
+can fail even when the caller is UID 0;
+it is a grave security error to omit checking for a failure return from
+.BR setresuid ().
+.SH ERRORS
+.TP
+.B EAGAIN
+The call would change the caller's real UID (i.e.,
+.I ruid
+does not match the caller's real UID),
+but there was a temporary failure allocating the
+necessary kernel data structures.
+.TP
+.B EAGAIN
+.I ruid
+does not match the caller's real UID and this call would
+bring the number of processes belonging to the real user ID
+.I ruid
+over the caller's
+.B RLIMIT_NPROC
+resource limit.
+Since Linux 3.1, this error case no longer occurs
+(but robust applications should check for this error);
+see the description of
+.B EAGAIN
+in
+.BR execve (2).
+.TP
+.B EINVAL
+One or more of the target user or group IDs
+is not valid in this user namespace.
+.TP
+.B EPERM
+The calling process is not privileged (did not have the necessary
+capability in its user namespace)
+and tried to change the IDs to values that are not permitted.
+For
+.BR setresuid (),
+the necessary capability is
+.BR CAP_SETUID ;
+for
+.BR setresgid (),
+it is
+.BR CAP_SETGID .
+.SH VERSIONS
+.SS C library/kernel differences
+At the kernel level, user IDs and group IDs are a per-thread attribute.
+However, POSIX requires that all threads in a process
+share the same credentials.
+The NPTL threading implementation handles the POSIX requirements by
+providing wrapper functions for
+the various system calls that change process UIDs and GIDs.
+These wrapper functions (including those for
+.BR setresuid ()
+and
+.BR setresgid ())
+employ a signal-based technique to ensure
+that when one thread changes credentials,
+all of the other threads in the process also change their credentials.
+For details, see
+.BR nptl (7).
+.SH STANDARDS
+None.
+.SH HISTORY
+Linux 2.1.44,
+glibc 2.3.2.
+HP-UX, FreeBSD.
+.P
+The original Linux
+.BR setresuid ()
+and
+.BR setresgid ()
+system calls supported only 16-bit user and group IDs.
+Subsequently, Linux 2.4 added
+.BR setresuid32 ()
+and
+.BR setresgid32 (),
+supporting 32-bit IDs.
+The glibc
+.BR setresuid ()
+and
+.BR setresgid ()
+wrapper functions transparently deal with the variations across kernel versions.
+.SH SEE ALSO
+.BR getresuid (2),
+.BR getuid (2),
+.BR setfsgid (2),
+.BR setfsuid (2),
+.BR setreuid (2),
+.BR setuid (2),
+.BR capabilities (7),
+.BR credentials (7),
+.BR user_namespaces (7)