explain_getchar(3)

✨ NAME ✨

explain_getchar — bestie, this is the girl who explains your getchar(3) errors 💅

(It lives in libexplain, section 3, the Library Functions Manual — so if your stdio is acting up and you're like "why tho", this is the page you open 🫶)

---

🎀 SYNOPSIS 🎀

#include <libexplain/getchar.h>
const char *explain_getchar(void);
const char *explain_errno_getchar(int errnum, void);
void explain_message_getchar(char *message, int message_size);
void explain_message_errno_getchar(char *message, int message_size, int
errnum);

---

🦋 DESCRIPTION 🦋

okay so these functions are basically your translator besties: you use them to get actual explanations for errors that came back from the getchar(3) system call. lowkey essential, no cap.

🌸 explain_getchar 🌸

const char *explain_getchar(void);

So explain_getchar is the one you call when you want an explanation of an error that getchar(3) returned. The least you're gonna get in that message is the value of strerror(errno), but usually it does way better than that and tells you the actual underlying cause in more detail. it's giving detective energy 🔍

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

You're meant to use this one kinda like this:

int c = getchar();
if (c == EOF && ferror(stdin))
{
    fprintf(stderr, "%s\n", explain_getchar());
    exit(EXIT_FAILURE);
}

Returns: the message explaining the error 💖 Heads up though — this message buffer is shared by all the libexplain functions that don't take a buffer in their argument list. So it gets overwritten the next time any libexplain function that shares this buffer gets called, other threads included. So like… copy it if you need it, bestie 😭

Note: this function is not thread safe, because it shares a return buffer across all threads — and honestly, so do many other functions in this library. not me being the bearer of bad news 🙈

🌈 explain_errno_getchar 🌈

const char *explain_errno_getchar(int errnum);

explain_errno_getchar is the same vibe, but you hand it the error number yourself — it gives you an explanation of an error returned by the getchar(3) system call. Again, the least the message contains is the value of strerror(errnum), but usually it goes way harder and points at the real underlying cause. iconic behavior ✨

Use it in a fashion similar to this little moment:

int c = getchar();
if (c == EOF && ferror(stdin))
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_getchar(err, ));
    exit(EXIT_FAILURE);
}

• errnum — the error value that's gonna be decoded, usually grabbed from the errno global variable right before this function is called. You need to do that if you're calling any other code between the system call you're explaining and this function, because so many libc functions will just casually rewrite errno on you. sneaky fr fr 💀

Returns: the message explaining the error 💜 Same deal as before — that message buffer is shared by all libexplain functions that don't supply a buffer in their argument list, and it gets overwritten by the next call to any libexplain function sharing this buffer, including from other threads. save it if you love it 🥺

Note: this function is not thread safe either, because it shares a return buffer across all threads, and so do many other functions in this library. we stay consistent 💅

🧚 explain_message_getchar 🧚

void explain_message_getchar(char *message, int message_size);

explain_message_getchar may be used to obtain an explanation of an error returned by the getchar(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, we love her 🌸

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

You'd use it kinda like this:

int c = getchar();
if (c == EOF && ferror(stdin))
{
    char message[3000];
    explain_message_getchar(message, sizeof(message), );
    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. look at her go 👑
• message_size — the size in bytes of the location where the returned message gets stored.

💜 explain_message_errno_getchar 💜

void explain_message_errno_getchar(char *message, int message_size, int
errnum);

explain_message_errno_getchar may be used to obtain an explanation of an error returned by the getchar(3) system call. The least the message will contain is the value of strerror(errnum), but usually it does much better and tells you the underlying cause in more detail. no crumbs left behind 🍓

Here's the example energy:

int c = getchar();
if (c == EOF && ferror(stdin))
{
    int err = errno;
    char message[3000];
    explain_message_errno_getchar(message, sizeof(message), err, );
    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 🫶
• 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 a bunch of libc functions will alter the value of errno on you. they can't help themselves 😤

---

👀 SEE ALSO 👀

• getchar(3) — input of characters
• explain_getchar_or_die(3) — input of characters and report errors

---

💖 COPYRIGHT 💖

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

and that's the whole page, bestie — mwah, take care of your errno, and remember: explain_getchar(3) from libexplain version 1.4, © 2008 Peter Miller, has your back always 💅💖✨