Debian Codegraph @

upstream/debian-trixie/man2/setreuid.2

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