diff options
Diffstat (limited to 'man2/setreuid.2')
| -rw-r--r-- | man2/setreuid.2 | 193 |
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) |