man2/setreuid.2

   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 2017-09-15 "Linux" "Linux Programmer's Manual"
  47 .SH NAME
  48 setreuid, setregid \- set real and/or effective user or group ID
  49 .SH SYNOPSIS
  50 .B #include <sys/types.h>
  51 .br
  52 .B #include <unistd.h>
  53 .PP
  54 .BI "int setreuid(uid_t " ruid ", uid_t " euid );
  55 .br
  56 .BI "int setregid(gid_t " rgid ", gid_t " egid );
  57 .PP
  58 .in -4n
  59 Feature Test Macro Requirements for glibc (see
  60 .BR feature_test_macros (7)):
  61 .in
  62 .PP
  63 .BR setreuid (),
  64 .BR setregid ():
  65 .RS 4
  66 .ad l
  67 _XOPEN_SOURCE\ >=\ 500
  68 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  69     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  70     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
  71 .ad
  72 .RE
  73 .SH DESCRIPTION
  74 .BR setreuid ()
  75 sets real and effective user IDs of the calling process.
  76 .PP
  77 Supplying a value of \-1 for either the real or effective user ID forces
  78 the system to leave that ID unchanged.
  79 .PP
  80 Unprivileged processes may only set the effective user ID to the real user ID,
  81 the effective user ID, or the saved set-user-ID.
  82 .PP
  83 Unprivileged users may only set the real user ID to
  84 the real user ID or the effective user ID.
  85 .PP
  86 If the real user ID is set (i.e.,
  87 .I ruid
  88 is not \-1) or the effective user ID is set to a value
  89 not equal to the previous real user ID,
  90 the saved set-user-ID will be set to the new effective user ID.
  91 .PP
  92 Completely analogously,
  93 .BR setregid ()
  94 sets real and effective group ID's of the calling process,
  95 and all of the above holds with "group" instead of "user".
  96 .SH RETURN VALUE
  97 On success, zero is returned.
  98 On error, \-1 is returned, and
  99 .I errno
 100 is set appropriately.
 101 .PP
 102 .IR Note :
 103 there are cases where
 104 .BR setreuid ()
 105 can fail even when the caller is UID 0;
 106 it is a grave security error to omit checking for a failure return from
 107 .BR setreuid ().
 108 .SH ERRORS
 109 .TP
 110 .B EAGAIN
 111 The call would change the caller's real UID (i.e.,
 112 .I ruid
 113 does not match the caller's real UID),
 114 but there was a temporary failure allocating the
 115 necessary kernel data structures.
 116 .TP
 117 .B EAGAIN
 118 .I ruid
 119 does not match the caller's real UID and this call would
 120 bring the number of processes belonging to the real user ID
 121 .I ruid
 122 over the caller's
 123 .B RLIMIT_NPROC
 124 resource limit.
 125 Since Linux 3.1, this error case no longer occurs
 126 (but robust applications should check for this error);
 127 see the description of
 128 .B EAGAIN
 129 in
 130 .BR execve (2).
 131 .TP
 132 .B EINVAL
 133 One or more of the target user or group IDs
 134 is not valid in this user namespace.
 135 .TP
 136 .B EPERM
 137 The calling process is not privileged
 138 (on Linux, does not have the necessary capability in its user namespace:
 139 .B CAP_SETUID
 140 in the case of
 141 .BR setreuid (),
 142 or
 143 .B CAP_SETGID
 144 in the case of
 145 .BR setregid ())
 146 and a change other than (i)
 147 swapping the effective user (group) ID with the real user (group) ID,
 148 or (ii) setting one to the value of the other or (iii) setting the
 149 effective user (group) ID to the value of the
 150 saved set-user-ID (saved set-group-ID) was specified.
 151 .SH CONFORMING TO
 152 POSIX.1-2001, POSIX.1-2008, 4.3BSD
 153 .RB ( setreuid ()
 154 and
 155 .BR setregid ()
 156 first appeared in 4.2BSD).
 157 .SH NOTES
 158 Setting the effective user (group) ID to the
 159 saved set-user-ID (saved set-group-ID) is
 160 possible since Linux 1.1.37 (1.1.38).
 161 .PP
 162 POSIX.1 does not specify all of the UID changes that Linux permits
 163 for an unprivileged process.
 164 For
 165 .BR setreuid (),
 166 the effective user ID can be made the same as the
 167 real user ID or the saved set-user-ID,
 168 and it is unspecified whether unprivileged processes may set the
 169 real user ID to the real user ID, the effective user ID, or the
 170 saved set-user-ID.
 171 For
 172 .BR setregid (),
 173 the real group ID can be changed to the value of the saved set-group-ID,
 174 and the effective group ID can be changed to the value of
 175 the real group ID or the saved set-group-ID.
 176 The precise details of what ID changes are permitted vary
 177 across implementations.
 178 .PP
 179 POSIX.1 makes no specification about the effect of these calls
 180 on the saved set-user-ID and saved set-group-ID.
 181 .PP
 182 The original Linux
 183 .BR setreuid ()
 184 and
 185 .BR setregid ()
 186 system calls supported only 16-bit user and group IDs.
 187 Subsequently, Linux 2.4 added
 188 .BR setreuid32 ()
 189 and
 190 .BR setregid32 (),
 191 supporting 32-bit IDs.
 192 The glibc
 193 .BR setreuid ()
 194 and
 195 .BR setregid ()
 196 wrapper functions transparently deal with the variations across kernel versions.
 197 .\"
 198 .SS C library/kernel differences
 199 At the kernel level, user IDs and group IDs are a per-thread attribute.
 200 However, POSIX requires that all threads in a process
 201 share the same credentials.
 202 The NPTL threading implementation handles the POSIX requirements by
 203 providing wrapper functions for
 204 the various system calls that change process UIDs and GIDs.
 205 These wrapper functions (including those for
 206 .BR setreuid ()
 207 and
 208 .BR setregid ())
 209 employ a signal-based technique to ensure
 210 that when one thread changes credentials,
 211 all of the other threads in the process also change their credentials.
 212 For details, see
 213 .BR nptl (7).
 214 .SH SEE ALSO
 215 .BR getgid (2),
 216 .BR getuid (2),
 217 .BR seteuid (2),
 218 .BR setgid (2),
 219 .BR setresuid (2),
 220 .BR setuid (2),
 221 .BR capabilities (7),
 222 .BR credentials (7),
 223 .BR user_namespaces (7)