DUP3(3)

💅 DUP3(3) — the dup3 glow-up, bestie

okay so real talk, this is the dup3 page from the Library Functions Manual, and honestly? she's iconic. she's dup2's cooler little sister and she will let you pick the descriptor number yourself. no cap. let's get into it 🎀

---

✨ LIBRARY ✨

Standard C Library (libc, -lc). she lives in libc, obviously 💖

---

🌸 SYNOPSIS 🌸

like, here's the vibe, literally copy-paste:

#include <fcntl.h>
#include <unistd.h>

int
dup3(int oldd, int newd, int flags);

three args, no drama. well, mostly no drama, wait for the ERRORS section 🙈

---

🦋 DESCRIPTION 🦋

okay so dup3() duplicates an existing object descriptor, but the whole main character move is that you get to specify the value of the new descriptor. newd. your choice. your moment. periodt ✨

the close-on-exec flag on the new file descriptor? that's determined by the O_CLOEXEC bit in flags. yup, she's listening 👑

the close-on-fork flag on the new file descriptor? determined by the O_CLOFORK bit in flags. very demure, very mindful 💅

the resolve-beneath flag on the new file descriptor is preserved. we don't touch it, we respect it 🫶

if oldd ≠ newd and flags == 0, the behavior is identical to dup2(oldd, newd). same energy, same result, just a different function name fr fr.

⚠️ but if oldd == newd, then dup3() fails — unlike dup2(2). yeah. that's the plot twist. that's the whole thing. dup2 would've been chill about it, dup3 is not. 💀

---

🔥 RETURN VALUES 🔥

the value -1 is returned if an error occurs. and the external variable errno indicates the cause of the error. so if you get -1, check errno, she's telling you what went wrong 💜

---

🎀 ERRORS 🎀

dup3() fails if:

• [EBADF] — the oldd argument is not a valid active descriptor, or the newd argument is negative or exceeds the maximum allowable descriptor number. like, either she doesn't exist or she's out of range, and neither is cute 😭
• [EINVAL] — the oldd argument is equal to the newd argument. yup, the self-dupe situation. we said no 🙈
• [EINVAL] — the flags argument has bits set other than O_CLOEXEC or O_CLOFORK. only those two bits are invited to the party, bestie, everyone else is getting turned away at the door 💅

---

🌈 SEE ALSO 🌈

the whole friend group, go say hi:

accept(2), close(2), dup2(2), fcntl(2), getdtablesize(2), open(2), pipe(2), socket(2), socketpair(2)

---

⭐ STANDARDS ⭐

the dup3() function does not conform to any standard. she's ungovernable. she's free. she answers to no one 🦋 (ngl this is lowkey important info if you care about portability, so like, know that about her)

---

👑 HISTORY 👑

the dup3() function appeared in FreeBSD 10.0. and the O_CLOFORK flag appeared in FreeBSD 15.0. glow-ups take time, okay? 💖

---

okay that's the whole page, you ate that, go duplicate some descriptors responsibly 🍓

sign-off szn: this little masterpiece is from Debian, dated May 17, 2025, and it's the DUP3(3) page. mwah 💋