explain_fchownat_or_die(3)

💖 explain_fchownat_or_die(3) 💖

okay bestie, welcome to the Library Functions Manual section, and this one is literally about changing who owns a file — but relative to a directory, which is the ✨fancy✨ version. 🦋

---

✨ NAME ✨

explain_fchownat_or_die — change ownership of a file relative to a directory and report errors 💅

---

🌸 SYNOPSIS 🌸

#include <libexplain/fchownat.h>
void explain_fchownat_or_die(int dirfd, const char *pathname, int owner,
int group, int flags);
int explain_fchownat_on_error(int dirfd, const char *pathname, int
owner, int group, int flags);

---

🎀 DESCRIPTION 🎀

so there's these two little icons, right, and they both wrap the fchownat(2) system call. but they react to failure VERY differently, and that's the whole tea. ☕

The explain_fchownat_or_die function is used to call the fchownat(2) system call. On failure an explanation will be printed to stderr, obtained from the explain_fchownat(3) function, and then the process terminates by calling exit(EXIT_FAILURE). 💀 like, it does NOT come back. it's giving dramatic exit, no notes.

The explain_fchownat_on_error function is used to call the fchownat(2) system call. On failure an explanation will be printed to stderr, obtained from the explain_fchownat(3) function, but still returns to the caller. 🫶 so chill. so forgiving. main character energy but polite.

now the parameters, one by one, no skipping:

• dirfd — The dirfd, exactly as to be passed to the fchownat(2) system call. like, we're not touching it, we're just handing it over 🎁
• pathname — The pathname, exactly as to be passed to the fchownat(2) system call. same energy, verbatim ✨
• owner — The owner, exactly as to be passed to the fchownat(2) system call. the new owner bestie 👑
• group — The group, exactly as to be passed to the fchownat(2) system call. the new group, matching set 💜
• flags — The flags, exactly as to be passed to the fchownat(2) system call. all the little toggles, untouched 🌈

---

⭐ RETURN VALUE ⭐

The explain_fchownat_or_die function only returns on success — see fchownat(2) for more information. On failure, prints an explanation and exits, it does not return. 😭 so if it comes back to you, that's a W. if it doesn't... that was the point, fr fr.

The explain_fchownat_on_error function always returns the value return by the wrapped fchownat(2) system call. 🍓 yes, always. even the sad values. it's a whole vibe.

---

🌈 EXAMPLE 🌈

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

explain_fchownat_or_die(dirfd, pathname, owner, group, flags);

literally that's it. one line. ate. 💅

---

🧚 SEE ALSO 🧚

• fchownat(2) — change ownership of a file relative to a directory
• explain_fchownat(3) — explain fchownat(2) errors
• exit(2) — terminate the calling process

iykyk, these three are the whole friend group. 👑

---

💜 COPYRIGHT 💜

libexplain version 1.4 Copyright (C) 2013 Peter Miller

---

okay that's the whole page bestie, and since we're at the very bottom, this is the cute sign-off: this little masterpiece lives in libexplain version 1.4, it's Copyright (C) 2013 Peter Miller, and the man page name tag it wears is explain_fchownat_or_die(3). 🎀 go forth and chown responsibly, no cap. 💖✨