explain_futimens(3)

💖 explain_futimens(3) 💖

okay bestie, pull up a chair, because we're about to get into explain_futimens(3) from the Library Functions Manual — and no, it's not as scary as it sounds, i promise 🫶

---

✨ NAME ✨

explain_futimens — the girl whose whole job is explaining futimens(3) errors to you 💅

---

🌸 SYNOPSIS 🌸

#include <libexplain/futimens.h>
const char *explain_futimens(int fildes, const struct time_spec *data);
const char *explain_errno_futimens(int errnum, int fildes, const struct
time_spec *data);
void explain_message_futimens(char *message, int message_size, int
fildes, const struct time_spec *data);
void explain_message_errno_futimens(char *message, int message_size, int
errnum, int fildes, const struct time_spec *data);

---

🦋 DESCRIPTION 🦋

So like, these functions are your little translators ✨ — you use them to get explanations for errors that the futimens(3) system call hands back to you. Basically the system call says "nope" and these functions say "here's why, bestie."

---

💜 explain_futimens

const char *explain_futimens(int fildes, const struct time_spec *data);

The explain_futimens function is the one you call to get an explanation of an error that futimens(3) returned. And listen — the least the message will contain is the value of strerror(errno), but usually it's gonna do so much better than that and tell you the actual underlying cause in way more detail. it's giving overachiever 💅

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

• fildes — the original fildes, exactly as passed to the futimens(3) system call. no edits, no glow-up, the og 🎀
• data — the original data, exactly as passed to the futimens(3) system call. same energy ✨

Returns: The message explaining the error. and okay here's the tea — this message buffer is shared by all the libexplain functions that don't supply a buffer in their argument list. so it's gonna get overwritten by the next call to any libexplain function that shares this buffer, including 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 too. not me being messy in a multithreaded program 🙈

Example: This function is meant to be used in a fashion similar to this:

if (futimens(fildes, data) < 0)
{
    fprintf(stderr, "%s\n", explain_futimens(fildes, data));
    exit(EXIT_FAILURE);
}

The above code example is available pre-packaged as the explain_futimens_or_die(3) function. iconique, no cap 👑

---

💖 explain_errno_futimens

const char *explain_errno_futimens(int errnum, int fildes, const struct
time_spec *data);

The explain_errno_futimens function gets you an explanation of an error returned by the futimens(3) system call. Same deal as before — the least the message will contain is the value of strerror(errno), but usually it does much better and points at the real underlying cause in more detail. slay ✨

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. and why do you need to do that? because if you gotta run any code between the system call you're explaining and this function, you need to save it first — so many libc functions will alter the value of errno and ruin everything 💀
• fildes — the original fildes, exactly as passed to the futimens(3) system call.
• data — the original data, exactly as passed to the futimens(3) system call.

Returns: The message explaining the error. and again, bestie — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. 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 the same. periodt.

Example: This function is meant to be used in a fashion similar to this:

if (futimens(fildes, data) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_futimens(err, fildes,
    data));
    exit(EXIT_FAILURE);
}

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

---

🌈 explain_message_futimens

void explain_message_futimens(char *message, int message_size, int
fildes, const struct time_spec *data);

The explain_message_futimens function gets you an explanation of an error returned by the futimens(3) system call. you know the drill — 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 what gets used to obtain the error value to be decoded.

• message — the location where the returned message gets stored. and here's the good news: if you supply a suitable message return buffer, this function is thread safe 🥳 main character energy fr
• message_size — the size in bytes of the location where the returned message gets stored.
• fildes — the original fildes, exactly as passed to the futimens(3) system call.
• data — the original data, exactly as passed to the futimens(3) system call.

Example: This function is meant to be used in a fashion similar to this:

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

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

---

💜 explain_message_errno_futimens

void explain_message_errno_futimens(char *message, int message_size, int
errnum, int fildes, const struct time_spec *data);

The explain_message_errno_futimens function gets you an explanation of an error returned by the futimens(3) system call. and yes, the least the message will contain is the value of strerror(errno), but usually it goes way harder and explains the underlying cause in more detail 🌸

• message — the location where the returned message gets stored. if you supply a suitable message return buffer, 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 you're explaining and this function, because many libc functions will alter the value of errno and wreck the whole vibe 🙈
• fildes — the original fildes, exactly as passed to the futimens(3) system call.
• data — the original data, exactly as passed to the futimens(3) system call.

Example: This function is meant to be used in a fashion similar to this:

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

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

---

👑 SEE ALSO 👑

• futimens(3) — change file timestamps with nanosecond precision ⭐
• explain_futimens_or_die(3) — change file timestamps with nanosecond precision and report errors 🔥

---

🎀 COPYRIGHT 🎀

libexplain version 1.4 Copyright (C) 2013 Peter Miller

---

and that's the whole page bestie 💖 libexplain version 1.4, Copyright (C) 2013 Peter Miller — go forth and explain those errors, you absolute legend 🧚✨