setuid(2)

💖 setuid — set user identity 💖

okay bestie, welcome to the setuid(2) page, part of the System Calls Manual, and honestly? this one's a banger. it's the syscall that changes who you are. main character energy fr.

---

✨ NAME ✨

setuid — set user identity

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🫶 SYNOPSIS 🫶

#include <unistd.h>

int setuid(uid_t uid);

---

🌸 DESCRIPTION 🌸

so setuid() sets the effective user ID of the calling process. that's the one that decides what you're allowed to do, lowkey the important one.

if the calling process is privileged — and bestie, "privileged" here means, more precisely, the process has the CAP_SETUID capability in its user namespace — then the real UID and the saved set-user-ID get set too. all three. the whole glow-up. ✨

under Linux, setuid() is implemented like the POSIX version with the _POSIX_SAVED_IDS feature. what that buys you: a set-user-ID program (that isn't root) can drop all of its user privileges, go do some un-privileged work, and then reengage the original effective user ID in a secure manner. like taking off your heels, doing the errand, then putting them back on. iconic.

⚠️ but listen. if the user is root, or the program is set-user-ID-root, you must take special care. setuid() checks the effective user ID of the caller, and if that's the superuser, then all process-related user IDs get set to uid. and after that has happened? it is impossible for the program to regain root privileges. no takebacks. none. 💀

so, a set-user-ID-root program that wants to temporarily drop root privileges, assume the identity of an unprivileged user, and then regain root privileges afterward cannot use setuid(). it just can't, bestie. that's not the vibe. what you can do is accomplish this with seteuid(2). go see her. 👑

---

🎀 RETURN VALUE 🎀

• on success: zero is returned 🥳
• on error: -1 is returned, and errno is set to indicate the error

⚠️ note note note: there are cases where setuid() can fail even when the caller is UID 0. and it is a grave security error to omit checking for a failure return from setuid(). like, do not skip the check. that's the whole ballgame. 🙈

---

💀 ERRORS 💀

• EAGAIN — the call would change the caller's real UID (i.e., uid does not match the caller's real UID), but there was a temporary failure allocating the necessary kernel data structures.
• EAGAIN — uid does not match the real user ID of the caller and this call would bring the number of processes belonging to the real user ID uid over the caller's RLIMIT_NPROC resource limit. since Linux 3.1 this error case no longer occurs — but robust applications should still check for this error; see the description of EAGAIN in execve(2).
• EINVAL — the user ID specified in uid is not valid in this user namespace.
• EPERM — the user is not privileged (on Linux: does not have the CAP_SETUID capability in its user namespace) and uid does not match the real UID or saved set-user-ID of the calling process.

---

🦋 VERSIONS 🦋

🧚 C library/kernel differences 🧚

at the kernel level, user IDs and group IDs are a per-thread attribute. but POSIX requires that all threads in a process share the same credentials. so the NPTL threading implementation handles the POSIX requirements by providing wrapper functions for the various system calls that change process UIDs and GIDs.

these wrapper functions (including the one for setuid()) employ a signal-based technique to ensure that when one thread changes credentials, all of the other threads in the process also change their credentials. group project where everyone actually participates, imagine. 😭

for details, see nptl(7).

---

⭐ STANDARDS ⭐

POSIX.1-2024.

---

🌈 HISTORY 🌈

POSIX.1-2001, SVr4.

not quite compatible with the 4.4BSD call, which sets all of the real, saved, and effective user IDs.

the original Linux setuid() system call supported only 16-bit user IDs. subsequently, Linux 2.4 added setuid32() supporting 32-bit IDs. the glibc setuid() wrapper function transparently deals with the variation across kernel versions — she handles it, you don't have to. 💅

---

👑 NOTES 👑

Linux has the concept of the filesystem user ID, normally equal to the effective user ID. the setuid() call also sets the filesystem user ID of the calling process. see setfsuid(2).

if uid is different from the old effective UID, the process will be forbidden from leaving core dumps. so no crash souvenirs for you. 🍓

---

🔥 SEE ALSO 🔥

getuid(2), seteuid(2), setfsuid(2), setreuid(2), capabilities(7), credentials(7), user_namespaces(7)

---

and that's the page bestie, no cap. this was Linux man-pages 6.20, dated 2026-02-08, bringing you setuid(2) — go change your identity (legally, via syscall) and slay responsibly. 💜✨