explain_fputc(3)

✨ explain_fputc(3) ✨

okay bestie, gather round, because we're in the Library Functions Manual today and this one is a whole mood 💖

---

🌸 NAME 🌸

explain_fputc — the girl who explains your fputc(3) errors for you, no cap 💅

---

🎀 SYNOPSIS 🎀

#include <libexplain/fputc.h>
const char *explain_fputc(int c, FILE *fp);
const char *explain_errno_fputc(int errnum, int c, FILE *fp);
void explain_message_fputc(char *message, int message_size, int c, FILE
*fp);
void explain_message_errno_fputc(char *message, int message_size, int
errnum, int c, FILE *fp);

---

🦋 DESCRIPTION 🦋

so these functions? they're the ones you call when fputc(3) does a little oopsie and you need an actual explanation of what went wrong. not just vibes. receipts. 🔥

---

🌈 explain_fputc

const char *explain_fputc(int c, FILE *fp);

the explain_fputc function gets you an explanation of an error that came back from the fputc(3) system call. the bare minimum it'll give you is the value of strerror(errno) — but bestie, usually it does so much better than that and tells you the actual underlying cause in more detail. it's giving detective energy 🔍

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

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

if (fputc(c, fp) == EOF)
{
    fprintf(stderr, "%s\n", explain_fputc(c, fp));
    exit(EXIT_FAILURE);
}

• c — the original c, exactly as you passed it to the fputc(3) system call. don't be changing it up on me 🫶
• fp — the original fp, exactly as you passed it to the fputc(3) system call.

Returns: the message explaining the error. heads up tho — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. so the very next call to any libexplain function that shares this buffer will overwrite it. and yes, that includes calls from other threads. 😭

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

---

💜 explain_errno_fputc

const char *explain_errno_fputc(int errnum, int c, FILE *fp);

the explain_errno_fputc function also gets you an explanation of an error returned by the fputc(3) system call. the least the message will contain is the value of strerror(errnum), but usually it goes way harder and shows you the underlying cause in more detail. iconic behavior honestly ✨

use it kinda like this:

if (fputc(c, fp) == EOF)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_fputc(err, c, fp));
    exit(EXIT_FAILURE);
}

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. this matters! because if you need to run any code between the system call you're explaining and this function, you gotta save it first — so many libc functions will just casually alter the value of errno on you 🙈
• c — the original c, exactly as passed to the fputc(3) system call.
• fp — the original fp, exactly as passed to the fputc(3) system call.

Returns: the message explaining the error. and again — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list, so the next call to any libexplain function sharing 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 many other functions in this library do too.

---

🧚 explain_message_fputc

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

the explain_message_fputc function is here to get you an explanation of an error returned by the fputc(3) system call. minimum effort version gives you the value of strerror(errno), but usually it does way better and points at the underlying cause in more detail. slay 💅

the errno global variable is what it uses to get the error value to decode.

use it kinda like:

if (fputc(c, fp) == EOF)
{
    char message[3000];
    explain_message_fputc(message, sizeof(message), c, fp);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location where the returned message gets stored. and guess what bestie — if you supply a suitable message return buffer, this function is thread safe! 👑
• message_size — the size in bytes of the location where you're storing that returned message.
• c — the original c, exactly as passed to the fputc(3) system call.
• fp — the original fp, exactly as passed to the fputc(3) system call.

---

🍓 explain_message_errno_fputc

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

the explain_message_errno_fputc function may be used to obtain an explanation of an error returned by the fputc(3) 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. main character energy fr fr 🌟

use it kinda like:

if (fputc(c, fp) == EOF)
{
    int err = errno;
    char message[3000];
    explain_message_errno_fputc(message, sizeof(message), err, c, fp);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — where the returned message gets stored. supply a suitable message return buffer and boom, this function is thread safe 💖
• message_size — the size in bytes of the location where the returned message goes.
• errnum — the error value to be decoded, usually taken from the errno global variable just before this function is called. necessary if you need to run any code between the system call being explained and this function, because many libc functions will alter errno on you 😤
• c — the original c, exactly as passed to the fputc(3) system call.
• fp — the original fp, exactly as passed to the fputc(3) system call.

---

🌈 SEE ALSO 🌈

• fputc(3) — output of characters
• explain_fputc_or_die(3) — output of characters and report errors

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

okay that's the whole page, bestie 💖 libexplain version 1.4, Copyright (C) 2008 Peter Miller — go forth, explain your fputc errors, and stay iconic 🦋✨💅