| blob | d4ed809f352073c21de213f7f0468b2cd3b4fc15 |
1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
2 .\" and Copyright (C) 2009, 2010, 2014, 2015, Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" All rights reserved.
4 .\"
5 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed by the University of
17 .\" California, Berkeley and its contributors.
18 .\" 4. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\" %%%LICENSE_END
34 .\"
35 .\" @(#)setregid.2 6.4 (Berkeley) 3/10/91
36 .\"
37 .\" Modified Sat Jul 24 09:08:49 1993 by Rik Faith <faith@cs.unc.edu>
38 .\" Portions extracted from linux/kernel/sys.c:
39 .\" Copyright (C) 1991, 1992 Linus Torvalds
40 .\" May be distributed under the GNU General Public License
41 .\" Changes: 1994-07-29 by Wilf <G.Wilford@ee.surrey.ac.uk>
42 .\" 1994-08-02 by Wilf due to change in kernel.
43 .\" 2004-07-04 by aeb
44 .\" 2004-05-27 by Michael Kerrisk
45 .\"
46 .TH SETREUID 2 2021-03-22 "Linux" "Linux Programmer's Manual"
47 .SH NAME
48 setreuid, setregid \- set real and/or effective user or group ID
49 .SH SYNOPSIS
50 .nf
51 .B #include <unistd.h>
52 .PP
53 .BI "int setreuid(uid_t " ruid ", uid_t " euid );
54 .BI "int setregid(gid_t " rgid ", gid_t " egid );
55 .fi
56 .PP
57 .RS -4
58 Feature Test Macro Requirements for glibc (see
59 .BR feature_test_macros (7)):
60 .RE
61 .PP
62 .BR setreuid (),
63 .BR setregid ():
64 .nf
65 _XOPEN_SOURCE >= 500
66 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
67 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
68 || /* Glibc <= 2.19: */ _BSD_SOURCE
69 .fi
70 .SH DESCRIPTION
71 .BR setreuid ()
72 sets real and effective user IDs of the calling process.
73 .PP
74 Supplying a value of \-1 for either the real or effective user ID forces
75 the system to leave that ID unchanged.
76 .PP
77 Unprivileged processes may only set the effective user ID to the real user ID,
78 the effective user ID, or the saved set-user-ID.
79 .PP
80 Unprivileged users may only set the real user ID to
81 the real user ID or the effective user ID.
82 .PP
83 If the real user ID is set (i.e.,
84 .I ruid
85 is not \-1) or the effective user ID is set to a value
86 not equal to the previous real user ID,
87 the saved set-user-ID will be set to the new effective user ID.
88 .PP
89 Completely analogously,
90 .BR setregid ()
91 sets real and effective group ID's of the calling process,
92 and all of the above holds with "group" instead of "user".
93 .SH RETURN VALUE
94 On success, zero is returned.
95 On error, \-1 is returned, and
96 .I errno
97 is set to indicate the error.
98 .PP
99 .IR Note :
100 there are cases where
101 .BR setreuid ()
102 can fail even when the caller is UID 0;
103 it is a grave security error to omit checking for a failure return from
104 .BR setreuid ().
105 .SH ERRORS
106 .TP
107 .B EAGAIN
108 The call would change the caller's real UID (i.e.,
109 .I ruid
110 does not match the caller's real UID),
111 but there was a temporary failure allocating the
112 necessary kernel data structures.
113 .TP
114 .B EAGAIN
115 .I ruid
116 does not match the caller's real UID and this call would
117 bring the number of processes belonging to the real user ID
118 .I ruid
119 over the caller's
120 .B RLIMIT_NPROC
121 resource limit.
122 Since Linux 3.1, this error case no longer occurs
123 (but robust applications should check for this error);
124 see the description of
125 .B EAGAIN
126 in
127 .BR execve (2).
128 .TP
129 .B EINVAL
130 One or more of the target user or group IDs
131 is not valid in this user namespace.
132 .TP
133 .B EPERM
134 The calling process is not privileged
135 (on Linux, does not have the necessary capability in its user namespace:
136 .B CAP_SETUID
137 in the case of
138 .BR setreuid (),
139 or
140 .B CAP_SETGID
141 in the case of
142 .BR setregid ())
143 and a change other than (i)
144 swapping the effective user (group) ID with the real user (group) ID,
145 or (ii) setting one to the value of the other or (iii) setting the
146 effective user (group) ID to the value of the
147 saved set-user-ID (saved set-group-ID) was specified.
148 .SH CONFORMING TO
149 POSIX.1-2001, POSIX.1-2008, 4.3BSD
150 .RB ( setreuid ()
151 and
152 .BR setregid ()
153 first appeared in 4.2BSD).
154 .SH NOTES
155 Setting the effective user (group) ID to the
156 saved set-user-ID (saved set-group-ID) is
157 possible since Linux 1.1.37 (1.1.38).
158 .PP
159 POSIX.1 does not specify all of the UID changes that Linux permits
160 for an unprivileged process.
161 For
162 .BR setreuid (),
163 the effective user ID can be made the same as the
164 real user ID or the saved set-user-ID,
165 and it is unspecified whether unprivileged processes may set the
166 real user ID to the real user ID, the effective user ID, or the
167 saved set-user-ID.
168 For
169 .BR setregid (),
170 the real group ID can be changed to the value of the saved set-group-ID,
171 and the effective group ID can be changed to the value of
172 the real group ID or the saved set-group-ID.
173 The precise details of what ID changes are permitted vary
174 across implementations.
175 .PP
176 POSIX.1 makes no specification about the effect of these calls
177 on the saved set-user-ID and saved set-group-ID.
178 .PP
179 The original Linux
180 .BR setreuid ()
181 and
182 .BR setregid ()
183 system calls supported only 16-bit user and group IDs.
184 Subsequently, Linux 2.4 added
185 .BR setreuid32 ()
186 and
187 .BR setregid32 (),
188 supporting 32-bit IDs.
189 The glibc
190 .BR setreuid ()
191 and
192 .BR setregid ()
193 wrapper functions transparently deal with the variations across kernel versions.
194 .\"
195 .SS C library/kernel differences
196 At the kernel level, user IDs and group IDs are a per-thread attribute.
197 However, POSIX requires that all threads in a process
198 share the same credentials.
199 The NPTL threading implementation handles the POSIX requirements by
200 providing wrapper functions for
201 the various system calls that change process UIDs and GIDs.
202 These wrapper functions (including those for
203 .BR setreuid ()
204 and
205 .BR setregid ())
206 employ a signal-based technique to ensure
207 that when one thread changes credentials,
208 all of the other threads in the process also change their credentials.
209 For details, see
210 .BR nptl (7).
211 .SH SEE ALSO
212 .BR getgid (2),
213 .BR getuid (2),
214 .BR seteuid (2),
215 .BR setgid (2),
216 .BR setresuid (2),
217 .BR setuid (2),
218 .BR capabilities (7),
219 .BR credentials (7),
220 .BR user_namespaces (7)