explain_socket(3)

💖 explain_socket(3) 💖

Library Functions Manual ✨ okay so bestie, this is a whole page about a little family of functions called explain_socket, and they are genuinely so iconic. If socket(2) ever ghosts you and hands back an error, these are the girlies you call to find out why. Let's get into it 💅

---

🌸 NAME 🌸

explain_socket — explain socket(2) errors

---

🎀 SYNOPSIS 🎀

#include <libexplain/socket.h>
const char *explain_socket(int domain, int type, int protocol);
const char *explain_errno_socket(int errnum, int domain, int type, int protocol);
void explain_message_socket(char *message, int message_size, int domain, int type, int protocol);
void explain_message_errno_socket(char *message, int message_size, int errnum, int domain, int type, int protocol);

---

✨ DESCRIPTION ✨

So these four functions? They're your support system 💖 You use them to get actual explanations for errors that the socket(2) system call hands back. No more cryptic nonsense, no more "it didn't work and I don't know why" energy. We're getting answers.

---

🦋 explain_socket

const char *explain_socket(int domain, int type, int protocol);

The explain_socket function gets you an explanation of an error returned by the socket(2) system call. The bare minimum the message will contain is the value of strerror(errno), but honestly? Usually it does so much better than that, and it'll point at the actual underlying cause in more detail. It's giving detective 🔍

The errno global variable is what gets used to obtain the error value that needs decoding.

This function is meant to be used in a fashion similar to this example, bestie:

if (socket(domain, type, protocol) < 0)
{
    fprintf(stderr, "%s\n", explain_socket(domain, type, protocol));
    exit(EXIT_FAILURE);
}

• domain — the original domain, exactly as passed to the socket(2) system call. No substitutions, no edits 💅
• type — the original type, exactly as passed to the socket(2) system call.
• protocol — the original protocol, exactly as passed to the socket(2) system call.

Returns: The message explaining the error. Heads up though: this message buffer is shared by all libexplain functions that don't supply a buffer in their own argument list. So it will get overwritten by the very next call to any libexplain function that shares this buffer — including calls from other threads. Rude, but that's the deal 😭

Note: This function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library do too. Periodt.

---

🧚 explain_errno_socket

const char *explain_errno_socket(int errnum, int domain, int type, int protocol);

The explain_errno_socket function gets you an explanation of an error returned by the socket(2) system call. Least it'll give you is the value of strerror(errnum), but usually it goes way harder and tells you the underlying cause in more detail ✨

This function is meant to be used in a fashion similar to this example:

if (socket(domain, type, protocol) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_socket(err,
        domain, type, protocol));
    exit(EXIT_FAILURE);
}

• errnum — the error value to be decoded, usually grabbed from the errno global variable just before this function is called. This is necessary if you need to run any code between the system call you're explaining and this function, because so many libc functions will go and alter the value of errno behind your back. Sneaky fr fr 😤
• domain — the original domain, exactly as passed to the socket(2) system call.
• type — the original type, exactly as passed to the socket(2) system call.
• protocol — the original protocol, exactly as passed to the socket(2) system call.

Returns: The message explaining the error. And again: this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. It'll be overwritten by the next call to any libexplain function sharing this buffer, other threads included 💀

Note: This function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library do the same.

---

🌈 explain_message_socket

void explain_message_socket(char *message, int message_size, int domain, int type, int protocol);

The explain_message_socket function may be used to obtain an explanation of an error returned by the socket(2) system call. Minimum content? The value of strerror(errno). But usually it does much better and points at the underlying cause in more detail 💖

The errno global variable will be used to obtain the error value to be decoded.

This function is meant to be used in a fashion similar to this example:

if (socket(domain, type, protocol) < 0)
{
    char message[3000];
    explain_message_socket(message, sizeof(message), domain, type, protocol);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location in which to store the returned message. And here's the slay: if you supply a suitable message return buffer, this function is thread safe 👑
• message_size — the size in bytes of the location in which to store the returned message.
• domain — the original domain, exactly as passed to the socket(2) system call.
• type — the original type, exactly as passed to the socket(2) system call.
• protocol — the original protocol, exactly as passed to the socket(2) system call.

---

🫶 explain_message_errno_socket

void explain_message_errno_socket(char *message, int message_size, int errnum, int domain, int type, int protocol);

The explain_message_errno_socket function may be used to obtain an explanation of an error returned by the socket(2) system call. Least the message will contain is the value of strerror(errnum), but usually it does much better and shows the underlying cause in more detail 🌟

This function is meant to be used in a fashion similar to this example:

if (socket(domain, type, protocol) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_socket(message, sizeof(message), err,
        domain, type, protocol);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location in which to store the returned message. If you supply a suitable message return buffer, this function is thread safe 💅
• message_size — the size in bytes of the location in which to store the returned message.
• errnum — the error value to be decoded, usually obtained from the errno global variable just before this function is called. Necessary if you need to call any code between the system call to be explained and this function, because many libc functions will alter the value of errno.
• domain — the original domain, exactly as passed to the socket(2) system call.
• type — the original type, exactly as passed to the socket(2) system call.
• protocol — the original protocol, exactly as passed to the socket(2) system call.

---

👑 SEE ALSO 👑

• socket(2) — create an endpoint for communication
• explain_socket_or_die(3) — create an endpoint for communication and report errors

---

💜 COPYRIGHT 💜

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

And that's the whole page, bestie — explain_socket(3), from the Library Functions Manual, signed, sealed, delivered ✨ libexplain version 1.4, Copyright (C) 2008 Peter Miller. Go forth and debug, you absolute icon 💅🦋