| .\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) |
| .\" and Copyright (C) 2005, 2010, 2014, 2015, Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified, 2003-05-26, Michael Kerrisk, <mtk.manpages@gmail.com> |
| .TH SETRESUID 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| setresuid, setresgid \- set real, effective, and saved user or group ID |
| .SH SYNOPSIS |
| .nf |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .B #include <unistd.h> |
| .PP |
| .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. |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| If one of the arguments equals \-1, the corresponding value is not changed. |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| .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 |
| These calls are available under Linux since Linux 2.1.44. |
| .SH CONFORMING TO |
| These calls are nonstandard; |
| they also appear on HP-UX and some of the BSDs. |
| .SH NOTES |
| Under HP-UX and FreeBSD, the prototype is found in |
| .IR <unistd.h> . |
| Under Linux, the prototype is provided by glibc since version 2.3.2. |
| .PP |
| 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. |
| .\" |
| .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 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) |