lib/libcr/sys/setuid.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  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 .\"     @(#)setuid.2    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/sys/setuid.2,v 1.13.2.7 2003/02/14 00:49:42 keramida Exp $
  34 .\" $DragonFly: src/lib/libcr/sys/Attic/setuid.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt SETUID 2
  38 .Os
  39 .Sh NAME
  40 .Nm setuid ,
  41 .Nm seteuid ,
  42 .Nm setgid ,
  43 .Nm setegid ,
  44 .Nd set user and group ID
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In sys/types.h
  49 .In unistd.h
  50 .Ft int
  51 .Fn setuid "uid_t uid"
  52 .Ft int
  53 .Fn seteuid "uid_t euid"
  54 .Ft int
  55 .Fn setgid "gid_t gid"
  56 .Ft int
  57 .Fn setegid "gid_t egid"
  58 .Sh DESCRIPTION
  59 The
  60 .Fn setuid
  61 function
  62 sets the real and effective
  63 user IDs and the saved set-user-ID of the current process
  64 to the specified value.
  65 .\" Comment out next block for !_POSIX_SAVED_IDS
  66 .\" The real user ID and the saved set-user-ID are changed only if the
  67 .\" effective user ID is that of the super user.
  68 .\" I.e.
  69 .\" .Fn setuid
  70 .\" function is equal to
  71 .\" .Fn seteuid
  72 .\" function if the effective user ID is not that of the super user.
  73 .\" End of block
  74 The
  75 .Fn setuid
  76 function is permitted if the specified ID is equal to the real user ID
  77 .\" Comment out next line for !_POSIX_SAVED_IDS
  78 .\" or the saved set-user-ID
  79 .\" Next line is for Appendix B.4.2.2 case.
  80 or the effective user ID
  81 of the process, or if the effective user ID is that of the super user.
  82 .Pp
  83 The
  84 .Fn setgid
  85 function
  86 sets the real and effective
  87 group IDs and the saved set-group-ID of the current process
  88 to the specified value.
  89 .\" Comment out next block for !_POSIX_SAVED_IDS
  90 .\" The real group ID and the saved set-group-ID are changed only if the
  91 .\" effective user ID is that of the super user.
  92 .\" I.e.
  93 .\" .Fn setgid
  94 .\" function is equal to
  95 .\" .Fn setegid
  96 .\" function if the effective user ID is not that of the super user.
  97 .\" End of block
  98 The
  99 .Fn setgid
 100 function is permitted if the specified ID is equal to the real group ID
 101 .\" Comment out next line for !_POSIX_SAVED_IDS
 102 .\" or the saved set-group-ID
 103 .\" Next line is for Appendix B.4.2.2 case.
 104 or the effective group ID
 105 of the process, or if the effective user ID is that of the super user.
 106 .Pp
 107 The
 108 .Fn seteuid
 109 function
 110 .Pq Fn setegid
 111 sets the effective user ID (group ID) of the
 112 current process.
 113 The effective user ID may be set to the value
 114 of the real user ID or the saved set-user-ID (see
 115 .Xr intro 2
 116 and
 117 .Xr execve 2 ) ;
 118 in this way, the effective user ID of a set-user-ID executable
 119 may be toggled by switching to the real user ID, then re-enabled
 120 by reverting to the set-user-ID value.
 121 Similarly, the effective group ID may be set to the value
 122 of the real group ID or the saved set-group-ID.
 123 .Sh RETURN VALUES
 124 .Rv -std
 125 .Sh ERRORS
 126 The functions will fail if:
 127 .Bl -tag -width Er
 128 .It Bq Er EPERM
 129 The user is not the super user and the ID
 130 specified is not the real, effective ID, or saved ID.
 131 .El
 132 .Sh SEE ALSO
 133 .Xr getgid 2 ,
 134 .Xr getuid 2 ,
 135 .Xr issetugid 2 ,
 136 .Xr setregid 2 ,
 137 .Xr setreuid 2
 138 .Sh STANDARDS
 139 The
 140 .Fn setuid
 141 and
 142 .Fn setgid
 143 functions are compliant with the
 144 .St -p1003.1-90
 145 specification with
 146 .Li _POSIX_SAVED_IDS
 147 .\" Uncomment next line for !_POSIX_SAVED_IDS
 148 not
 149 defined with the permitted extensions from Appendix B.4.2.2.
 150 The
 151 .Fn seteuid
 152 and
 153 .Fn setegid
 154 functions are extensions based on the
 155 .Tn POSIX
 156 concept of
 157 .Li _POSIX_SAVED_IDS ,
 158 and have been proposed for a future revision of the standard.
 159 .Sh HISTORY
 160 A
 161 .Fn setuid
 162 and a
 163 .Fn setgid
 164 function calls appeared in
 165 .At v7 .