explain_read(3)

💖 explain_read(3) — the manual page, but make it make sense 💖

okay bestie, gather round, because we're talking about explain_read(3) from the libexplain library, and honestly? it's giving "your syscall failed and nobody told you why" energy. not anymore. ✨

---

🌸 NAME 🌸

explain_read — explain read(2) errors 🫶

like, it explains the errors. that's the whole job. she's employed. 💅

---

✨ SYNOPSIS ✨

#include <libexplain/read.h>
const char *explain_read(int fildes, const void *data, long data_size);
const char *explain_errno_read(int errnum, int fildes, const void *data,
long data_size);
void explain_message_read(char *message, int message_size, int fildes,
const void *data, long data_size);
void explain_message_errno_read(char *message, int message_size, int
errnum, int fildes, const void *data, long data_size);

four functions. four little helpers. one very confused read(2). let's go. 🦋

---

🎀 DESCRIPTION 🎀

These functions may be used to obtain an explanation for read(2) errors. that's it, that's the vibe check — something went wrong in your read(2) call, and instead of staring at errno like it owes you money, you let libexplain tell you what actually happened. 👑

💜 explain_read

const char *explain_read(int fildes, const void *data, long data_size);

The explain_read function may be used to obtain a human readable explanation of what went wrong in a read(2) system call. The least the message will contain is the value of strerror(errno), but usually it will do much better, and indicate the underlying cause in more detail. she's not just reading the error, she's interpreting it. main character behavior honestly. 😭

The error number will be picked up from the errno global variable. it just grabs it. no questions.

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

ssize_t n = read(fd, data, data_size);
if (n < 0)
{
    fprintf(stderr, "%s\n", explain_read(fd, data, data_size));
    exit(EXIT_FAILURE);
}

• fildes — The original fildes, exactly as passed to the read(2) system call. like, the same one. don't be creative.
• data — The original data, exactly as passed to the read(2) system call.
• data_size — The original data_size, exactly as passed to the read(2) system call.

Returns:

The message explaining the error. This message buffer is shared by all libexplain functions which do not supply a buffer in their argument list. This will be overwritten by the next call to any libexplain function which shares this buffer, including other threads. so like... screenshot it before it's gone bestie. 📸

Note: This function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library. she's iconic but she's not safe in a crowd. 💀

---

🦋 explain_errno_read

const char *explain_errno_read(int errnum, int fildes, const void *data,
long data_size);

The explain_errno_read function may be used to obtain a human readable explanation of what went wrong in a read(2) system call. The least the message will contain is the value of strerror(errnum), but usually it will do much better, and indicate the underlying cause in more detail. same energy, but you hand her the error number yourself. 🫶

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

ssize_t n = read(fd, data, data_size);
if (n < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_read(err, fd, data, data_size));
    exit(EXIT_FAILURE);
}

• errnum — The error value to be decoded, usually obtain 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. ⚠️ so like, snapshot errno immediately, because the moment you call literally anything else it might get rewritten and now you're explaining the wrong error. embarrassing. 🙈
• fildes — The original fildes, exactly as passed to the read(2) system call.
• data — The original data, exactly as passed to the read(2) system call.
• data_size — The original data_size, exactly as passed to the read(2) system call.

Returns:

The message explaining the error. This message buffer is shared by all libexplain functions which do not supply a buffer in their argument list. This will be overwritten by the next call to any libexplain function which shares this buffer, including other threads. same shared-buffer situation. same chaos. 🌀

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

---

🌈 explain_message_read

void explain_message_read(char *message, int message_size, int fildes,
const void *data, long data_size);

The explain_message_read function may be used to obtain a human readable explanation of what went wrong in a read(2) system call. The least the message will contain is the value of strerror(errno), but usually it will do much better, and indicate the underlying cause in more detail. and this one writes into YOUR buffer, which is the glow-up. 🌟

The error number will be picked up from the errno global variable.

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

ssize_t n = read(fd, data, data_size);
if (n < 0)
{
    char message[3000];
    explain_message_read(message, sizeof(message), fd, data, data_size));
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — The location in which to store the returned message. Because a message return buffer has been supplied, this function is thread safe. she brought her own storage bestie, we love a prepared queen. 👑
• message_size — The size in bytes of the location in which to store the returned message. don't skimp on it. 📏
• fildes — The original fildes, exactly as passed to the read(2) system call.
• data — The original data, exactly as passed to the read(2) system call.
• data_size — The original data_size, exactly as passed to the read(2) system call.

Note: Given a suitably thread safe buffer, this function is thread safe. yes queen, boundaries! 🎀

---

⭐ explain_message_errno_read

void explain_message_errno_read(char *message, int message_size, int
errnum, int fildes, const void *data, long data_size);

The explain_message_errno_read function may be used to obtain a human readable explanation of what went wrong in a read(2) system call. The least the message will contain is the value of strerror(errnum), but usually it will do much better, and indicate the underlying cause in more detail. it's the final boss form: your buffer and your own error number. 🔥

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

ssize_t n = read(fd, data, data_size);
if (n < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_read(message, sizeof(message), err,
        fd, data, data_size);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — The location in which to store the returned message. Because a message return buffer has been 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 obtain 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. again: grab errno FIRST, then do your other little tasks, then explain. otherwise you're explaining a totally different problem and that's not the assignment. 😭
• fildes — The original fildes, exactly as passed to the read(2) system call.
• data — The original data, exactly as passed to the read(2) system call.
• data_size — The original data_size, exactly as passed to the read(2) system call.

Note: Given a suitably thread safe buffer, this function is thread safe. 💅

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

🌸 AUTHOR 🌸

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

---

okay that's the whole page bestie, you ate it, no crumbs. 💖✨ this was explain_read(3) from the Library Functions Manual, brought to you by libexplain version 1.4, © 2008 Peter Miller — and yes, she's still explain_read(3), always and forever. 🎀🦋🌸🫶💜