usr/src/man/man2/setuid.2

   1 '\" te
   2 .\"  Copyright 1989 AT&T.  Copyright (c) 2003,Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SETUID 2 "Jan 20, 2003"
   7 .SH NAME
   8 setuid, setegid, seteuid, setgid \- set user and group IDs
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/types.h>
  13 #include <unistd.h>
  14
  15 \fBint\fR \fBsetuid\fR(\fBuid_t\fR \fIuid\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBsetgid\fR(\fBgid_t\fR \fIgid\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBseteuid\fR(\fBuid_t\fR \fIeuid\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBsetegid\fR(\fBgid_t\fR \fIegid\fR);
  31 .fi
  32
  33 .SH DESCRIPTION
  34 .sp
  35 .LP
  36 The \fBsetuid()\fR function sets the real user ID, effective user ID, and saved
  37 user ID of the calling process. The \fBsetgid()\fR function sets the real group
  38 ID, effective group ID, and saved group ID of the calling process. The
  39 \fBsetegid()\fR and \fBseteuid()\fR functions set the effective group and user
  40 IDs respectively for the calling process. See \fBIntro\fR(2) for more
  41 information on real, effective, and saved user and group IDs.
  42 .sp
  43 .LP
  44 At login time, the real user ID, effective user ID, and saved user ID of the
  45 login process are set to the login ID of the user responsible for the creation
  46 of the process. The same is true for the real, effective, and saved group IDs;
  47 they are set to the group ID of the user responsible for the creation of the
  48 process.
  49 .sp
  50 .LP
  51 When a process calls one of the \fBexec\fR(2) family of functions to execute a
  52 file (program), the user and/or group identifiers associated with the process
  53 can change. If the file executed is a set-user-ID file, the effective and saved
  54 user IDs of the process are set to the owner of the file executed. If the file
  55 executed is a set-group-ID file, the effective and saved group IDs of the
  56 process are set to the group of the file executed. If the file executed is not
  57 a set-user-ID or set-group-ID file, the effective user \fBID\fR, saved user ID,
  58 effective group ID, and saved group ID are not changed.
  59 .sp
  60 .LP
  61 If the {\fBPRIV_PROC_SETID\fR} privilege is asserted in the effective set of
  62 the process calling \fBsetuid()\fR, the real, effective, and saved user IDs are
  63 set to the \fIuid\fR argument.  If the \fIuid\fR argument is 0 and none of the
  64 saved, effective or real UID is 0, additional restrictions apply. See
  65 \fBprivileges\fR(5).
  66 .sp
  67 .LP
  68 If the {\fBPRIV_PROC_SETID\fR} privilege is not asserted in the effective set,
  69 but \fIuid\fR is either the real user ID or the saved user ID of the calling
  70 process, the effective user ID is set to \fIuid\fR.
  71 .sp
  72 .LP
  73 If the {\fBPRIV_PROC_SETID\fR} privilege is asserted in the effective set of
  74 the process calling \fBsetgid()\fR, the real, effective, and saved group IDs
  75 are set to the \fIgid\fR argument.
  76 .sp
  77 .LP
  78 If the {\fBPRIV_PROC_SETID\fR} privilege is not asserted in the effective set,
  79 but \fIgid\fR is either the real group ID or the saved group ID of the calling
  80 process, the effective group ID is set to \fIgid\fR.
  81 .SH RETURN VALUES
  82 .sp
  83 .LP
  84 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
  85 returned and \fBerrno\fR is set to indicate the error.
  86 .SH ERRORS
  87 .sp
  88 .LP
  89 The \fBsetuid()\fR and \fBsetgid()\fR functions will fail if:
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBEINVAL\fR\fR
  94 .ad
  95 .RS 10n
  96 The value of \fIuid\fR or \fIgid\fR is out of range.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBEPERM\fR\fR
 103 .ad
 104 .RS 10n
 105 For \fBsetuid()\fR and \fBseteuid()\fR, the {\fBPRIV_PROC_SETID\fR} privilege
 106 is not asserted in the effective set of the calling process and the \fIuid\fR
 107 argument does not match either the real or saved user IDs, or an attempt is
 108 made to change to UID 0 and none of the existing UIDs is 0, in which case
 109 additional privileges are required.
 110 .sp
 111 For \fBsetgid()\fR and \fBsetegid()\fR, the {\fBPRIV_PROC_SETID\fR} privilege
 112 is not asserted in the effective set and the \fIgid\fR argument does not match
 113 either the real or saved group IDs.
 114 .RE
 115
 116 .SH ATTRIBUTES
 117 .sp
 118 .LP
 119 See \fBattributes\fR(5) for descriptions of the following attributes:
 120 .sp
 121
 122 .sp
 123 .TS
 124 box;
 125 c | c
 126 l | l .
 127 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 128 _
 129 Interface Stability     Standard
 130 _
 131 MT-Level        Async-Signal-Safe
 132 .TE
 133
 134 .SH SEE ALSO
 135 .sp
 136 .LP
 137 \fBIntro\fR(2), \fBexec\fR(2), \fBgetgroups\fR(2), \fBgetuid\fR(2),
 138 \fBstat.h\fR(3HEAD), \fBattributes\fR(5), \fBprivileges\fR(5),
 139 \fBstandards\fR(5)