explain_readdir(3)

💖 explain_readdir(3) 💖

okay bestie, gather round, because this is the libexplain page for explain_readdir, and it lives in the Library Functions Manual section 3. it's giving "my system call broke and i need someone to explain what happened in a full sentence instead of just a cryptic number" energy. iconic, honestly.

---

✨ NAME ✨

explain_readdir — explain readdir(2) errors 🫶

---

🌸 SYNOPSIS 🌸

#include <libexplain/readdir.h>
const char *explain_readdir(DIR *dir);
const char *explain_errno_readdir(int errnum, DIR *dir);
void explain_message_readdir(char *message, int message_size, DIR *dir);
void explain_message_errno_readdir(char *message, int message_size, int
errnum, DIR *dir);

---

🦋 DESCRIPTION 🦋

so like, these functions? they're your little translators. you use them to get explanations for errors that the readdir(2) system call hands back to you. no more squinting at a bare error code wondering what it's trying to tell you. 💅

👑 explain_readdir

const char *explain_readdir(DIR *dir);

the explain_readdir function gets you an explanation of an error returned by the readdir(2) system call. the absolute least the message will contain is the value of strerror(errno), but usually it does much better than that and tells you the underlying cause in way more detail. lowkey overachiever. 💖

the errno global variable is what it uses to grab the error value it's gonna decode.

this function is meant to be used kinda like this, bestie:

errno = 0;
struct dirent *dep = readdir(dir);
if (!dep && errno != 0)
{
    fprintf(stderr, "%s\n", explain_readdir(dir));
    exit(EXIT_FAILURE);
}

• dir — the original dir, exactly as passed to the readdir(2) system call. like, don't get creative with it, just pass the same one. 🎀

Returns:

the message explaining the error. and here's the tea ☕ — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. so it will get overwritten by the next call to any libexplain function that shares this buffer, including calls from other threads. it's a communal vibe and it does not respect boundaries. 😭

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. periodt.

🌈 explain_errno_readdir

const char *explain_errno_readdir(int errnum, DIR *dir);

the explain_errno_readdir function gets you an explanation of an error returned by the readdir(2) system call. again, the least the message will contain is the value of strerror(errnum), but usually it does way better and shows you the underlying cause in more detail. ✨

this function is meant to be used kinda like this:

errno = 0;
struct dirent *dep = readdir(dir);
int err = errno;
if (!dep && errno != 0)
{
    fprintf(stderr, "%s\n", explain_errno_readdir(err, dir));
    exit(EXIT_FAILURE);
}

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. this one 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 ahead and alter the value of errno behind your back. rude, but that's the situation. 💀
• dir — the original dir, exactly as passed to the readdir(2) system call.

Returns:

the message explaining the error. same deal as before: this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list, and it will be overwritten by the next call to any libexplain function that shares this buffer, other threads included. 🙈

Note: not thread safe. shares a return buffer across all threads, and so do many other functions in this library. it's a whole thing.

🍓 explain_message_readdir

void explain_message_readdir(char *message, int message_size, DIR *dir);

the explain_message_readdir function may be used to obtain an explanation of an error returned by the readdir(2) system call. least the message will contain is the value of strerror(errno), but usually it does much better and points at the underlying cause in more detail. chef's kiss. 👑

the errno global variable is what it uses to get the error value it's decoding.

use it kinda like this:

errno = 0;
struct dirent *dep = readdir(dir);
if (!dep && errno != 0)
{
    char message[3000];
    explain_message_readdir(message, sizeof(message), dir);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location in which to store the returned message. and bestie, if you supply a suitable message return buffer, this function is thread safe. slay. 💖
• message_size — the size in bytes of the location in which to store the returned message.
• dir — the original dir, exactly as passed to the readdir(2) system call.

🧚 explain_message_errno_readdir

void explain_message_errno_readdir(char *message, int message_size, int
errnum, DIR *dir);

the explain_message_errno_readdir function may be used to obtain an explanation of an error returned by the readdir(2) system call. the least the message will contain is the value of strerror(errnum), but usually it does much better and indicates the underlying cause in more detail. main character behavior fr fr. 🌟

use it kinda like this:

errno = 0;
struct dirent *dep = readdir(dir);
int err = errno;
if (!dep && errno != 0)
{
    char message[3000];
    explain_message_errno_readdir(message, sizeof(message), err, dir);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location in which to store the returned message. if a suitable message return buffer is supplied, 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. this is 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. (say it with me: libc has no chill.)
• dir — the original dir, exactly as passed to the readdir(2) system call.

---

💜 SEE ALSO 💜

• readdir(2) — read directory entry 📁
• explain_readdir_or_die(3) — read directory entry and report errors 💀

---

🎀 COPYRIGHT 🎀

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

and that's the whole page, bestie!! 💅✨ go forth and let libexplain narrate your readdir disasters in full sentences. mwah. 🦋🌸💖