explain_utimens_or_die(3)

💅 explain_utimens_or_die(3) 💅

okay bestie, sit down, we're doing libexplain's little timestamp-gremlin today. this one lives in the Library Functions Manual section of your man pages, and it's genuinely so useful once you get it. no cap.

---

✨ NAME ✨

explain_utimens_or_die — change file timestamps and report errors 🕰️

like, it changes the timestamps on a file, and if it can't? it tells you why. main character energy fr.

---

🌸 SYNOPSIS 🌸

#include <libexplain/utimens.h>
void explain_utimens_or_die(const char *pathname, const struct timespec
*data);
int explain_utimens_on_error(const char *pathname, const struct timespec
*data);

two functions, one header, zero drama (well, okay, some drama — that's literally the point).

---

💖 DESCRIPTION 💖

so there's two of them and they're like sisters, one's the chaotic one and one's the chill one.

explain_utimens_or_die is the chaotic one 💀. you call it, it calls the utimens(2) system call for you. if that call fails, it prints an explanation to stderr — and that explanation comes straight from the explain_utimens(3) function, which is the whole reason libexplain exists, it's giving translator-for-errno energy — and then it terminates the process by calling exit(EXIT_FAILURE). so yeah. it does not come back. it's not coming back. 🙈

explain_utimens_on_error is the chill one ✨. it also calls utimens(2), and on failure it also prints that same explanation from explain_utimens(3) to stderr — but then it just... returns to you. like a grownup. you keep your process, you keep your vibes. 🫶

and here's the tea on the arguments, both functions take the exact same two:

• pathname — the pathname, exactly as to be passed to the utimens(2) system call. don't get creative with it, bestie, it gets handed straight through. 🛣️
• data — the data, exactly as to be passed to the utimens(2) system call. same deal. hand it over untouched. 📦

⚠️ notice how both say "exactly as to be passed"? that's not decoration. these wrappers are transparent, they don't massage your arguments, so whatever you give them is what utimens(2) sees. iykyk.

---

👑 RETURN VALUE 👑

explain_utimens_or_die only returns on success — and if you wanna know what "success" even means here, go read utimens(2), it's all in there. on failure? it prints an explanation and exits. it does not return. periodt. 💀

explain_utimens_on_error always returns the value returned by the wrapped utimens(2) system call. so like, it's a faithful little mirror of whatever the syscall said. 🌈

---

🎀 EXAMPLE 🎀

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

explain_utimens_or_die(pathname, data);

that's it. that's the whole vibe. one line, and if it goes wrong you get a real explanation instead of a cryptic EACCES and a prayer. iconic. 🦋

---

🔥 SEE ALSO 🔥

• utimens(2) — change file last access and modification times
• explain_utimens(3) — explain utimens(2) errors
• exit(2) — terminate the calling process

---

💜 COPYRIGHT 💜

libexplain version 1.4 Copyright (C) 2012 Peter Miller

---

okay so that's the whole page, bestie — go forth and timestamp responsibly 🌸💅✨

this has been explain_utimens_or_die(3) from the Library Functions Manual, libexplain version 1.4, copyright 2012 Peter Miller, mwah 🫶🎀