explain_tcflush(3)

✨ NAME ✨

explain_tcflush — bestie, it explains tcflush(3) errors 💖

Like, it's the libexplain glow-up that turns a boring old error code into an actual sentence about what went wrong. Fr fr.

---

🦋 SYNOPSIS 🦋

#include <libexplain/tcflush.h>
const char *explain_tcflush(int fildes, int selector);
const char *explain_errno_tcflush(int errnum, int fildes, int selector);
void explain_message_tcflush(char *message, int message_size, int
        fildes, int selector);
void explain_message_errno_tcflush(char *message, int message_size, int
        errnum, int fildes, int selector);

---

🌈 DESCRIPTION 🌈

Okay so here's the tea: these functions are your go-to for getting explanations for errors that the tcflush(3) system call hands back. Four of them, one for every mood. 👑

🌸 explain_tcflush

const char *explain_tcflush(int fildes, int selector);

explain_tcflush gets you an explanation of an error returned by the tcflush(3) system call. The absolute least the message will contain is the value of strerror(errno), but ngl it usually 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 it uses to grab the error value that needs decoding.

• fildes — the original fildes, exactly as passed to the tcflush(3) system call. No edits, no remix. 💅
• selector — the original selector, exactly as passed to the tcflush(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 will be 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. Periodt.

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

if (tcflush(fildes, selector) < 0)
{
    fprintf(stderr, "%s\n", explain_tcflush(fildes, selector));
    exit(EXIT_FAILURE);
}

The above code example is available pre-packaged as the explain_tcflush_or_die(3) function. So convenient, we love that for us. 🎀

🧚 explain_errno_tcflush

const char *explain_errno_tcflush(int errnum, int fildes, int selector);

explain_errno_tcflush gets you an explanation of an error returned by the tcflush(3) system call. The least the message will contain is the value of strerror(errno), but usually it does much better and points at the underlying cause in more detail. Iconic behaviour honestly. ✨

• errnum — the error value to be decoded, usually grabbed 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 being explained and this function, because many libc functions will alter the value of errno. Sneaky little things.
• fildes — the original fildes, exactly as passed to the tcflush(3) system call.
• selector — the original selector, exactly as passed to the tcflush(3) system call.

Returns: the message explaining the error. Same deal as before — this message buffer is shared by all libexplain functions which don't supply a buffer in their argument list. It'll get overwritten by the next call to any libexplain function that shares this buffer, including other threads. 🙈

Note: not thread safe, because it shares a return buffer across all threads, and many other functions in this library do the same. Yeah.

Example: this function is intended to be used in a fashion similar to the following example:

if (tcflush(fildes, selector) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_tcflush(err, fildes, selector));
    exit(EXIT_FAILURE);
}

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

💜 explain_message_tcflush

void explain_message_tcflush(char *message, int message_size, int
        fildes, int selector);

explain_message_tcflush gets you an explanation of an error returned by the tcflush(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 obtain the error value to be decoded.

• message — the location in which to store the returned message. If a suitable message return buffer is supplied, this function is thread safe. 👑
• message_size — the size in bytes of the location in which to store the returned message.
• fildes — the original fildes, exactly as passed to the tcflush(3) system call.
• selector — the original selector, exactly as passed to the tcflush(3) system call.

Example: this function is intended to be used in a fashion similar to the following example:

if (tcflush(fildes, selector) < 0)
{
    char message[3000];
    explain_message_tcflush(message, sizeof(message), fildes, selector);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

The above code example is available pre-packaged as the explain_tcflush_or_die(3) function. Slay. 💅

🍓 explain_message_errno_tcflush

void explain_message_errno_tcflush(char *message, int message_size, int
        errnum, int fildes, int selector);

explain_message_errno_tcflush gets you an explanation of an error returned by the tcflush(3) system call. The least the message will contain is the value of strerror(errno), but usually it does much better and tells you the underlying cause in more detail. 🔥

• message — the location in which to store the returned message. If a suitable message return buffer is supplied, 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. (Yes, we're saying it again. It matters!! 😤)
• fildes — the original fildes, exactly as passed to the tcflush(3) system call.
• selector — the original selector, exactly as passed to the tcflush(3) system call.

Example: this function is intended to be used in a fashion similar to the following example:

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

The above code example is available pre-packaged as the explain_tcflush_or_die(3) function. Chef's kiss. 🧚

---

👀 SEE ALSO 👀

• tcflush(3) — discard terminal data
• explain_tcflush_or_die(3) — discard terminal data and report errors

---

💖 COPYRIGHT 💖

libexplain version 1.4 Copyright (C) 2009 Peter Miller

---

And that's the whole page, bestie! 🎀 This little love letter to error messages is from libexplain version 1.4, with the copyright sitting pretty at Copyright (C) 2009 Peter Miller — and yes, it lives in the explain_tcflush(3) manual, so you always know where to find it. Go forth and flush those terminals with style. 💅✨🦋