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 setuid ,
  41 .Nm seteuid ,
  42 .Nm setgid ,
  43 .Nm setegid
  44 .Nd set user and group ID
  45 .Sh SYNOPSIS
  46 .Fd #include <sys/types.h>
  47 .Fd #include <unistd.h>
  48 .Ft int
  49 .Fn setuid "uid_t uid"
  50 .Ft int
  51 .Fn seteuid "uid_t euid"
  52 .Ft int
  53 .Fn setgid "gid_t gid"
  54 .Ft int
  55 .Fn setegid "gid_t egid"
  56 .Sh DESCRIPTION
  57 The
  58 .Fn setuid
  59 function
  60 sets the real and effective
  61 user IDs and the saved set-user-ID of the current process
  62 to the specified value.
  63 The
  64 .Fn setuid
  65 function is permitted if the effective user ID is that of the super user,
  66 or if the specified user ID is the same as the effective user ID.  If
  67 not, but the specified user ID is the same as the real user ID,
  68 .Fn setuid
  69 will set the effective user ID to the real user ID.
  70 .Pp
  71 The
  72 .Fn setgid
  73 function
  74 sets the real and effective
  75 group IDs and the saved set-group-ID of the current process
  76 to the specified value.
  77 The
  78 .Fn setgid
  79 function is permitted if the effective user ID is that of the super user,
  80 or if the specified group ID is the same as the effective group ID.  If
  81 not, but the specified group ID is the same as the real group ID,
  82 .Fn setgid
  83 will set the effective group ID to the real group ID.
  84 .Pp
  85 The
  86 .Fn seteuid
  87 function
  88 .Pq Fn setegid
  89 sets the effective user ID (group ID) of the
  90 current process.
  91 The effective user ID may be set to the value
  92 of the real user ID or the saved set-user-ID (see
  93 .Xr intro 2
  94 and
  95 .Xr execve 2 ) ;
  96 in this way, the effective user ID of a set-user-ID executable
  97 may be toggled by switching to the real user ID, then re-enabled
  98 by reverting to the set-user-ID value.
  99 Similarly, the effective group ID may be set to the value
 100 of the real group ID or the saved set-user-ID.
 101 .Pp
 102 .Sh RETURN VALUES
 103 Upon success, these functions return 0;
 104 otherwise \-1 is returned.
 105 .Pp
 106 If the user is not the super user, or the uid
 107 specified is not the real, effective ID, or saved ID,
 108 these functions return \-1.
 109 .Sh SEE ALSO
 110 .Xr getuid 2 ,
 111 .Xr getgid 2
 112 .Sh STANDARDS
 113 The
 114 .Fn setuid
 115 and
 116 .Fn setgid
 117 functions are compliant with the
 118 .St -p1003.1-90
 119 specification with
 120 .Li _POSIX_SAVED_IDS
 121 defined, with the extensions allowed in section B.4.2.2.
 122 The
 123 .Fn seteuid
 124 and
 125 .Fn setegid
 126 functions are extensions based on the
 127 .Tn POSIX
 128 concept of
 129 .Li _POSIX_SAVED_IDS ,
 130 and have been proposed for a future revision of the standard.