explain_futimes(3)

💖 NAME 💖

okay so, bestie, <rainbow>explain_futimes</rainbow> — she explains futimes(3) errors. that's it, that's the whole job, and she ate. 💅

this page lives in the Library Functions Manual, and you're gonna want to keep it in your back pocket, fr fr.

---

✨ SYNOPSIS ✨

#include <libexplain/futimes.h>
const char *explain_futimes(int fildes, const struct timeval *tv);
const char *explain_errno_futimes(int errnum, int fildes, const struct timeval *tv);
void explain_message_futimes(char *message, int message_size, int fildes, const struct timeval *tv);
void explain_message_errno_futimes(char *message, int message_size, int errnum, int fildes, const struct timeval *tv);

---

🦋 DESCRIPTION 🦋

so like, these functions? they're how you get actual explanations for the errors that the futimes(3) system call throws back at you. think of it as the friend who translates cryptic error codes into human feelings. 💖

🌸 explain_futimes 🌸

const char *explain_futimes(int fildes, const struct timeval *tv);

explain_futimes is the one you call when you want the tea on an error that came back from the futimes(3) system call. the bare minimum it'll give you is the value of strerror(errno), but ngl, it usually pops off way harder than that and tells you the actual underlying cause in more detail. 👑

it reads the errno global variable to get the error value it's decoding.

this one's meant to be used in a vibe like this, bestie:

if (futimes(fildes, tv) < 0)
{
    fprintf(stderr, "%s\n", explain_futimes(fildes, tv));
    exit(EXIT_FAILURE);
}

that code right there? it's already available pre-packaged as the explain_futimes_or_die(3) function. iconic behavior.

• fildes — the original fildes, exactly as you passed it to the futimes(3) system call. no edits, no remixes.
• tv — the original tv, exactly as you passed it to the futimes(3) system call. same energy.

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 own argument list. so it gets overwritten by the very next call to any libexplain function that shares this buffer — including calls from other threads. it's giving communal lip gloss, honestly.

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. 💀

🧚 explain_errno_futimes 🧚

const char *explain_errno_futimes(int errnum, int fildes, const struct timeval *tv);

explain_errno_futimes does the same job — it gets you an explanation of an error returned by the futimes(3) system call. the least you'll get is the value of strerror(errnum), but usually it goes so much harder and points at the underlying cause in more detail. ✨

use it kinda like this:

if (futimes(fildes, tv) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_futimes(err, fildes, tv));
    exit(EXIT_FAILURE);
}

yep, this example is also pre-packaged as the explain_futimes_or_die(3) function.

• errnum — the error value you want decoded, usually grabbed from the errno global variable right before you call this function. you need to do that if you're running any code between the system call being explained and this function, because a lot of libc functions will change the value of errno and ruin everything. 😭
• fildes — the original fildes, exactly as passed to the futimes(3) system call.
• tv — the original tv, exactly as passed to the futimes(3) system call.

Returns:

• the message explaining the error. and again: this buffer is shared by all libexplain functions that don't take a buffer in their argument list, so it'll be overwritten by the next call to any libexplain function sharing it, other threads included. 🫠

Note: not thread safe, bestie — shared return buffer across all threads, and plenty of other functions in this library do the same. 💀

🎀 explain_message_futimes 🎀

void explain_message_futimes(char *message, int message_size, int fildes, const struct timeval *tv);

explain_message_futimes is your girl when you want an explanation of an error returned by the futimes(3) system call. minimum content: the value of strerror(errno). but usually? so much better, with the actual underlying cause spelled out in more detail. 💜

it pulls the error value to decode from the errno global variable.

the intended vibe:

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

and yes, pre-packaged as explain_futimes_or_die(3). 🔥

• message — where you want the returned message stored. if you supply a suitable message return buffer, this function is thread safe — look at her, being responsible. 👑
• message_size — the size in bytes of the place where the returned message is going.
• fildes — the original fildes, exactly as passed to the futimes(3) system call.
• tv — the original tv, exactly as passed to the futimes(3) system call.

🌈 explain_message_errno_futimes 🌈

void explain_message_errno_futimes(char *message, int message_size, int errnum, int fildes, const struct timeval *tv);

explain_message_errno_futimes gets you an explanation of an error returned by the futimes(3) system call. at minimum you're getting the value of strerror(errnum), but usually it's way more than that and it names the underlying cause in more detail. no cap. 🍓

use it like:

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

pre-packaged as explain_futimes_or_die(3), obviously. 💅

• message — the location where the returned message gets stored. supply a suitable message return buffer and this function is thread safe. 🫶
• message_size — the size in bytes of the location where the returned message goes.
• errnum — the error value to decode, usually taken from the errno global variable right before calling this function. this matters if you need to run any code between the system call being explained and this function, because loads of libc functions will alter errno. 🙈
• fildes — the original fildes, exactly as passed to the futimes(3) system call.
• tv — the original tv, exactly as passed to the futimes(3) system call.

---

👀 SEE ALSO 👀

• futimes(3) — change file timestamps
• explain_futimes_or_die(3) — change file timestamps and report errors

---

💖 COPYRIGHT 💖

• libexplain version 1.4
• Copyright (C) 2008 Peter Miller

---

and that's the whole page, bestie — explain_futimes(3) from the Library Functions Manual, brought to you by libexplain version 1.4, with Copyright (C) 2008 Peter Miller holding it down at the bottom. go forth and explain your errors, you main character. 🌟💅