EXPLAIN_UTIMENSAT_OR_DIE(3)

💖 explain_utimensat_or_die(3) 💖

okay bestie, sit down, hydrate, because we're talking about explain_utimensat_or_die(3) from the Library Functions Manual. this is the girl who changes your file timestamps and then, if things go sideways, tells you exactly why before she dramatically exits the group chat. 💅

---

✨ NAME ✨

explain_utimensat_or_die — change file timestamps and report errors

---

🌸 SYNOPSIS 🌸

#include <libexplain/utimensat.h>
void explain_utimensat_or_die(int fildes, const char *pathname, const struct timespec *data, int flags);
int explain_utimensat_on_error(int fildes, const char *pathname, const struct timespec *data, int flags);

like. two functions. one of them is the dramatic one and one of them is the chill one. we love a duo. 🫶

---

🦋 DESCRIPTION 🦋

so the explain_utimensat_or_die function is literally just here to call the utimensat(2) system call for you. that's the job. that's the whole vibe.

but here's the tea ☕ — if it fails, it prints an explanation to stderr (obtained from the explain_utimensat(3) function, she's the source of all the gossip), and then the process terminates by calling exit(EXIT_FAILURE). like, no survivors. it's giving main character exit. 💀

meanwhile explain_utimensat_on_error is the same deal — it also calls the utimensat(2) system call, and on failure it also prints an explanation to stderr, also obtained from the explain_utimensat(3) function — but she's emotionally stable and still returns to the caller. no exiting. no drama. just information. ✨

and now the arguments, one by one, no skipping, we don't do that here:

• fildes — the fildes, exactly as to be passed to the utimensat(2) system call. literally exactly. don't get creative with it bestie.
• pathname — the pathname, exactly as to be passed to the utimensat(2) system call. same energy, same rule.
• data — the data, exactly as to be passed to the utimensat(2) system call. yes, still exactly.
• flags — the flags, exactly as to be passed to the utimensat(2) system call. you already know the rule by now. 🎀

---

🔥 RETURN VALUE 🔥

explain_utimensat_or_die only ever returns on success — and if you wanna know more about what success looks like, go read utimensat(2), she explains it better. on failure? it prints an explanation and exits. it does not return. not ever. not even a little. 😭

explain_utimensat_on_error always returns the value returned by the wrapped utimensat(2) system call. always. she's consistent like that. 👑

---

🌈 EXAMPLE 🌈

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

explain_utimensat_or_die(fildes, pathname, data, flags);

that's it. that's the example. iconic, honestly. no notes. ⭐

---

💜 SEE ALSO 💜

• utimensat(2) — change file timestamps with nanosecond precision
• explain_utimensat(3) — explain utimensat(2) errors
• exit(2) — terminate the calling process

go read all three, bestie, they're all bangers. iykyk. 🌸

---

🎀 COPYRIGHT 🎀

libexplain version 1.4

Copyright (C) 2012 Peter Miller

---

and that's the whole page, we ate and left no crumbs 💅 this was explain_utimensat_or_die(3) — libexplain version 1.4, copyright (C) 2012 Peter Miller — signing off, mwah 🫶✨💖