explain_fread(3)

💖 explain_fread(3) — the NAME bit, bestie 💖

okay so, this page lives in the Library Functions Manual, and the whole entire point is: explain_fread — explain fread(3) errors. that's it. that's the vibe. 🫶

---

✨ SYNOPSIS ✨

#include <libexplain/fread.h>
const char *explain_fread(void *ptr, size_t size, size_t nmemb, FILE *fp);
const char *explain_errno_fread(int errnum, void *ptr, size_t size, size_t nmemb, FILE *fp);
void explain_message_fread(char *message, int message_size, void *ptr, size_t size, size_t nmemb, FILE *fp);
void explain_message_errno_fread(char *message, int message_size, int errnum, void *ptr, size_t size, size_t nmemb, FILE *fp);

---

🦋 DESCRIPTION 🦋

so these functions? they're your little translators. when the fread(3) system call comes back with an error, these give you an explanation for it. that's the whole job. 💅

---

🌸 explain_fread 🌸

const char *explain_fread(void *ptr, size_t size, size_t nmemb, FILE *fp);

the explain_fread function gets you an explanation of an error returned by the fread(3) system call. the bare minimum you'll get in the message is the value of strerror(errno), but honestly? usually it does so much better and actually tells you the underlying cause in more detail. main character behaviour fr. 👑

the errno global variable is what gets used to grab the error value that's gonna be decoded.

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

size_t how_many = fread(ptr, size, nmemb, fp);
if (how_many == 0 && ferror(fp))
{
    fprintf(stderr, "%s\n", explain_fread(ptr, size, nmemb, fp));
    exit(EXIT_FAILURE);
}

• ptr — the original ptr, exactly as passed to the fread(3) system call.
• size — the original size, exactly as passed to the fread(3) system call.
• nmemb — the original nmemb, exactly as passed to the fread(3) system call.
• fp — the original fp, exactly as passed to the fread(3) 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 argument list. so it gets overwritten by the next call to any libexplain function that shares this buffer, including other threads. 😭

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. not me being the shared-buffer friend group 🙈

---

🎀 explain_errno_fread 🎀

const char *explain_errno_fread(int errnum, void *ptr, size_t size, size_t nmemb, FILE *fp);

the explain_errno_fread function gets you an explanation of an error returned by the fread(3) system call. the least the message will contain is the value of strerror(errnum), but usually it does way better and points at the underlying cause in more detail. ✨

this function is meant to be used kinda like this example:

size_t how_many = fread(ptr, size, nmemb, fp);
if (how_many == 0 && ferror(fp))
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_fread(err, ptr, size, nmemb, fp));
    exit(EXIT_FAILURE);
}

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function gets called. you need this if you have to run any code between the system call being explained and this function, because like, a ton of libc functions will mess with the value of errno. lowkey chaotic.
• ptr — the original ptr, exactly as passed to the fread(3) system call.
• size — the original size, exactly as passed to the fread(3) system call.
• nmemb — the original nmemb, exactly as passed to the fread(3) system call.
• fp — the original fp, exactly as passed to the fread(3) system call.

Returns:

the message explaining the error. and yeah — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. it'll get overwritten by the next call to any libexplain function sharing this buffer, including other threads. 💀

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

---

🧚 explain_message_fread 🧚

void explain_message_fread(char *message, int message_size, void *ptr, size_t size, size_t nmemb, FILE *fp);

the explain_message_fread function may be used to obtain an explanation of an error returned by the fread(3) system call. the least the message will contain is the value of strerror(errno), but usually it does much better and shows the underlying cause in more detail. 💖

the errno global variable is used to get the error value that's gonna be decoded.

this function is meant to be used kinda like this example:

size_t how_many = fread(ptr, size, nmemb, fp);
if (how_many == 0 && ferror(fp))
{
    char message[3000];
    explain_message_fread(message, sizeof(message), ptr, size, nmemb, fp);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location where the returned message gets stored. if you supply a suitable message return buffer, this function is thread safe. slay. 🫶
• message_size — the size in bytes of the location where the returned message gets stored.
• ptr — the original ptr, exactly as passed to the fread(3) system call.
• size — the original size, exactly as passed to the fread(3) system call.
• nmemb — the original nmemb, exactly as passed to the fread(3) system call.
• fp — the original fp, exactly as passed to the fread(3) system call.

---

🦋 explain_message_errno_fread 🦋

void explain_message_errno_fread(char *message, int message_size, int errnum, void *ptr, size_t size, size_t nmemb, FILE *fp);

the explain_message_errno_fread function may be used to obtain an explanation of an error returned by the fread(3) system call. the least the message will contain is the value of strerror(errnum), but usually it does so much better and indicates the underlying cause in more detail. ⭐

this function is meant to be used kinda like this example:

size_t how_many = fread(ptr, size, nmemb, fp);
if (how_many == 0 && ferror(fp))
{
    int err = errno;
    char message[3000];
    explain_message_errno_fread(message, sizeof(message), err,
        ptr, size, nmemb, fp);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location where the returned message gets stored. if a suitable message return buffer is supplied, this function is thread safe. we love to see it. ✨
• message_size — the size in bytes of the location where the returned message gets stored.
• errnum — the error value to be decoded, usually obtained from the errno global variable right before this function is called. this is necessary if you need to call any code between the system call being explained and this function, because many libc functions will alter the value of errno. it's giving sabotage tbh.
• ptr — the original ptr, exactly as passed to the fread(3) system call.
• size — the original size, exactly as passed to the fread(3) system call.
• nmemb — the original nmemb, exactly as passed to the fread(3) system call.
• fp — the original fp, exactly as passed to the fread(3) system call.

---

👀 SEE ALSO 👀

• fread(3) — binary stream input
• explain_fread_or_die(3) — binary stream input and report errors

---

📜 COPYRIGHT 📜

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

and that's the whole page, bestie 🎀 no cap, every flag and every word accounted for. this was explain_fread(3) from libexplain version 1.4, Copyright (C) 2008 Peter Miller — go forth and decode your errors, you absolute icon. 💅🌈👑