original/man2/setreuid.2

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