explain_tcsendbreak(3)

✨ NAME ✨

explain_tcsendbreak — bestie, this is the glow-up that explains your tcsendbreak(3) errors 💅

So like, you called tcsendbreak(3) (it's in the Library Functions Manual, section 3, iykyk) and it flopped. This little libexplain page is here to tell you why it flopped, in actual words, not just a sad number. 🫶

---

🌸 SYNOPSIS 🌸

#include <libexplain/tcsendbreak.h>
const char *explain_tcsendbreak(int fildes, int duration);
const char *explain_errno_tcsendbreak(int errnum, int fildes, int duration);
void explain_message_tcsendbreak(char *message, int message_size, int fildes, int duration);
void explain_message_errno_tcsendbreak(char *message, int message_size, int errnum, int fildes, int duration);

---

💖 DESCRIPTION 💖

Okay so these functions are your error-translator besties — you use them to get actual explanations for errors that come back from the tcsendbreak(3) system call. No more staring at a bare errno like 👁️👄👁️.

---

🎀 explain_tcsendbreak

const char *explain_tcsendbreak(int fildes, int duration);

The explain_tcsendbreak function gets you an explanation of an error that came back from the tcsendbreak(3) system call. The bare minimum the message will contain is the value of strerror(errno) — but honestly? Usually it does so much better than that, and it points at the actual underlying cause in way more detail. It's giving detective energy fr fr 🔍

The errno global variable is what it uses to grab the error value it's gonna decode. (No passing it in, it just reads the global. Iconic but also, watch out, see the note below.)

• fildes — the original fildes, exactly as passed to the tcsendbreak(3) system call. Don't get creative with it, it wants the real one.
• duration — the original duration, exactly as passed to the tcsendbreak(3) system call. Same deal.

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 get overwritten by the next call to any libexplain function that shares this buffer — including calls from other threads. It's one communal water bottle, basically. 🚰

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

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

if (tcsendbreak(fildes, duration) < 0)
{
    fprintf(stderr, "%s\n", explain_tcsendbreak(fildes, duration));
    exit(EXIT_FAILURE);
}

The above code example is available pre-packaged as the explain_tcsendbreak_or_die(3) function. Slay, no need to write it yourself. ✨

---

🦋 explain_errno_tcsendbreak

const char *explain_errno_tcsendbreak(int errnum, int fildes, int duration);

The explain_errno_tcsendbreak function gets you an explanation of an error that came back from the tcsendbreak(3) system call. Again, the least the message will contain is the value of strerror(errno), but usually it does way better and tells 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 is necessary if you need to run any code between the system call being explained and this function — because a lot of libc functions will mess with the value of errno. So like, snapshot it first, bestie. 📸
• fildes — the original fildes, exactly as passed to the tcsendbreak(3) system call.
• duration — the original duration, exactly as passed to the tcsendbreak(3) system call.

Returns:

The message explaining the error. Same shared-buffer situation: this message buffer is shared by all libexplain functions which don't supply a buffer in their argument list, and it gets overwritten by the next call to any libexplain function sharing 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.

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

if (tcsendbreak(fildes, duration) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_tcsendbreak(err, fildes, duration));
    exit(EXIT_FAILURE);
}

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

---

💜 explain_message_tcsendbreak

void explain_message_tcsendbreak(char *message, int message_size, int fildes, int duration);

The explain_message_tcsendbreak function is used to obtain an explanation of an error returned by the tcsendbreak(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 used to obtain the error value to be decoded.

• message — the location in which to store the returned message. Here's the cute part: if you supply a suitable message return buffer, this function is thread safe. You bring your own cup, you don't share. 🥤
• 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 tcsendbreak(3) system call.
• duration — the original duration, exactly as passed to the tcsendbreak(3) system call.

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

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

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

---

🧚 explain_message_errno_tcsendbreak

void explain_message_errno_tcsendbreak(char *message, int message_size, int errnum, int fildes, int duration);

The explain_message_errno_tcsendbreak function is used to obtain an explanation of an error returned by the tcsendbreak(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 full combo meal, if you will. 🍓

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

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

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

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

---

🌈 SEE ALSO 🌈

• tcsendbreak(3) — send terminal line break
• explain_tcsendbreak_or_die(3) — send terminal line break and report errors

---

👑 COPYRIGHT 👑

This is libexplain version 1.4, and it's Copyright (C) 2009 Peter Miller. Respect the elders, they ate. 🙇‍♀️

---

And that's the whole page, bestie — explain_tcsendbreak(3), from the Library Functions Manual, written by Peter Miller in 2009 and shipped as libexplain version 1.4. Go forth and decode your errnos. 💖✨🦋