lib/libc/sys/setuid.2

   1 .\"     $NetBSD: setuid.2,v 1.22 2010/04/05 07:44:28 wiz 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. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)setuid.2    8.1 (Berkeley) 6/4/93
  31 .\"
  32 .Dd April 3, 2010
  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 unistd.h
  45 .Ft int
  46 .Fn setuid "uid_t uid"
  47 .Ft int
  48 .Fn seteuid "uid_t euid"
  49 .Ft int
  50 .Fn setgid "gid_t gid"
  51 .Ft int
  52 .Fn setegid "gid_t egid"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn setuid
  56 function
  57 sets the real and effective
  58 user IDs and the saved set-user-ID of the current process
  59 to the specified value.
  60 The
  61 .Fn setuid
  62 function is permitted if the specified ID is equal to the real user ID
  63 of the process, or if the effective user ID is that of the super user.
  64 .Pp
  65 The
  66 .Fn setgid
  67 function
  68 sets the real and effective
  69 group IDs and the saved set-group-ID of the current process
  70 to the specified value.
  71 The
  72 .Fn setgid
  73 function is permitted if the specified ID is equal to the real group ID
  74 of the process, or if the effective user ID is that of the super user.
  75 Supplementary group IDs remain unchanged.
  76 .Pp
  77 The
  78 .Fn seteuid
  79 function
  80 .Pq Fn setegid
  81 sets the effective user ID (group ID) of the
  82 current process.
  83 The effective user ID may be set to the value
  84 of the real user ID or the saved set-user-ID (see
  85 .Xr intro 2
  86 and
  87 .Xr execve 2 ) ;
  88 in this way, the effective user ID of a set-user-ID executable
  89 may be toggled by switching to the real user ID, then re-enabled
  90 by reverting to the set-user-ID value.
  91 Similarly, the effective group ID may be set to the value
  92 of the real group ID or the saved set-group-ID.
  93 .Sh RETURN VALUES
  94 Upon success, these functions return 0;
  95 otherwise \-1 is returned.
  96 .Pp
  97 If the user is not the super user, or the uid
  98 specified is not the real, effective ID, or saved ID,
  99 these functions return \-1.
 100 .Sh SEE ALSO
 101 .Xr getgid 2 ,
 102 .Xr getgroups 2 ,
 103 .Xr getuid 2
 104 .Sh STANDARDS
 105 The
 106 .Fn setuid
 107 and
 108 .Fn setgid
 109 functions are compliant with the
 110 .St -p1003.1-90
 111 specification with
 112 .Li _POSIX_SAVED_IDS
 113 not defined.
 114 We do not implement the
 115 .Li _POSIX_SAVED_IDS
 116 option as specified in the standard
 117 because this would make it impossible for a set-user-ID executable owned
 118 by a user other than the super-user to permanently revoke its privileges.
 119 .Pp
 120 The
 121 .Fn seteuid
 122 and
 123 .Fn setegid
 124 functions are compliant with
 125 .St -p1003.1-2001 .
 126 .Sh HISTORY
 127 The
 128 .Fn setuid
 129 and
 130 .Fn setgid
 131 functions appeared in
 132 .At v2
 133 and
 134 .At v4 ,
 135 respectively.