bsd/man/man2/setuid.2

   1 .\"     $NetBSD: setuid.2,v 1.3 1995/02/27 12:37:06 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   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 .\"
  34 .\"     @(#)setuid.2    8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt SETUID 2
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm setegid ,
  41 .Nm seteuid ,
  42 .Nm setgid ,
  43 .Nm setuid
  44 .Nd set user and group ID
  45 .Sh SYNOPSIS
  46 .Fd #include <unistd.h>
  47 .Ft int
  48 .Fo setegid
  49 .Fa "gid_t egid"
  50 .Fc
  51 .Ft int
  52 .Fo seteuid
  53 .Fa "uid_t euid"
  54 .Fc
  55 .Ft int
  56 .Fo setgid
  57 .Fa "gid_t gid"
  58 .Fc
  59 .Ft int
  60 .Fo setuid
  61 .Fa "uid_t uid"
  62 .Fc
  63 .Sh DESCRIPTION
  64 The
  65 .Fn setuid
  66 function
  67 sets the real and effective
  68 user IDs and the saved set-user-ID of the current process
  69 to the specified value.
  70 The
  71 .Fn setuid
  72 function is permitted if the effective user ID is that of the super user,
  73 or if the specified user ID is the same as the effective user ID.  If
  74 not, but the specified user ID is the same as the real user ID,
  75 .Fn setuid
  76 will set the effective user ID to the real user ID.
  77 .Pp
  78 The
  79 .Fn setgid
  80 function
  81 sets the real and effective
  82 group IDs and the saved set-group-ID of the current process
  83 to the specified value.
  84 The
  85 .Fn setgid
  86 function is permitted if the effective user ID is that of the super user,
  87 or if the specified group ID is the same as the effective group ID.  If
  88 not, but the specified group ID is the same as the real group ID,
  89 .Fn setgid
  90 will set the effective group ID to the real group ID.
  91 .Pp
  92 The
  93 .Fn seteuid
  94 function
  95 .Pq Fn setegid
  96 sets the effective user ID (group ID) of the
  97 current process.
  98 The effective user ID may be set to the value
  99 of the real user ID or the saved set-user-ID (see
 100 .Xr intro 2
 101 and
 102 .Xr execve 2 ) ;
 103 in this way, the effective user ID of a set-user-ID executable
 104 may be toggled by switching to the real user ID, then re-enabled
 105 by reverting to the set-user-ID value.
 106 Similarly, the effective group ID may be set to the value
 107 of the real group ID or the saved set-user-ID.
 108 .Pp
 109 .Sh RETURN VALUES
 110 Upon success, these functions return 0;
 111 otherwise \-1 is returned.
 112 .Pp
 113 If the user is not the super user, or the uid
 114 specified is not the real, effective ID, or saved ID,
 115 these functions return \-1.
 116 .Pp
 117 .Sh ERRORS
 118 The
 119 .Fn setegid ,
 120 .Fn seteuid ,
 121 .Fn setgid ,
 122 and
 123 .Fn setuid
 124 system calls will fail if:
 125 .Bl -tag -width Er
 126 .\" ===========
 127 .It Bq Er EINVAL
 128 The value of the {group,user} ID argument is invalid
 129 and is not supported by the implementation.
 130 .\" ===========
 131 .It Bq Er EPERM
 132 The process does not have appropriate privileges and
 133 the ID argument
 134 does not match the real ID
 135 or the saved set-{group,user}-ID.
 136 .El
 137 .Sh LEGACY SYNOPSIS
 138 .Fd #include <sys/types.h>
 139 .Fd #include <unistd.h>
 140 .Pp
 141 The include file
 142 .In sys/types.h
 143 is necessary for all functions.
 144 .Sh SEE ALSO
 145 .Xr getgid 2 ,
 146 .Xr getuid 2 ,
 147 .Xr compat 5
 148 .Sh STANDARDS
 149 The
 150 .Fn setuid
 151 and
 152 .Fn setgid
 153 functions are compliant with the
 154 .St -p1003.1-90
 155 specification with
 156 .Li _POSIX_SAVED_IDS
 157 defined, with the extensions allowed in section B.4.2.2.
 158 The
 159 .Fn seteuid
 160 and
 161 .Fn setegid
 162 functions are extensions based on the
 163 .Tn POSIX
 164 concept of
 165 .Li _POSIX_SAVED_IDS ,
 166 and have been proposed for a future revision of the standard.