explain_fflush(3)

💖 explain_fflush(3) — Library Functions Manual 💖

okay bestie, sit down, hydrate, because we're about to talk about explain_fflush from libexplain — the little library that looks at your fflush(3) errors and is like "girl, here's what actually went wrong" instead of just handing you a cryptic errno and walking away. 🫶

---

✨ NAME ✨

explain_fflush — explain fflush(3) errors 💅

---

🌸 SYNOPSIS 🌸

#include <libexplain/fflush.h>
const char *explain_fflush(FILE *fp);
const char *explain_errno_fflush(int errnum, FILE *fp);
void explain_message_fflush(char *message, int message_size, FILE *fp);
void explain_message_errno_fflush(char *message, int message_size, int
errnum, FILE *fp);

---

🦋 DESCRIPTION 🦋

So these functions? They're your little translators. You use them to get explanations for errors that the fflush(3) system call hands back to you. Think of them as the friend who reads the error and goes "okay so here's what that actually means." ✨

---

🎀 explain_fflush

const char *explain_fflush(FILE *fp);

The explain_fflush function gets you an explanation of an error returned by the fflush(3) system call. At the bare minimum the message will contain the value of strerror(errno), but honestly? Usually it does so much better than that, and it will point at the underlying cause in way more detail. lowkey iconic behavior.

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

• fp — the original fp, exactly as it was passed to the fflush(3) system call. no substitutions, no remixes.

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. That means it will get 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 the same thing. fr fr, don't fight me on this, it's in the source.

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

if (fflush(fp) < 0)
{
    fprintf(stderr, "%s\n", explain_fflush(fp));
    exit(EXIT_FAILURE);
}

The above code example is available pre-packaged as the explain_fflush_or_die(3) function. 👑

---

🧚 explain_errno_fflush

const char *explain_errno_fflush(int errnum, FILE *fp);

The explain_errno_fflush function gets you an explanation of an error returned by the fflush(3) system call. Least it'll contain is the value of strerror(errno), but usually it goes way harder and shows you the underlying cause in more detail.

• errnum — the error value to be decoded, usually grabbed from the errno global variable just before this function is called. This matters if you need to run any code between the system call you're explaining and this function, because a lot of libc functions will go and mess with the value of errno. 🙈
• fp — the original fp, exactly as passed to the fflush(3) system call.

Returns: The message explaining the error. Same situation 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 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.

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

if (fflush(fp) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_fflush(err, fp));
    exit(EXIT_FAILURE);
}

The above code example is available pre-packaged as the explain_fflush_or_die(3) function. 💖

---

🌈 explain_message_fflush

void explain_message_fflush(char *message, int message_size, FILE *fp);

The explain_message_fflush function gets you an explanation of an error returned by the fflush(3) system call. The least the message will contain is the value of strerror(errno), but usually it does much better and shows you the underlying cause in more detail. she's thorough.

The errno global variable is used to get the error value to be decoded.

• 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.
• fp — the original fp, exactly as passed to the fflush(3) system call.

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

if (fflush(fp) < 0)
{
    char message[3000];
    explain_message_fflush(message, sizeof(message), fp);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

The above code example is available pre-packaged as the explain_fflush_or_die(3) function. ✨

---

🍓 explain_message_errno_fflush

void explain_message_errno_fflush(char *message, int message_size, int
errnum, FILE *fp);

The explain_message_errno_fflush function gets you an explanation of an error returned by the fflush(3) system call. Least it'll contain is the value of strerror(errno), but usually it does much better and points at the underlying cause in more detail. main character energy tbh.

• 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. 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. 💀
• fp — the original fp, exactly as passed to the fflush(3) system call.

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

if (fflush(fp) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_fflush(message, sizeof(message), err,
    fp);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

The above code example is available pre-packaged as the explain_fflush_or_die(3) function. 🌟

---

💜 SEE ALSO 💜

• fflush(3) — flush a stream
• explain_fflush_or_die(3) — flush a stream and report errors

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2009 Peter Miller

---

and that's the whole page bestie, no cap 💅 libexplain version 1.4, copyright 2009 Peter Miller — go forth and explain your fflush errors with confidence, you're literally the main character of stream flushing now. 🎀✨🦋