Debian Codegraph @

upstream/debian-unstable/man2/setuid.2

raw
1 .\" Copyright 1994, Graeme W. Wilford <[email protected]>
2 .\" Copyright 2010-2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH setuid 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 setuid \- set user identity
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BI "int setuid(uid_t " uid );
18 .fi
19 .SH DESCRIPTION
20 .BR setuid ()
21 sets the effective user ID of the calling process.
22 If the calling process is privileged
23 (more precisely: if the process has the
24 .B CAP_SETUID
25 capability in its user namespace),
26 the real UID and saved set-user-ID are also set.
27 .P
28 Under Linux,
29 .BR setuid ()
30 is implemented like the POSIX version with the
31 .B _POSIX_SAVED_IDS
32 feature.
33 This allows a set-user-ID (other than root) program to drop all of its user
34 privileges, do some un-privileged work, and then reengage the original
35 effective user ID in a secure manner.
36 .P
37 If the user is root or the program is set-user-ID-root, special care must be
38 taken:
39 .BR setuid ()
40 checks the effective user ID of the caller and if it is
41 the superuser, all process-related user ID's are set to
42 .IR uid .
43 After this has occurred, it is impossible for the program to regain root
44 privileges.
45 .P
46 Thus, a set-user-ID-root program wishing to temporarily drop root
47 privileges, assume the identity of an unprivileged user, and then regain
48 root privileges afterward cannot use
49 .BR setuid ().
50 You can accomplish this with
51 .BR seteuid (2).
52 .SH RETURN VALUE
53 On success, zero is returned.
54 On error, \-1 is returned, and
55 .I errno
56 is set to indicate the error.
57 .P
58 .IR Note :
59 there are cases where
60 .BR setuid ()
61 can fail even when the caller is UID 0;
62 it is a grave security error to omit checking for a failure return from
63 .BR setuid ().
64 .SH ERRORS
65 .TP
66 .B EAGAIN
67 The call would change the caller's real UID (i.e.,
68 .I uid
69 does not match the caller's real UID),
70 but there was a temporary failure allocating the
71 necessary kernel data structures.
72 .TP
73 .B EAGAIN
74 .I uid
75 does not match the real user ID of the caller and this call would
76 bring the number of processes belonging to the real user ID
77 .I uid
78 over the caller's
79 .B RLIMIT_NPROC
80 resource limit.
81 Since Linux 3.1, this error case no longer occurs
82 (but robust applications should check for this error);
83 see the description of
84 .B EAGAIN
85 in
86 .BR execve (2).
87 .TP
88 .B EINVAL
89 The user ID specified in
90 .I uid
91 is not valid in this user namespace.
92 .TP
93 .B EPERM
94 The user is not privileged (Linux: does not have the
95 .B CAP_SETUID
96 capability in its user namespace) and
97 .I uid
98 does not match the real UID or saved set-user-ID of the calling process.
99 .SH VERSIONS
100 .SS C library/kernel differences
101 At the kernel level, user IDs and group IDs are a per-thread attribute.
102 However, POSIX requires that all threads in a process
103 share the same credentials.
104 The NPTL threading implementation handles the POSIX requirements by
105 providing wrapper functions for
106 the various system calls that change process UIDs and GIDs.
107 These wrapper functions (including the one for
108 .BR setuid ())
109 employ a signal-based technique to ensure
110 that when one thread changes credentials,
111 all of the other threads in the process also change their credentials.
112 For details, see
113 .BR nptl (7).
114 .SH STANDARDS
115 POSIX.1-2024.
116 .SH HISTORY
117 POSIX.1-2001, SVr4.
118 .P
119 Not quite compatible with the 4.4BSD call, which
120 sets all of the real, saved, and effective user IDs.
121 .\" SVr4 documents an additional EINVAL error condition.
122 .P
123 The original Linux
124 .BR setuid ()
125 system call supported only 16-bit user IDs.
126 Subsequently, Linux 2.4 added
127 .BR setuid32 ()
128 supporting 32-bit IDs.
129 The glibc
130 .BR setuid ()
131 wrapper function transparently deals with the variation across kernel versions.
132 .SH NOTES
133 Linux has the concept of the filesystem user ID, normally equal to the
134 effective user ID.
135 The
136 .BR setuid ()
137 call also sets the filesystem user ID of the calling process.
138 See
139 .BR setfsuid (2).
140 .P
141 If
142 .I uid
143 is different from the old effective UID, the process will
144 be forbidden from leaving core dumps.
145 .SH SEE ALSO
146 .BR getuid (2),
147 .BR seteuid (2),
148 .BR setfsuid (2),
149 .BR setreuid (2),
150 .BR capabilities (7),
151 .BR credentials (7),
152 .BR user_namespaces (7)