explain_linkat_or_die(3)

💖 explain_linkat_or_die — bestie edition 💖

okay so you're deep in the explain_linkat_or_die(3) page of the Library Functions Manual and you need the tea. sit down, hydrate, let's go 🫶

---

✨ NAME ✨

explain_linkat_or_die — link a file relative to directory and report errors. that's the whole vibe, no cap 💅

---

🌸 SYNOPSIS 🌸

#include <libexplain/linkat.h>
void explain_linkat_or_die(int old_dirfd, const char *old_path, int
       new_fildes, const char *new_path, int flags);
int explain_linkat_on_error(int old_dirfd, const char *old_path, int
       new_fildes, const char *new_path, int flags);

like. two functions. both iconic. that's the whole thing 🎀

---

🦋 DESCRIPTION 🦋

so explain_linkat_or_die is the function you call when you wanna call the linkat(2) system call. but here's the twist — if it fails, an explanation gets printed to stderr (pulled straight from the explain_linkat(3) function, slay) and then the process terminates by calling exit(EXIT_FAILURE). it's giving "we don't do partial failure here." dramatic? maybe. effective? absolutely. 💀

and then explain_linkat_on_error is its chill sibling — also calls the linkat(2) system call, also prints that explanation to stderr from explain_linkat(3) on failure, BUT it still returns to the caller. no exit. no drama. just vibes and a return value. 🌈

now the arguments, bestie, all five of them:

• old_dirfd — the old_dirfd, exactly as to be passed to the linkat(2) system call. no notes, pass it through 🫶
• old_path — the old_path, exactly as to be passed to the linkat(2) system call. same energy ✨
• new_fildes — the new_fildes, exactly as to be passed to the linkat(2) system call. yes it's spelled that way, yes it's the parameter name, we don't question it 💅
• new_path — the new_path, exactly as to be passed to the linkat(2) system call. you know the drill 🌸
• flags — the flags, exactly as to be passed to the linkat(2) system call. all of it. unchanged. periodt 👑

---

💜 RETURN VALUE 💜

explain_linkat_or_die only returns on success — check linkat(2) for more info on that. on failure it prints an explanation and exits, so like. it does not return. it's gone. it left the chat. 😭

explain_linkat_on_error always returns the value returned by the wrapped linkat(2) system call. every single time. reliable queen 💖

---

⭐ EXAMPLE ⭐

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

explain_linkat_or_die(old_dirfd, old_path, new_fildes, new_path, flags);

that's it. that's the example. clean, simple, ate 🔥

---

🧚 SEE ALSO 🧚

• linkat(2) — create a file link relative to directory file descriptors
• explain_linkat(3) — explain linkat(2) errors
• exit(2) — terminate the calling process

go read them, iykyk 📚

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2013 Peter Miller

---

and that's the whole page, bestie 🫶 this little love letter to explain_linkat_or_die(3) came to you courtesy of libexplain version 1.4, © 2013 Peter Miller — go forth, link your files relative to directory file descriptors, and may your stderr always be explanatory ✨💖🌸