SETREUID(3POSIX)

💖 SETREUID(3POSIX) — the POSIX Programmer's Manual, bestie edition 💖

okay so before we even get into it, a lil PROLOG moment, because it matters:

bestie, this page is part of the POSIX Programmer's Manual. the Linux implementation of this interface may differ (so like, go check the matching Linux man page for the Linux deets if that's your situation), or the interface might not even be implemented on Linux at all. 🙈

---

✨ NAME ✨

setreuid — set real and effective user IDs

---

🌸 SYNOPSIS 🌸

#include <unistd.h>

int setreuid(uid_t ruid, uid_t euid);

---

🦋 DESCRIPTION 🦋

so setreuid() sets the real and effective user IDs of the current process to the values you hand it in the ruid and euid arguments. that's it, that's the job. 💅

and here's the lil trick: if ruid or euid is -1, the corresponding effective or real user ID of the current process gets left unchanged. like, "no notes, don't touch that one."

a process with appropriate privileges can set either ID to literally any value. main character energy. 👑

but an unprivileged process? it can only set the effective user ID if the euid argument is equal to either the real, effective, or saved user ID of the process. that's the whole guest list, no plus-ones. 🎀

if the real user ID is being set (ruid is not -1), or the effective user ID is being set to a value not equal to the real user ID, then the saved set-user-ID of the current process shall be set equal to the new effective user ID. slay, it cascades.

⚠️ and this one's important, so pay attention: it is unspecified whether a process without appropriate privileges is permitted to change the real user ID to match the current effective user ID or saved set-user-ID of the process. unspecified means don't build your whole personality around it. 😭

---

🌈 RETURN VALUE 🌈

• upon successful completion, 0 shall be returned. periodt. ✨
• otherwise, -1 shall be returned and errno gets set to indicate the error. 💀

---

💜 ERRORS 💜

the setreuid() function shall fail if:

• EINVAL — the value of the ruid or euid argument is invalid or out-of-range. like girl, that number is not it. 🚫
• EPERM — the current process does not have appropriate privileges, and either an attempt was made to change the effective user ID to a value other than the real user ID or the saved set-user-ID, or an attempt was made to change the real user ID to a value not permitted by the implementation. no privileges, no vibes, no entry. 🙅

the following sections are informative. (yes bestie, informative. they're the commentary track, not the movie.) 🍓

---

🎀 EXAMPLES 🎀

Setting the Effective User ID to the Real User ID

this example sets the effective user ID of the calling process to the real user ID, so that files created later will be owned by the current user. it also sets the saved set-user-ID to the real user ID, so any future attempt to set the effective user ID back to its previous value will fail. iconic, honestly — it locks the door behind itself. 🔒

#include <unistd.h>
#include <sys/types.h>
...
setreuid(getuid(), getuid());
...

---

🧚 APPLICATION USAGE 🧚

None.

that's it. that's the section. nothing. empty. a vibe check with no vibes. 💀

---

⭐ RATIONALE ⭐

earlier versions of this standard did not specify whether the saved set-user-ID was affected by setreuid() calls. this version specifies common existing practice that constitutes an important security feature. ✨

the ability to set both the effective user ID and saved set-user-ID to be the same as the real user ID means that any security weakness in code that is executed after that point cannot result in malicious code being executed with the previous effective user ID. like, that's a whole security glow-up. 🫶

privileged applications could already do this using just setuid(), but for non-privileged applications the only standard method available is to use this feature of setreuid(). the way that non-privileged apps finally got a standard way to do it… obsessed. 🔥

---

🌸 FUTURE DIRECTIONS 🌸

None.

(nothing coming, bestie. the future is quiet.) 🦋

---

👑 SEE ALSO 👑

• getegid()
• geteuid()
• getgid()
• getuid()
• setegid()
• seteuid()
• setgid()
• setregid()
• setuid()

the Base Definitions volume of POSIX.1‐2017, <unistd.h>

---

📜 COPYRIGHT 📜

portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. in the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. the original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. to report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

okay that's the whole page bestie, love that for us 💖 this was brought to you by IEEE/The Open Group, dated 2017 — SETREUID(3POSIX), out. mwah. 💅🎀