Debian Codegraph @

upstream/debian-unstable/man2/setreuid.2

raw
1 .\" Copyright 1983-1991, The Regents of the University of California.
2 .\" Copyright 2009-2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: BSD-4-Clause-UC
6 .\"
7 .TH setreuid 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 setreuid, setregid \- set real and/or effective user or group ID
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BI "int setreuid(uid_t " ruid ", uid_t " euid );
18 .BI "int setregid(gid_t " rgid ", gid_t " egid );
19 .fi
20 .P
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
25 .P
26 .BR setreuid (),
27 .BR setregid ():
28 .nf
29 _XOPEN_SOURCE >= 500
30 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
31 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
32 || /* glibc <= 2.19: */ _BSD_SOURCE
33 .fi
34 .SH DESCRIPTION
35 .BR setreuid ()
36 sets real and effective user IDs of the calling process.
37 .P
38 Supplying a value of \-1 for either the real or effective user ID forces
39 the system to leave that ID unchanged.
40 .P
41 Unprivileged processes may only set the effective user ID to the real user ID,
42 the effective user ID, or the saved set-user-ID.
43 .P
44 Unprivileged users may only set the real user ID to
45 the real user ID or the effective user ID.
46 .P
47 If the real user ID is set (i.e.,
48 .I ruid
49 is not \-1) or the effective user ID is set to a value
50 not equal to the previous real user ID,
51 the saved set-user-ID will be set to the new effective user ID.
52 .P
53 Completely analogously,
54 .BR setregid ()
55 sets real and effective group ID's of the calling process,
56 and all of the above holds with "group" instead of "user".
57 .SH RETURN VALUE
58 On success, zero is returned.
59 On error, \-1 is returned, and
60 .I errno
61 is set to indicate the error.
62 .P
63 .IR Note :
64 there are cases where
65 .BR setreuid ()
66 can fail even when the caller is UID 0;
67 it is a grave security error to omit checking for a failure return from
68 .BR setreuid ().
69 .SH ERRORS
70 .TP
71 .B EAGAIN
72 The call would change the caller's real UID (i.e.,
73 .I ruid
74 does not match the caller's real UID),
75 but there was a temporary failure allocating the
76 necessary kernel data structures.
77 .TP
78 .B EAGAIN
79 .I ruid
80 does not match the caller's real UID and this call would
81 bring the number of processes belonging to the real user ID
82 .I ruid
83 over the caller's
84 .B RLIMIT_NPROC
85 resource limit.
86 Since Linux 3.1, this error case no longer occurs
87 (but robust applications should check for this error);
88 see the description of
89 .B EAGAIN
90 in
91 .BR execve (2).
92 .TP
93 .B EINVAL
94 One or more of the target user or group IDs
95 is not valid in this user namespace.
96 .TP
97 .B EPERM
98 The calling process is not privileged
99 (on Linux, does not have the necessary capability in its user namespace:
100 .B CAP_SETUID
101 in the case of
102 .BR setreuid (),
103 or
104 .B CAP_SETGID
105 in the case of
106 .BR setregid ())
107 and a change other than (i)
108 swapping the effective user (group) ID with the real user (group) ID,
109 or (ii) setting one to the value of the other or (iii) setting the
110 effective user (group) ID to the value of the
111 saved set-user-ID (saved set-group-ID) was specified.
112 .SH VERSIONS
113 POSIX.1 does not specify all of the UID changes that Linux permits
114 for an unprivileged process.
115 For
116 .BR setreuid (),
117 the effective user ID can be made the same as the
118 real user ID or the saved set-user-ID,
119 and it is unspecified whether unprivileged processes may set the
120 real user ID to the real user ID, the effective user ID, or the
121 saved set-user-ID.
122 For
123 .BR setregid (),
124 the real group ID can be changed to the value of the saved set-group-ID,
125 and the effective group ID can be changed to the value of
126 the real group ID or the saved set-group-ID.
127 The precise details of what ID changes are permitted vary
128 across implementations.
129 .P
130 POSIX.1 makes no specification about the effect of these calls
131 on the saved set-user-ID and saved set-group-ID.
132 .SH STANDARDS
133 POSIX.1-2024.
134 .SH HISTORY
135 POSIX.1-2001, 4.3BSD (first appeared in 4.2BSD).
136 .P
137 Setting the effective user (group) ID to the
138 saved set-user-ID (saved set-group-ID) is
139 possible since Linux 1.1.37 (1.1.38).
140 .P
141 The original Linux
142 .BR setreuid ()
143 and
144 .BR setregid ()
145 system calls supported only 16-bit user and group IDs.
146 Subsequently, Linux 2.4 added
147 .BR setreuid32 ()
148 and
149 .BR setregid32 (),
150 supporting 32-bit IDs.
151 The glibc
152 .BR setreuid ()
153 and
154 .BR setregid ()
155 wrapper functions transparently deal with the variations across kernel versions.
156 .\"
157 .SS C library/kernel differences
158 At the kernel level, user IDs and group IDs are a per-thread attribute.
159 However, POSIX requires that all threads in a process
160 share the same credentials.
161 The NPTL threading implementation handles the POSIX requirements by
162 providing wrapper functions for
163 the various system calls that change process UIDs and GIDs.
164 These wrapper functions (including those for
165 .BR setreuid ()
166 and
167 .BR setregid ())
168 employ a signal-based technique to ensure
169 that when one thread changes credentials,
170 all of the other threads in the process also change their credentials.
171 For details, see
172 .BR nptl (7).
173 .SH SEE ALSO
174 .BR getgid (2),
175 .BR getuid (2),
176 .BR seteuid (2),
177 .BR setgid (2),
178 .BR setresuid (2),
179 .BR setuid (2),
180 .BR capabilities (7),
181 .BR credentials (7),
182 .BR user_namespaces (7)