explain_utimes(3)

💖 explain_utimes(3) 💖

okay bestie, so this is a page out of the Library Functions Manual, and it's all about explain_utimes — the glow-up your utimes(2) error messages deserve. she's giving "translator for cryptic syscall failures" and honestly? iconic. 🦋

---

✨ NAME ✨

explain_utimes — explain utimes(2) errors

like, she takes your mysterious errno situation and turns it into actual words. no cap. 💅

---

🌸 SYNOPSIS 🌸

#include <libexplain/utimes.h>
const char *explain_utimes(const char *pathname, const struct timeval
*data);
const char *explain_errno_utimes(int errnum, const char *pathname, const
struct timeval *data);
void explain_message_utimes(char *message, int message_size, const char
*pathname, const struct timeval *data);
void explain_message_errno_utimes(char *message, int message_size, int
errnum, const char *pathname, const struct timeval *data);

four functions. four besties. all here for you. 🫶

---

🎀 DESCRIPTION 🎀

So these functions? They're your little helpers for getting explanations for errors that come back from the utimes(2) system call. Basically: syscall goes wrong, these girls tell you why. 💜

💫 explain_utimes

const char *explain_utimes(const char *pathname, const struct timeval
*data);

The explain_utimes function is here to hand you an explanation of an error that came back from the utimes(2) system call. The least the message will contain is the value of strerror(errno), but usually she does so much better than that and points at the underlying cause in way more detail. lowkey overachiever energy. 🌟

The errno global variable will be used to grab the error value that needs decoding.

• pathname — the original pathname, exactly as passed to the utimes(2) system call. no edits, no glow-up, verbatim bestie.
• data — the original data, exactly as passed to the utimes(2) system call.

Returns: The message explaining the error. This message buffer is shared by all libexplain functions which do not supply a buffer in their argument list. Which means it will be overwritten by the next call to any libexplain function that shares this buffer — including calls from other threads. so like, be careful. 🙈

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. it's giving "communal lip gloss" — cute in theory, chaotic in practice. 💀

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

if (utimes(pathname, data) < 0)
{
    fprintf(stderr, "%s\n", explain_utimes(pathname, data));
    exit(EXIT_FAILURE);
}

The above code example is available pre‐packaged as the explain_utimes_or_die(3) function. she's already ready for you, periodt. 🔥

💫 explain_errno_utimes

const char *explain_errno_utimes(int errnum, const char *pathname, const
struct timeval *data);

The explain_errno_utimes function is used to obtain an explanation of an error returned by the utimes(2) system call. The least the message will contain is the value of strerror(errno), but usually it will do much better, and indicate the underlying cause in more detail. 💖

• 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. so grab it early, bestie, she's slippery. 😭
• pathname — the original pathname, exactly as passed to the utimes(2) system call.
• data — the original data, exactly as passed to the utimes(2) system call.

Returns: The message explaining the error. This message buffer is shared by all libexplain functions which do not supply a buffer in their argument list. This will be overwritten by the next call to any libexplain function which 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.

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

if (utimes(pathname, data) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_utimes(err, pathname,
    data));
    exit(EXIT_FAILURE);
}

The above code example is available pre‐packaged as the explain_utimes_or_die(3) function. 🌈

💫 explain_message_utimes

void explain_message_utimes(char *message, int message_size, const char
*pathname, const struct timeval *data);

The explain_message_utimes function is used to obtain an explanation of an error returned by the utimes(2) system call. The least the message will contain is the value of strerror(errno), but usually it will do much better, and indicate the underlying cause in more detail. ✨

The errno global variable will be 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. look at her go, she grew up. 👑
• message_size — the size in bytes of the location in which to store the returned message.
• pathname — the original pathname, exactly as passed to the utimes(2) system call.
• data — the original data, exactly as passed to the utimes(2) system call.

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

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

The above code example is available pre‐packaged as the explain_utimes_or_die(3) function. 🍓

💫 explain_message_errno_utimes

void explain_message_errno_utimes(char *message, int message_size, int
errnum, const char *pathname, const struct timeval *data);

The explain_message_errno_utimes function is used to obtain an explanation of an error returned by the utimes(2) system call. The least the message will contain is the value of strerror(errno), but usually it will do much better, and indicate 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. yeah, she said what she said. 🫶
• pathname — the original pathname, exactly as passed to the utimes(2) system call.
• data — the original data, exactly as passed to the utimes(2) system call.

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

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

The above code example is available pre‐packaged as the explain_utimes_or_die(3) function. 🌸

---

🦋 SEE ALSO 🦋

• utimes(2) — change file last access and modification times
• explain_utimes_or_die(3) — change file last access and modification times and report errors

go read those next, bestie, they're the sequels. 📚

---

💜 COPYRIGHT 💜

libexplain version 1.4 Copyright (C) 2010 Peter Miller

---

and that's the whole page, no notes. 🎀 this was explain_utimes(3) from the Library Functions Manual, brought to you by libexplain version 1.4, with copyright vibes from 2010, Peter Miller — mwah, thanks for the lore, Peter. 💖 stan a well-documented library. bye bestie, go fix those errnos. 🌟