Debian Codegraph @

upstream/debian-unstable/man2/setresuid.2

raw
1 .\" Copyright 1997, Andries E. Brouwer <[email protected]>
2 .\" Copyright 2005-2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH setresuid 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 setresuid, setresgid \- set real, effective, and saved user or group ID
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
16 .B #include <unistd.h>
17 .P
18 .BI "int setresuid(uid_t " ruid ", uid_t " euid ", uid_t " suid );
19 .BI "int setresgid(gid_t " rgid ", gid_t " egid ", gid_t " sgid );
20 .fi
21 .SH DESCRIPTION
22 .BR setresuid ()
23 sets the real user ID, the effective user ID, and the
24 saved set-user-ID of the calling process.
25 .P
26 An unprivileged process may change its real UID,
27 effective UID, and saved set-user-ID, each to one of:
28 the current real UID, the current effective UID, or the
29 current saved set-user-ID.
30 .P
31 A privileged process (on Linux, one having the
32 .B CAP_SETUID
33 capability)
34 may set its real UID, effective UID, and
35 saved set-user-ID to arbitrary values.
36 .P
37 If one of the arguments equals \-1, the corresponding value is not changed.
38 .P
39 Regardless of what changes are made to the real UID, effective UID,
40 and saved set-user-ID, the filesystem UID is always set to the same
41 value as the (possibly new) effective UID.
42 .P
43 Completely analogously,
44 .BR setresgid ()
45 sets the real GID, effective GID, and saved set-group-ID
46 of the calling process (and always modifies the filesystem GID
47 to be the same as the effective GID),
48 with the same restrictions for unprivileged processes.
49 .SH RETURN VALUE
50 On success, zero is returned.
51 On error, \-1 is returned, and
52 .I errno
53 is set to indicate the error.
54 .P
55 .IR Note :
56 there are cases where
57 .BR setresuid ()
58 can fail even when the caller is UID 0;
59 it is a grave security error to omit checking for a failure return from
60 .BR setresuid ().
61 .SH ERRORS
62 .TP
63 .B EAGAIN
64 The call would change the caller's real UID (i.e.,
65 .I ruid
66 does not match the caller's real UID),
67 but there was a temporary failure allocating the
68 necessary kernel data structures.
69 .TP
70 .B EAGAIN
71 .I ruid
72 does not match the caller's real UID and this call would
73 bring the number of processes belonging to the real user ID
74 .I ruid
75 over the caller's
76 .B RLIMIT_NPROC
77 resource limit.
78 Since Linux 3.1, this error case no longer occurs
79 (but robust applications should check for this error);
80 see the description of
81 .B EAGAIN
82 in
83 .BR execve (2).
84 .TP
85 .B EINVAL
86 One or more of the target user or group IDs
87 is not valid in this user namespace.
88 .TP
89 .B EPERM
90 The calling process is not privileged (did not have the necessary
91 capability in its user namespace)
92 and tried to change the IDs to values that are not permitted.
93 For
94 .BR setresuid (),
95 the necessary capability is
96 .BR CAP_SETUID ;
97 for
98 .BR setresgid (),
99 it is
100 .BR CAP_SETGID .
101 .SH VERSIONS
102 .SS C library/kernel differences
103 At the kernel level, user IDs and group IDs are a per-thread attribute.
104 However, POSIX requires that all threads in a process
105 share the same credentials.
106 The NPTL threading implementation handles the POSIX requirements by
107 providing wrapper functions for
108 the various system calls that change process UIDs and GIDs.
109 These wrapper functions (including those for
110 .BR setresuid ()
111 and
112 .BR setresgid ())
113 employ a signal-based technique to ensure
114 that when one thread changes credentials,
115 all of the other threads in the process also change their credentials.
116 For details, see
117 .BR nptl (7).
118 .SH STANDARDS
119 POSIX.1-2024.
120 .SH HISTORY
121 POSIX.1-2024.
122 Linux 2.1.44,
123 glibc 2.3.2.
124 HP-UX, FreeBSD.
125 .P
126 The original Linux
127 .BR setresuid ()
128 and
129 .BR setresgid ()
130 system calls supported only 16-bit user and group IDs.
131 Subsequently, Linux 2.4 added
132 .BR setresuid32 ()
133 and
134 .BR setresgid32 (),
135 supporting 32-bit IDs.
136 The glibc
137 .BR setresuid ()
138 and
139 .BR setresgid ()
140 wrapper functions transparently deal with the variations across kernel versions.
141 .SH SEE ALSO
142 .BR getresuid (2),
143 .BR getuid (2),
144 .BR setfsgid (2),
145 .BR setfsuid (2),
146 .BR setreuid (2),
147 .BR setuid (2),
148 .BR capabilities (7),
149 .BR credentials (7),
150 .BR user_namespaces (7)