explain_access(3)

🌸 NAME 🌸

explain_access — bestie, this whole page is about explaining the errors that come back from the access(2) system call. That's the entire vibe. 💅

And hi, yes, this is the explain_access(3) page from the Library Functions Manual, and we are reading it together, all of it, no skipping. 🫶

---

✨ SYNOPSIS ✨

#include <libexplain/access.h>
const char *explain_access(const char *pathname, int mode);
const char *explain_errno_access(int errnum, const char *pathname, int mode);
void explain_message_access(char *message, int message_size, const char *pathname, int mode);
void explain_message_errno_access(char *message, int message_size, int errnum, const char *pathname, int mode);

---

💖 DESCRIPTION 💖

So these four functions? They're how you get explanations for access(2) errors. Four of them. Each one is slightly different and the differences genuinely matter, so we're doing them one at a time. 🧚

🌟 explain_access 🌟

const char *explain_access(const char *pathname, int mode);

The explain_access function is how you get an explanation of an error returned by the access(2) system call. The least your message is gonna contain is the value of strerror(errno) — but usually it does way better than that and points at the actual underlying cause in way more detail. Obsessed with that, honestly.

It reads the errno global variable to get the error value it's decoding.

It's meant to be used in a fashion similar to this example, fr fr:

int fd = access(pathname, mode);
if (fd < 0)
{
    fprintf(stderr, "%s0, explain_access(pathname, mode));
    exit(EXIT_FAILURE);
}

• pathname — the original pathname, exactly as passed to the access(2) system call. No edits, no glow-up.
• mode — the original mode, exactly as passed to the access(2) system call. Same energy.

Returns: the message explaining the error. ⚠️ But heads up — this message buffer is shared by all the libexplain functions that don't supply a buffer in their own argument list. So the very next call to any libexplain function that shares this buffer will overwrite it, other threads included. 😭

Note: this function is not thread safe, because it shares a return buffer across all threads — and honestly, a lot of other functions in this library do the exact same thing.

---

🌟 explain_errno_access 🌟

const char *explain_errno_access(int errnum, const char *pathname, int mode);

The explain_errno_access function is how you get an explanation of an error returned by the access(2) system call. The least your message is gonna contain is the value of strerror(errnum) — but usually it does much better and shows you the underlying cause in more detail. 💖

It's meant to be used in a fashion similar to this example:

int fd = access(pathname, mode);
if (fd < 0)
{
    int err = errno;
    fprintf(stderr, "%s0, explain_errno_access(err, pathname, mode));
    exit(EXIT_FAILURE);
}

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before you call this function. And you do need to do that if you're gonna run any code between the system call you're explaining and this function, because so many libc functions will mess with the value of errno. Not a vibe. 🙈
• pathname — the original pathname, exactly as passed to the access(2) system call.
• mode — the original mode, exactly as passed to the access(2) system call.

Returns: the message explaining the error. Again — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. The next call to any libexplain function sharing this buffer overwrites it, other threads included. 💀

Note: this function is not thread safe, because it shares a return buffer across all threads — plus many other functions in this library.

---

🌟 explain_message_access 🌟

void explain_message_access(char *message, int message_size, const char *pathname, int mode);

The explain_message_access function is how you get an explanation of an error returned by the access(2) system call. The least your message is gonna contain is the value of strerror(errno) — but usually it does much better and tells you the underlying cause in more detail. ✨

The errno global variable is used to obtain the error value being decoded.

It's meant to be used in a fashion similar to this example:

int fd = access(pathname, mode);
if (fd < 0)
{
    char message[3000];
    explain_message_access(message, sizeof(message), pathname, mode);
    fprintf(stderr, "%s0, message);
    exit(EXIT_FAILURE);
}

• message — where you want the returned message stored. And because you supplied the message return buffer, this function is thread safe. Slay. 🎀
• message_size — the size in bytes of the location where the returned message goes.
• pathname — the original pathname, exactly as passed to the access(2) system call.
• mode — the original mode, exactly as passed to the access(2) system call.

---

🌟 explain_message_errno_access 🌟

void explain_message_errno_access(char *message, int message_size, int errnum, const char *pathname, int mode);

The explain_message_errno_access function is how you get an explanation of an error returned by the access(2) system call. The least your message is gonna contain is the value of strerror(errnum) — but usually it does much better and shows the underlying cause in more detail. 🔥

It's meant to be used in a fashion similar to this example:

int fd = access(pathname, mode);
if (fd < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_access(message, sizeof(message), err, pathname, mode);
    fprintf(stderr, "%s0, message);
    exit(EXIT_FAILURE);
}

• message — where you want the returned message stored. Because a message return buffer has been supplied, this function is thread safe. Periodt. 👑
• message_size — the size in bytes of the location where the returned message goes.
• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. Necessary if you need to call any code between the system call being explained and this function, because lots of libc functions will alter the value of errno. 😤
• pathname — the original pathname, exactly as passed to the access(2) system call.
• mode — the original mode, exactly as passed to the access(2) system call.

---

👑 COPYRIGHT 👑

• libexplain version 1.4
• Copyright (C) 2008 Peter Miller

---

🎀 AUTHOR 🎀

Written by Peter Miller <pmiller@opensource.org.au>

---

And that's the whole explain_access(3) page from the Library Functions Manual, top to bottom, every last crumb. 🍓 Go explain your errors, bestie, you've got this 💜