original/man2/setreuid.2

   1 .\" Copyright (c) 1983, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     @(#)setregid.2  6.4 (Berkeley) 3/10/91
  35 .\"
  36 .\" Modified Sat Jul 24 09:08:49 1993 by Rik Faith <faith@cs.unc.edu>
  37 .\" Portions extracted from linux/kernel/sys.c:
  38 .\"             Copyright (C) 1991, 1992  Linus Torvalds
  39 .\"             May be distributed under the GNU General Public License
  40 .\" Changes: 1994-07-29 by Wilf <G.Wilford@ee.surrey.ac.uk>
  41 .\"          1994-08-02 by Wilf due to change in kernel.
  42 .\"          2004-07-04 by aeb
  43 .\"          2004-05-27 by Michael Kerrisk
  44 .\"
  45 .TH SETREUID 2 2013-12-12 "Linux" "Linux Programmer's Manual"
  46 .SH NAME
  47 setreuid, setregid \- set real and/or effective user or group ID
  48 .SH SYNOPSIS
  49 .B #include <sys/types.h>
  50 .br
  51 .B #include <unistd.h>
  52 .sp
  53 .BI "int setreuid(uid_t " ruid ", uid_t " euid );
  54 .br
  55 .BI "int setregid(gid_t " rgid ", gid_t " egid );
  56 .sp
  57 .in -4n
  58 Feature Test Macro Requirements for glibc (see
  59 .BR feature_test_macros (7)):
  60 .in
  61 .sp
  62 .BR setreuid (),
  63 .BR setregid ():
  64 .RS 4
  65 .ad l
  66 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  67 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  68 .ad
  69 .RE
  70 .SH DESCRIPTION
  71 .BR setreuid ()
  72 sets real and effective user IDs of the calling process.
  73
  74 Supplying a value of \-1 for either the real or effective user ID forces
  75 the system to leave that ID unchanged.
  76
  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
  80 Unprivileged users may only set the real user ID to
  81 the real user ID or the effective user ID.
  82
  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
  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 appropriately.
  98 .SH ERRORS
  99 .TP
 100 .B EPERM
 101 The calling process is not privileged
 102 (Linux: does not have the
 103 .B CAP_SETUID
 104 capability in the case of
 105 .BR setreuid (),
 106 or the
 107 .B CAP_SETGID
 108 capability in the case of
 109 .BR setregid ())
 110 and a change other than (i)
 111 swapping the effective user (group) ID with the real user (group) ID,
 112 or (ii) setting one to the value of the other or (iii) setting the
 113 effective user (group) ID to the value of the
 114 saved set-user-ID (saved set-group-ID) was specified.
 115 .SH CONFORMING TO
 116 POSIX.1-2001, 4.3BSD (the
 117 .BR setreuid ()
 118 and
 119 .BR setregid ()
 120 function calls first appeared in 4.2BSD).
 121 .SH NOTES
 122 Setting the effective user (group) ID to the
 123 saved set-user-ID (saved set-group-ID) is
 124 possible since Linux 1.1.37 (1.1.38).
 125
 126 POSIX.1 does not specify all of possible ID changes that are permitted
 127 on Linux for an unprivileged process.
 128 For
 129 .BR setreuid (),
 130 the effective user ID can be made the same as the
 131 real user ID or the save set-user-ID,
 132 and it is unspecified whether unprivileged processes may set the
 133 real user ID to the real user ID, the effective user ID, or the
 134 saved set-user-ID.
 135 For
 136 .BR setregid (),
 137 the real group ID can be changed to the value of the saved set-group-ID,
 138 and the effective group ID can be changed to the value of
 139 the real group ID or the saved set-group-ID.
 140 The precise details of what ID changes are permitted vary
 141 across implementations.
 142
 143 POSIX.1 makes no specification about the effect of these calls
 144 on the saved set-user-ID and saved set-group-ID.
 145
 146 The original Linux
 147 .BR setreuid ()
 148 and
 149 .BR setregid ()
 150 system calls supported only 16-bit user and group IDs.
 151 Subsequently, Linux 2.4 added
 152 .BR setreuid32 ()
 153 and
 154 .BR setregid32 (),
 155 supporting 32-bit IDs.
 156 The glibc
 157 .BR setreuid ()
 158 and
 159 .BR setregid ()
 160 wrapper functions transparently deal with the variations across kernel versions.
 161 .SH SEE ALSO
 162 .BR getgid (2),
 163 .BR getuid (2),
 164 .BR seteuid (2),
 165 .BR setgid (2),
 166 .BR setresuid (2),
 167 .BR setuid (2),
 168 .BR capabilities (7)
 169 .SH COLOPHON
 170 This page is part of release 3.64 of the Linux
 171 .I man-pages
 172 project.
 173 A description of the project,
 174 and information about reporting bugs,
 175 can be found at
 176 \%http://www.kernel.org/doc/man\-pages/.