EXPLAIN_SOCKETPAIR_OR_DIE(3)

💖 explain_socketpair_or_die(3) 💖

okay bestie, gather round, we're doing the libexplain thing. this is from the Library Functions Manual, and it's literally the glow-up your error handling has been begging for ✨

---

🌸 NAME 🌸

explain_socketpair_or_die — create pair of connected sockets and report errors

no cap, that's the whole job description 🫶

---

✨ SYNOPSIS ✨

#include <libexplain/socketpair.h>

void explain_socketpair_or_die(int domain, int type, int protocol, int *sv);

int explain_socketpair_on_error(int domain, int type, int protocol, int *sv);

two functions, one header, zero drama 💅

---

🦋 DESCRIPTION 🦋

so here's the tea. the explain_socketpair_or_die function is used to call the socketpair(2) system call. and if it fails? an explanation gets printed to stderr, which it snags from the explain_socketpair(3) function, and then the process terminates by calling exit(EXIT_FAILURE). it's giving "we don't do silent failures in this house" 💀

meanwhile, the explain_socketpair_on_error function is also used to call the socketpair(2) system call. on failure an explanation will be printed to stderr, again obtained from the explain_socketpair(3) function — but this one still returns to the caller. so it's the chill sibling. no dramatic exit, just a little note and back to business 🌈

🎀 the arguments, bestie

• domain — the domain, exactly as to be passed to the socketpair(2) system call.
• type — the type, exactly as to be passed to the socketpair(2) system call.
• protocol — the protocol, exactly as to be passed to the socketpair(2) system call.
• sv — the sv, exactly as to be passed to the socketpair(2) system call.

see the pattern? exactly as to be passed to the socketpair(2) system call. don't get creative, don't freestyle, just pass it through, periodt 👑

---

💜 RETURN VALUE 💜

the explain_socketpair_or_die function only returns on success — see socketpair(2) for more information. on failure, it prints an explanation and exits, it does not return. so like, if you ever see a line of code after it, just know that line is living on borrowed time 😭

the explain_socketpair_on_error function always returns the value return by the wrapped socketpair(2) system call. (yes, "return by", that's the original's wording, we're keeping it verbatim, don't @ me 🍓)

---

🔥 EXAMPLE 🔥

the explain_socketpair_or_die function is intended to be used in a fashion similar to the following example:

explain_socketpair_or_die(domain, type, protocol, sv);

that's it. that's the whole vibe. one line, and your errors explain themselves 💫

---

🌟 SEE ALSO 🌟

• socketpair(2) — create a pair of connected sockets
• explain_socketpair(3) — explain socketpair(2) errors
• exit(2) — terminate the calling process

---

👑 COPYRIGHT 👑

this whole thing is libexplain version 1.4 and it's Copyright (C) 2010 Peter Miller. respect the icon, they wrote the library that holds your hand through every syscall failure 🫶

---

okay so that's the page, bestie! go forth and let your sockets fail loudly and with receipts. 💅✨

libexplain version 1.4 · Copyright (C) 2010 Peter Miller — mwah, thanks for reading, no cap 🎀🦋