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 setegid , 41.Nm seteuid , 42.Nm setgid , 43.Nm setuid 44.Nd set user and group ID 45.Sh SYNOPSIS 46.Fd #include <unistd.h> 47.Ft int 48.Fo setegid 49.Fa "gid_t egid" 50.Fc 51.Ft int 52.Fo seteuid 53.Fa "uid_t euid" 54.Fc 55.Ft int 56.Fo setgid 57.Fa "gid_t gid" 58.Fc 59.Ft int 60.Fo setuid 61.Fa "uid_t uid" 62.Fc 63.Sh DESCRIPTION 64The 65.Fn setuid 66function 67sets the real and effective 68user IDs and the saved set-user-ID of the current process 69to the specified value. 70The 71.Fn setuid 72function is permitted if the effective user ID is that of the super user, 73or if the specified user ID is the same as the effective user ID. If 74not, but the specified user ID is the same as the real user ID, 75.Fn setuid 76will set the effective user ID to the real user ID. 77.Pp 78The 79.Fn setgid 80function 81sets the real and effective 82group IDs and the saved set-group-ID of the current process 83to the specified value. 84The 85.Fn setgid 86function is permitted if the effective user ID is that of the super user, 87or if the specified group ID is the same as the effective group ID. If 88not, but the specified group ID is the same as the real group ID, 89.Fn setgid 90will set the effective group ID to the real group ID. 91.Pp 92The 93.Fn seteuid 94function 95.Pq Fn setegid 96sets the effective user ID (group ID) of the 97current process. 98The effective user ID may be set to the value 99of the real user ID or the saved set-user-ID (see 100.Xr intro 2 101and 102.Xr execve 2 ) ; 103in this way, the effective user ID of a set-user-ID executable 104may be toggled by switching to the real user ID, then re-enabled 105by reverting to the set-user-ID value. 106Similarly, the effective group ID may be set to the value 107of the real group ID or the saved set-group-ID. 108.Pp 109.Sh RETURN VALUES 110Upon success, these functions return 0; 111otherwise \-1 is returned. 112.Pp 113If the user is not the super user, or the uid 114specified is not the real, effective ID, or saved ID, 115these functions return \-1. 116.Pp 117.Sh ERRORS 118The 119.Fn setegid , 120.Fn seteuid , 121.Fn setgid , 122and 123.Fn setuid 124system calls will fail if: 125.Bl -tag -width Er 126.\" =========== 127.It Bq Er EINVAL 128The value of the {group,user} ID argument is invalid 129and is not supported by the implementation. 130.\" =========== 131.It Bq Er EPERM 132The process does not have appropriate privileges and 133the ID argument 134does not match the real ID 135or the saved set-{group,user}-ID. 136.El 137.Sh LEGACY SYNOPSIS 138.Fd #include <sys/types.h> 139.Fd #include <unistd.h> 140.Pp 141The include file 142.In sys/types.h 143is necessary for all functions. 144.Sh SEE ALSO 145.Xr getgid 2 , 146.Xr getuid 2 , 147.Xr compat 5 148.Sh STANDARDS 149The 150.Fn setuid 151and 152.Fn setgid 153functions are compliant with the 154.St -p1003.1-90 155specification with 156.Li _POSIX_SAVED_IDS 157defined, with the extensions allowed in section B.4.2.2. 158The 159.Fn seteuid 160and 161.Fn setegid 162functions are extensions based on the 163.Tn POSIX 164concept of 165.Li _POSIX_SAVED_IDS , 166and have been proposed for a future revision of the standard. 167