getpeereid(3bsd)

💖 getpeereid — the libbsd glow-up ✨

okay bestie, so you know how Unix-domain sockets are like. a whole thing? well getpeereid is the function from 3bsd that lets you peek at who's actually on the other end. it's giving "who dis" but for sockets, and it's reliable. no cap.

---

📚 LIBRARY

Utility functions from BSD systems — that's libbsd, and you link it with -lbsd. yes queen, add the flag. 🎀

---

✨ SYNOPSIS ✨

#include <sys/types.h>
#include <unistd.h>
(See libbsd(7) for include usage.)

int
getpeereid(int s, uid_t *euid, gid_t *egid);

💡 friendly reminder: check libbsd(7) for how the include situation works, it's got the deets.

---

🦋 DESCRIPTION 🦋

so. getpeereid() hands you the effective user ID and the effective group ID of the peer that's connected to a Unix-domain socket. literally just. the credentials. of your socket bestie.

the argument s has to be a Unix-domain socket (unix(4)) of type SOCK_STREAM — and like, connect(2) or listen(2) must have already been called on it. no skipping steps babe. ✋

the effective user ID lands in euid, and the effective group ID lands in egid. cute little out-params. 🫶

now here's the part that's actually iconic:

• if you're the listen(2) caller, the credentials you get back are your peer's credentials at the time it called connect(2).
• if you're the connect(2) caller, the credentials you get back are your peer's credentials at the time it called listen(2).

and the way this is reliable?? there is genuinely no way for either side to influence the credentials returned to its peer — the only way to change them is to call the appropriate system call (so, either connect(2) or listen(2)) under different effective credentials. that's it. that's the whole loophole. there isn't one. 💅

one super common use of this routine is a Unix-domain server verifying the credentials of its client. and likewise? the client can verify the credentials of the server. mutual verification. it's giving healthy relationship. 💖

---

🔧 IMPLEMENTATION NOTES 🔧

on FreeBSD, getpeereid() is implemented in terms of the LOCAL_PEERCRED unix(4) socket option. so that's the tea. ☕

---

🎀 RETURN VALUES 🎀

• getpeereid() returns the value 0 when it's successful. slay. ✅
• otherwise it returns the value -1, and the global variable errno gets set to indicate the error. 😭

---

💀 ERRORS 💀

getpeereid() fails if:

• [EBADF] — the argument s is not a valid descriptor. bestie that's not even a real fd. 🙈
• [ENOTSOCK] — the argument s is a file, not a socket. wrong vibe entirely, it's giving regular file energy. 📄
• [ENOTCONN] — the argument s does not refer to a socket on which connect(2) or listen(2) have been called. you gotta commit first, babe. 💅
• [EINVAL] — the argument s does not refer to a socket of type SOCK_STREAM, or the kernel returned invalid data. either wrong socket type or the kernel is being weird, and honestly both are a moment. 😭

---

👀 SEE ALSO 👀

connect(2), getpeername(2), getsockname(2), getsockopt(2), listen(2), unix(4)

like. go read them. iykyk. 📖✨

---

🌸 HISTORY 🌸

getpeereid() appeared in FreeBSD 4.6, NetBSD 5.0 and OpenBSD 3.0. a whole trilogy. main character energy across three BSDs. 👑

---

and that's the page bestie!! 🎉 this little beauty came out of Debian, dated July 15, 2001 — yes it's older than you, it's a vintage icon and it still ate. 💅✨🦋