]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
38883d95 | 2 | .\" and Copyright (C) 2009, 2010, 2014, 2015, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
3 | .\" All rights reserved. |
4 | .\" | |
47009d5e | 5 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
6 | .\" |
7 | .\" @(#)setregid.2 6.4 (Berkeley) 3/10/91 | |
8 | .\" | |
9 | .\" Modified Sat Jul 24 09:08:49 1993 by Rik Faith <faith@cs.unc.edu> | |
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 <G.Wilford@ee.surrey.ac.uk> | |
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 | .\" | |
45186a5d | 18 | .TH SETREUID 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
19 | .SH NAME |
20 | setreuid, setregid \- set real and/or effective user or group ID | |
ec93f52f AC |
21 | .SH LIBRARY |
22 | Standard C library | |
8fc3b2cf | 23 | .RI ( libc ", " \-lc ) |
fea681da | 24 | .SH SYNOPSIS |
c7db92b9 | 25 | .nf |
fea681da | 26 | .B #include <unistd.h> |
68e4db0a | 27 | .PP |
fea681da | 28 | .BI "int setreuid(uid_t " ruid ", uid_t " euid ); |
fea681da | 29 | .BI "int setregid(gid_t " rgid ", gid_t " egid ); |
c7db92b9 | 30 | .fi |
68e4db0a | 31 | .PP |
d39ad78f | 32 | .RS -4 |
cc4615cc MK |
33 | Feature Test Macro Requirements for glibc (see |
34 | .BR feature_test_macros (7)): | |
d39ad78f | 35 | .RE |
68e4db0a | 36 | .PP |
cc4615cc MK |
37 | .BR setreuid (), |
38 | .BR setregid (): | |
9d2adbae | 39 | .nf |
5c10d2c5 MK |
40 | _XOPEN_SOURCE >= 500 |
41 | .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED | |
9d2adbae MK |
42 | || /* Since glibc 2.19: */ _DEFAULT_SOURCE |
43 | || /* Glibc <= 2.19: */ _BSD_SOURCE | |
44 | .fi | |
fea681da | 45 | .SH DESCRIPTION |
e511ffb6 | 46 | .BR setreuid () |
a1ffe9f5 | 47 | sets real and effective user IDs of the calling process. |
efeece04 | 48 | .PP |
fea681da MK |
49 | Supplying a value of \-1 for either the real or effective user ID forces |
50 | the system to leave that ID unchanged. | |
efeece04 | 51 | .PP |
fea681da | 52 | Unprivileged processes may only set the effective user ID to the real user ID, |
715e4bec | 53 | the effective user ID, or the saved set-user-ID. |
efeece04 | 54 | .PP |
715e4bec | 55 | Unprivileged users may only set the real user ID to |
fea681da | 56 | the real user ID or the effective user ID. |
efeece04 | 57 | .PP |
297c144f MK |
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 | |
d9df8ff8 MK |
61 | not equal to the previous real user ID, |
62 | the saved set-user-ID will be set to the new effective user ID. | |
efeece04 | 63 | .PP |
fea681da | 64 | Completely analogously, |
e511ffb6 | 65 | .BR setregid () |
a1ffe9f5 | 66 | sets real and effective group ID's of the calling process, |
fea681da | 67 | and all of the above holds with "group" instead of "user". |
47297adb | 68 | .SH RETURN VALUE |
c13182ef MK |
69 | On success, zero is returned. |
70 | On error, \-1 is returned, and | |
fea681da | 71 | .I errno |
f6a4078b | 72 | is set to indicate the error. |
efeece04 | 73 | .PP |
27cbe704 MK |
74 | .IR Note : |
75 | there are cases where | |
76 | .BR setreuid () | |
77 | can fail even when the caller is UID 0; | |
29d3bdc4 | 78 | it is a grave security error to omit checking for a failure return from |
27cbe704 | 79 | .BR setreuid (). |
fea681da MK |
80 | .SH ERRORS |
81 | .TP | |
4b3beb49 | 82 | .B EAGAIN |
27bb77b0 MK |
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 | |
4b3beb49 MK |
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. | |
c2cb87b6 MK |
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). | |
4b3beb49 | 103 | .TP |
0076479c MK |
104 | .B EINVAL |
105 | One or more of the target user or group IDs | |
106 | is not valid in this user namespace. | |
107 | .TP | |
fea681da | 108 | .B EPERM |
a1ffe9f5 | 109 | The calling process is not privileged |
36a62e03 | 110 | (on Linux, does not have the necessary capability in its user namespace: |
fea681da | 111 | .B CAP_SETUID |
36a62e03 | 112 | in the case of |
c13182ef | 113 | .BR setreuid (), |
36a62e03 | 114 | or |
fea681da | 115 | .B CAP_SETGID |
36a62e03 | 116 | in the case of |
fea681da MK |
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 | |
d9df8ff8 MK |
121 | effective user (group) ID to the value of the |
122 | saved set-user-ID (saved set-group-ID) was specified. | |
3113c7f3 | 123 | .SH STANDARDS |
c2798764 | 124 | POSIX.1-2001, POSIX.1-2008, 4.3BSD |
9d80eb47 | 125 | .RB ( setreuid () |
fea681da | 126 | and |
e511ffb6 | 127 | .BR setregid () |
9d80eb47 | 128 | first appeared in 4.2BSD). |
a1d5f77c MK |
129 | .SH NOTES |
130 | Setting the effective user (group) ID to the | |
131 | saved set-user-ID (saved set-group-ID) is | |
132 | possible since Linux 1.1.37 (1.1.38). | |
efeece04 | 133 | .PP |
75295d40 MK |
134 | POSIX.1 does not specify all of the UID changes that Linux permits |
135 | for an unprivileged process. | |
715e4bec MK |
136 | For |
137 | .BR setreuid (), | |
d5dd3a91 | 138 | the effective user ID can be made the same as the |
75295d40 | 139 | real user ID or the saved set-user-ID, |
715e4bec MK |
140 | and it is unspecified whether unprivileged processes may set the |
141 | real user ID to the real user ID, the effective user ID, or the | |
142 | saved set-user-ID. | |
143 | For | |
144 | .BR setregid (), | |
145 | the real group ID can be changed to the value of the saved set-group-ID, | |
146 | and the effective group ID can be changed to the value of | |
147 | the real group ID or the saved set-group-ID. | |
148 | The precise details of what ID changes are permitted vary | |
149 | across implementations. | |
efeece04 | 150 | .PP |
715e4bec MK |
151 | POSIX.1 makes no specification about the effect of these calls |
152 | on the saved set-user-ID and saved set-group-ID. | |
efeece04 | 153 | .PP |
ee3b2c76 MK |
154 | The original Linux |
155 | .BR setreuid () | |
156 | and | |
157 | .BR setregid () | |
158 | system calls supported only 16-bit user and group IDs. | |
c5662d5d | 159 | Subsequently, Linux 2.4 added |
ee3b2c76 MK |
160 | .BR setreuid32 () |
161 | and | |
162 | .BR setregid32 (), | |
163 | supporting 32-bit IDs. | |
164 | The glibc | |
165 | .BR setreuid () | |
166 | and | |
167 | .BR setregid () | |
168 | wrapper functions transparently deal with the variations across kernel versions. | |
38883d95 | 169 | .\" |
0722a578 | 170 | .SS C library/kernel differences |
38883d95 MK |
171 | At the kernel level, user IDs and group IDs are a per-thread attribute. |
172 | However, POSIX requires that all threads in a process | |
173 | share the same credentials. | |
174 | The NPTL threading implementation handles the POSIX requirements by | |
175 | providing wrapper functions for | |
176 | the various system calls that change process UIDs and GIDs. | |
177 | These wrapper functions (including those for | |
178 | .BR setreuid () | |
179 | and | |
180 | .BR setregid ()) | |
181 | employ a signal-based technique to ensure | |
182 | that when one thread changes credentials, | |
183 | all of the other threads in the process also change their credentials. | |
184 | For details, see | |
185 | .BR nptl (7). | |
47297adb | 186 | .SH SEE ALSO |
fea681da MK |
187 | .BR getgid (2), |
188 | .BR getuid (2), | |
189 | .BR seteuid (2), | |
190 | .BR setgid (2), | |
191 | .BR setresuid (2), | |
192 | .BR setuid (2), | |
0076479c | 193 | .BR capabilities (7), |
7d1ce2d4 | 194 | .BR credentials (7), |
f58fb24f | 195 | .BR user_namespaces (7) |