lib/libc/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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)setuid.2    8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/sys/setuid.2,v 1.13.2.7 2003/02/14 00:49:42 keramida Exp $
  30 .\" $DragonFly: src/lib/libc/sys/setuid.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
  31 .\"
  32 .Dd June 4, 1993
  33 .Dt SETUID 2
  34 .Os
  35 .Sh NAME
  36 .Nm setuid ,
  37 .Nm seteuid ,
  38 .Nm setgid ,
  39 .Nm setegid ,
  40 .Nd set user and group ID
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In unistd.h
  46 .Ft int
  47 .Fn setuid "uid_t uid"
  48 .Ft int
  49 .Fn seteuid "uid_t euid"
  50 .Ft int
  51 .Fn setgid "gid_t gid"
  52 .Ft int
  53 .Fn setegid "gid_t egid"
  54 .Sh DESCRIPTION
  55 The
  56 .Fn setuid
  57 function
  58 sets the real and effective
  59 user IDs and the saved set-user-ID of the current process
  60 to the specified value.
  61 .\" Comment out next block for !_POSIX_SAVED_IDS
  62 .\" The real user ID and the saved set-user-ID are changed only if the
  63 .\" effective user ID is that of the super user.
  64 .\" I.e.
  65 .\" .Fn setuid
  66 .\" function is equal to
  67 .\" .Fn seteuid
  68 .\" function if the effective user ID is not that of the super user.
  69 .\" End of block
  70 The
  71 .Fn setuid
  72 function is permitted if the specified ID is equal to the real user ID
  73 .\" Comment out next line for !_POSIX_SAVED_IDS
  74 .\" or the saved set-user-ID
  75 .\" Next line is for Appendix B.4.2.2 case.
  76 or the effective user ID
  77 of the process, or if the effective user ID is that of the super user.
  78 .Pp
  79 The
  80 .Fn setgid
  81 function
  82 sets the real and effective
  83 group IDs and the saved set-group-ID of the current process
  84 to the specified value.
  85 .\" Comment out next block for !_POSIX_SAVED_IDS
  86 .\" The real group ID and the saved set-group-ID are changed only if the
  87 .\" effective user ID is that of the super user.
  88 .\" I.e.
  89 .\" .Fn setgid
  90 .\" function is equal to
  91 .\" .Fn setegid
  92 .\" function if the effective user ID is not that of the super user.
  93 .\" End of block
  94 The
  95 .Fn setgid
  96 function is permitted if the specified ID is equal to the real group ID
  97 .\" Comment out next line for !_POSIX_SAVED_IDS
  98 .\" or the saved set-group-ID
  99 .\" Next line is for Appendix B.4.2.2 case.
 100 or the effective group ID
 101 of the process, or if the effective user ID is that of the super user.
 102 .Pp
 103 The
 104 .Fn seteuid
 105 function
 106 .Pq Fn setegid
 107 sets the effective user ID (group ID) of the
 108 current process.
 109 The effective user ID may be set to the value
 110 of the real user ID or the saved set-user-ID (see
 111 .Xr intro 2
 112 and
 113 .Xr execve 2 ) ;
 114 in this way, the effective user ID of a set-user-ID executable
 115 may be toggled by switching to the real user ID, then re-enabled
 116 by reverting to the set-user-ID value.
 117 Similarly, the effective group ID may be set to the value
 118 of the real group ID or the saved set-group-ID.
 119 .Sh RETURN VALUES
 120 .Rv -std
 121 .Sh ERRORS
 122 The functions will fail if:
 123 .Bl -tag -width Er
 124 .It Bq Er EPERM
 125 The user is not the super user and the ID
 126 specified is not the real, effective ID, or saved ID.
 127 .El
 128 .Sh SEE ALSO
 129 .Xr getgid 2 ,
 130 .Xr getuid 2 ,
 131 .Xr issetugid 2 ,
 132 .Xr setregid 2 ,
 133 .Xr setreuid 2
 134 .Sh STANDARDS
 135 The
 136 .Fn setuid
 137 and
 138 .Fn setgid
 139 functions are compliant with the
 140 .St -p1003.1-90
 141 specification with
 142 .Li _POSIX_SAVED_IDS
 143 .\" Uncomment next line for !_POSIX_SAVED_IDS
 144 not
 145 defined with the permitted extensions from Appendix B.4.2.2.
 146 The
 147 .Fn seteuid
 148 and
 149 .Fn setegid
 150 functions are extensions based on the
 151 .Tn POSIX
 152 concept of
 153 .Li _POSIX_SAVED_IDS ,
 154 and have been proposed for a future revision of the standard.
 155 .Sh HISTORY
 156 A
 157 .Fn setuid
 158 and a
 159 .Fn setgid
 160 function calls appeared in
 161 .At v7 .