xref: /openbsd-src/lib/libc/sys/setuid.2 (revision e86f66765aba9d9b2f3ef1ce9530962cafe73b71)
1.\"	$OpenBSD: setuid.2,v 1.23 2014/09/09 08:16:12 jmc Exp $
2.\"	$NetBSD: setuid.2,v 1.3 1995/02/27 12:37:06 cgd Exp $
3.\"
4.\" Copyright (c) 1983, 1991, 1993
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"     @(#)setuid.2	8.1 (Berkeley) 6/4/93
32.\"
33.Dd $Mdocdate: September 9 2014 $
34.Dt SETUID 2
35.Os
36.Sh NAME
37.Nm setuid ,
38.Nm seteuid ,
39.Nm setgid ,
40.Nm setegid
41.Nd set user and group ID
42.Sh SYNOPSIS
43.In unistd.h
44.Ft int
45.Fn setuid "uid_t uid"
46.Ft int
47.Fn seteuid "uid_t euid"
48.Ft int
49.Fn setgid "gid_t gid"
50.Ft int
51.Fn setegid "gid_t egid"
52.Sh DESCRIPTION
53The
54.Fn setuid
55function sets the real and effective user IDs and the saved set-user-ID
56of the current process to the specified value.
57The
58.Fn setuid
59function is permitted if the effective user ID is that of the superuser,
60or if the specified user ID is the same as the effective user ID.
61If not, but the specified user ID is the same as the real user ID,
62.Fn setuid
63will set the effective user ID to the real user ID.
64.Pp
65The
66.Fn setgid
67function sets the real and effective group IDs and the saved set-group-ID
68of the current process to the specified value.
69The
70.Fn setgid
71function is permitted if the effective user ID is that of the superuser,
72or if the specified group ID is the same as the effective group ID.
73If not, but the specified group ID is the same as the real group ID,
74.Fn setgid
75will set the effective group ID to the real group ID.
76Supplementary group IDs remain unchanged.
77.Pp
78The
79.Fn seteuid
80function
81.Pq Fn setegid
82sets the effective user ID (group ID) of the current process.
83The effective user ID may be set to the value
84of the real user ID or the saved set-user-ID (see
85.Xr intro 2
86and
87.Xr execve 2 ) ;
88in this way, the effective user ID of a set-user-ID executable
89may be toggled by switching to the real user ID, then re-enabled
90by reverting to the set-user-ID value.
91Similarly, the effective group ID may be set to the value
92of the real group ID or the saved set-group-ID.
93.Sh RETURN VALUES
94.Rv -std setuid seteuid setgid setegid
95.Sh ERRORS
96.Fn setuid
97and
98.Fn seteuid
99will succeed unless:
100.Bl -tag -width Er
101.It Bq Er EPERM
102The user is not the superuser and the requested
103.Fa uid
104or
105.Fa euid
106is not the process's real, effective, or saved UID.
107.El
108.Pp
109.Fn setgid
110and
111.Fn setegid
112will succeed unless:
113.Bl -tag -width Er
114.It Bq Er EPERM
115The user is not the superuser and the requested
116.Fa gid
117or
118.Fa egid
119is not the process's real, effective, or saved GID.
120.El
121.Sh SEE ALSO
122.Xr getgid 2 ,
123.Xr getuid 2 ,
124.Xr issetugid 2 ,
125.Xr setgroups 2 ,
126.Xr setregid 2 ,
127.Xr setresgid 2 ,
128.Xr setresuid 2 ,
129.Xr setreuid 2
130.Sh STANDARDS
131The
132.Fn setuid ,
133.Fn seteuid ,
134.Fn setgid ,
135and
136.Fn setegid
137functions conform to
138.St -p1003.1-2008 .
139.Sh HISTORY
140The
141.Fn setuid
142system call first appeared in
143.At v1 ;
144.Fn setgid
145in
146.At v4 ;
147and
148.Fn seteuid
149and
150.Fn setegid
151in
152.Bx 4.2 .
153