explain_putchar(3)

💖 explain_putchar(3) — like, the whole vibe 💖

okay so bestie, welcome to the explain_putchar(3) page from the Library Functions Manual, and no cap this one is a little gem 🫶 it's all about getting actual explanations for errors from putchar(3), and I'm gonna walk you through every single bit of it.

---

✨ NAME ✨

explain_putchar — bestie, this is the one that explains putchar(3) errors 💅

---

🌸 SYNOPSIS 🌸

#include <libexplain/putchar.h>
const char *explain_putchar(int c);
const char *explain_errno_putchar(int errnum, int c);
void explain_message_putchar(char *message, int message_size, int c);
void explain_message_errno_putchar(char *message, int message_size, int
errnum, int c);

---

🦋 DESCRIPTION 🦋

So these functions are the ones you call when putchar(3) acts up and you want an explanation instead of just a sad little mystery. They give you explanations for errors returned by the putchar(3) system call. Iconic behaviour, honestly.

💜 explain_putchar

const char *explain_putchar(int c);

The explain_putchar function gets you an explanation of an error returned by the putchar(3) system call. The least the message will contain is the value of strerror(errno) — but usually it does so much better and tells you the actual underlying cause in more detail. it's giving overachiever, and we love that 💖

The errno global variable is the one used to grab the error value that gets decoded.

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

if (putchar(c) == EOF)
{
    fprintf(stderr, "%s\n", explain_putchar(c));
    exit(EXIT_FAILURE);
}

• c — the original c, exactly as passed to the putchar(3) system call. no edits, no remixes, just the exact same value, periodt.

Returns:

The message explaining the error. Okay so important: this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. That means it gets overwritten by the next call to any libexplain function that shares this buffer — including other threads. so like, don't get attached to it 🌸

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. fr fr, be careful with it.

💙 explain_errno_putchar

const char *explain_errno_putchar(int errnum, int c);

The explain_errno_putchar function gets you an explanation of an error returned by the putchar(3) system call. The least the message will contain is the value of strerror(errnum) — but usually it goes way harder and indicates the underlying cause in more detail ✨

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

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

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. You need to do it this way if you have to call any code between the system call you're explaining and this function, because many libc functions will alter the value of errno. so snatch that value early bestie, it does not wait for you 😭
• c — the original c, exactly as passed to the putchar(3) system call.

Returns:

The message explaining the error. Same deal 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 that shares this buffer, including other threads. it's a communal vibe and it does not respect your boundaries 🙈

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

💚 explain_message_putchar

void explain_message_putchar(char *message, int message_size, int c);

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

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

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

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

• message — the location in which to store the returned message. And here's the glow-up: if you supply a suitable message return buffer, this function is thread safe. main character energy honestly 🌈
• message_size — the size in bytes of the location in which to store the returned message.
• c — the original c, exactly as passed to the putchar(3) system call.

💛 explain_message_errno_putchar

void explain_message_errno_putchar(char *message, int message_size, int
errnum, int c);

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

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

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

• message — the location in which to store the returned message. If a suitable message return buffer is supplied, this function is thread safe. slay 🎀
• 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. yeah, errno is lowkey feral, grab it before anything else touches it 💀
• c — the original c, exactly as passed to the putchar(3) system call.

---

🌟 SEE ALSO 🌟

• putchar(3) — output of characters
• explain_putchar_or_die(3) — output of characters and report errors

---

👑 COPYRIGHT 👑

libexplain version 1.4

Copyright (C) 2008 Peter Miller

---

and that's the whole page bestie, we ate and left no crumbs 🍓 if you made it this far you're officially a putchar(3) error-explaining icon — explain_putchar(3), out 💅✨🧚