explain_stime(3)

💖 explain_stime(3) 💖

okay bestie, pull up a chair, we're talking about explain_stime from the Library Functions Manual — it's a libexplain thing whose whole entire job is explaining the errors that stime(2) throws at you. yes. that's it. that's the gig. and it does it gorgeously. 🦋

---

✨ NAME ✨

explain_stime — explain stime(2) errors 💅

---

✨ SYNOPSIS ✨

#include <libexplain/stime.h>
const char *explain_stime(time_t *t);
const char *explain_errno_stime(int errnum, time_t *t);
void explain_message_stime(char *message, int message_size, time_t *t);
void explain_message_errno_stime(char *message, int message_size, int
errnum, time_t *t);

---

✨ DESCRIPTION ✨

so these functions are your little translators 🫶 — you use them to get explanations for errors returned by the stime(2) system call. that's the whole vibe.

🌸 explain_stime

const char *explain_stime(time_t *t);

the explain_stime function gets you an explanation of an error that the stime(2) system call returned. worst case? the message contains at least the value of strerror(errno). but usually it does so much better and tells you the actual underlying cause in more detail. it's giving detective energy 🔍✨

the errno global variable is what gets used to grab the error value that needs decoding.

• t — the original t, exactly as passed to the stime(2) system call. no edits, no remix, the same t fr fr.

Returns: the message explaining the error. ⚠️ this message buffer is shared by all the 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 from other threads. so don't get attached, bestie 😭

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

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

if (stime(t) < 0)
{
    fprintf(stderr, "%s\n", explain_stime(t));
    exit(EXIT_FAILURE);
}

the above code example is available pre-packaged as the explain_stime_or_die(3) function. iconic, honestly 👑

---

🌸 explain_errno_stime

const char *explain_errno_stime(int errnum, time_t *t);

the explain_errno_stime function gets you an explanation of an error returned by the stime(2) system call. and again, the least the message will contain is the value of strerror(errno), but usually it does way better and points at the underlying cause in more detail. 💅

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. you need this if you have to run any code between the system call being explained and this function, because a lot of libc functions will go and change the value of errno on you. sneaky little things 🙈
• t — the original t, exactly as passed to the stime(2) system call.

Returns: the message explaining the error. ⚠️ same deal as before — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list, and it will be overwritten by the next call to any libexplain function that shares this buffer, other threads included. it's a whole thing.

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

Example: intended to be used in a fashion similar to this:

if (stime(t) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_stime(err, t));
    exit(EXIT_FAILURE);
}

the above code example is available pre-packaged as the explain_stime_or_die(3) function. ✨

---

🌸 explain_message_stime

void explain_message_stime(char *message, int message_size, time_t *t);

the explain_message_stime function gets you an explanation of an error returned by the stime(2) 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. 🫶 and here's the good news: if you supply a suitable message return buffer, this function is thread safe. slay.
• message_size — the size in bytes of the location in which to store the returned message.
• t — the original t, exactly as passed to the stime(2) system call.

Example: intended to be used in a fashion similar to this:

if (stime(t) < 0)
{
    char message[3000];
    explain_message_stime(message, sizeof(message), t);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

the above code example is available pre-packaged as the explain_stime_or_die(3) function. 💖

---

🌸 explain_message_errno_stime

void explain_message_errno_stime(char *message, int message_size, int
errnum, time_t *t);

the explain_message_errno_stime function gets you an explanation of an error returned by the stime(2) 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. no cap. 🔥

• message — the location in which to store the returned message. and yep, if a suitable message return buffer is supplied, this function is thread safe. we love a safe buffer moment.
• 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. 💀
• t — the original t, exactly as passed to the stime(2) system call.

Example: intended to be used in a fashion similar to this:

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

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

---

✨ SEE ALSO ✨

• stime(2) — set system time ⏰
• explain_stime_or_die(3) — set system time and report errors 😌

---

✨ COPYRIGHT ✨

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

---

and that's the whole page, bestie 💜 this was libexplain version 1.4, brought to you by Copyright (C) 2009 Peter Miller, filed lovingly under explain_stime(3). go forth and explain those errors, you absolute main character 👑🦋✨