summaryrefslogtreecommitdiffstats
path: root/man2/setreuid.2
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man2/setreuid.2193
1 files changed, 193 insertions, 0 deletions
diff --git a/man2/setreuid.2 b/man2/setreuid.2
new file mode 100644
index 0000000..121deb4
--- /dev/null
+++ b/man2/setreuid.2
@@ -0,0 +1,193 @@
+.\" Copyright (c) 1983, 1991 The Regents of the University of California.
+.\" and Copyright (C) 2009, 2010, 2014, 2015, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\" @(#)setregid.2 6.4 (Berkeley) 3/10/91
+.\"
+.\" Modified Sat Jul 24 09:08:49 1993 by Rik Faith <faith@cs.unc.edu>
+.\" Portions extracted from linux/kernel/sys.c:
+.\" Copyright (C) 1991, 1992 Linus Torvalds
+.\" May be distributed under the GNU General Public License
+.\" Changes: 1994-07-29 by Wilf <G.Wilford@ee.surrey.ac.uk>
+.\" 1994-08-02 by Wilf due to change in kernel.
+.\" 2004-07-04 by aeb
+.\" 2004-05-27 by Michael Kerrisk
+.\"
+.TH setreuid 2 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+setreuid, setregid \- set real and/or effective user or group ID
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.PP
+.BI "int setreuid(uid_t " ruid ", uid_t " euid );
+.BI "int setregid(gid_t " rgid ", gid_t " egid );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR setreuid (),
+.BR setregid ():
+.nf
+ _XOPEN_SOURCE >= 500
+.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+ || /* Since glibc 2.19: */ _DEFAULT_SOURCE
+ || /* glibc <= 2.19: */ _BSD_SOURCE
+.fi
+.SH DESCRIPTION
+.BR setreuid ()
+sets real and effective user IDs of the calling process.
+.PP
+Supplying a value of \-1 for either the real or effective user ID forces
+the system to leave that ID unchanged.
+.PP
+Unprivileged processes may only set the effective user ID to the real user ID,
+the effective user ID, or the saved set-user-ID.
+.PP
+Unprivileged users may only set the real user ID to
+the real user ID or the effective user ID.
+.PP
+If the real user ID is set (i.e.,
+.I ruid
+is not \-1) or the effective user ID is set to a value
+not equal to the previous real user ID,
+the saved set-user-ID will be set to the new effective user ID.
+.PP
+Completely analogously,
+.BR setregid ()
+sets real and effective group ID's of the calling process,
+and all of the above holds with "group" instead of "user".
+.SH RETURN VALUE
+On success, zero is returned.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.IR Note :
+there are cases where
+.BR setreuid ()
+can fail even when the caller is UID 0;
+it is a grave security error to omit checking for a failure return from
+.BR setreuid ().
+.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
+(on Linux, does not have the necessary capability in its user namespace:
+.B CAP_SETUID
+in the case of
+.BR setreuid (),
+or
+.B CAP_SETGID
+in the case of
+.BR setregid ())
+and a change other than (i)
+swapping the effective user (group) ID with the real user (group) ID,
+or (ii) setting one to the value of the other or (iii) setting the
+effective user (group) ID to the value of the
+saved set-user-ID (saved set-group-ID) was specified.
+.SH VERSIONS
+POSIX.1 does not specify all of the UID changes that Linux permits
+for an unprivileged process.
+For
+.BR setreuid (),
+the effective user ID can be made the same as the
+real user ID or the saved set-user-ID,
+and it is unspecified whether unprivileged processes may set the
+real user ID to the real user ID, the effective user ID, or the
+saved set-user-ID.
+For
+.BR setregid (),
+the real group ID can be changed to the value of the saved set-group-ID,
+and the effective group ID can be changed to the value of
+the real group ID or the saved set-group-ID.
+The precise details of what ID changes are permitted vary
+across implementations.
+.PP
+POSIX.1 makes no specification about the effect of these calls
+on the saved set-user-ID and saved set-group-ID.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, 4.3BSD (first appeared in 4.2BSD).
+.PP
+Setting the effective user (group) ID to the
+saved set-user-ID (saved set-group-ID) is
+possible since Linux 1.1.37 (1.1.38).
+.PP
+The original Linux
+.BR setreuid ()
+and
+.BR setregid ()
+system calls supported only 16-bit user and group IDs.
+Subsequently, Linux 2.4 added
+.BR setreuid32 ()
+and
+.BR setregid32 (),
+supporting 32-bit IDs.
+The glibc
+.BR setreuid ()
+and
+.BR setregid ()
+wrapper functions transparently deal with the variations across kernel 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 setreuid ()
+and
+.BR setregid ())
+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 SEE ALSO
+.BR getgid (2),
+.BR getuid (2),
+.BR seteuid (2),
+.BR setgid (2),
+.BR setresuid (2),
+.BR setuid (2),
+.BR capabilities (7),
+.BR credentials (7),
+.BR user_namespaces (7)