explain_ftello_or_die(3)

💖 explain_ftello_or_die — bestie edition 💖

okay so this is a page from the Library Functions Manual, and it's about a little function called explain_ftello_or_die, which lowkey does exactly what it says on the tin: it gets your stream position, and if stuff goes wrong it tells you why and then dips. iconic behavior honestly.

---

✨ NAME ✨

explain_ftello_or_die — get stream position and report errors

like. it gets the stream position. and it reports the errors. that's the whole vibe. no cap. 🎀

---

🌸 SYNOPSIS 🌸

#include <libexplain/ftello.h>
off_t explain_ftello_or_die(FILE *fp);
off_t explain_ftello_on_error(FILE *fp);

two functions, one header, both taking a FILE *fp. it's giving duo. ✨

---

🦋 DESCRIPTION 🦋

so here's the tea. 🍓

The explain_ftello_or_die function is used to call the ftello(3) system call. On failure an explanation will be printed to stderr, obtained from the explain_ftello(3) function, and then the process terminates by calling exit(EXIT_FAILURE).

bestie. when it fails, it does not just sulk. it prints a whole explanation to stderr — courtesy of explain_ftello(3) — and then it literally calls exit(EXIT_FAILURE). your process is GONE. main character exit. 💀

The explain_ftello_on_error function is used to call the ftello(3) system call. On failure an explanation will be printed to stderr, obtained from the explain_ftello(3) function, but still returns to the caller.

this one is the chill sibling 🧚 — same explanation printed to stderr, same explain_ftello(3) source, but it comes back to you. it does not leave. it stays. 🫶

• fp — the fp, exactly as to be passed to the ftello(3) system call. like, no edits, no remix, just hand it over as-is. 💅

---

👑 RETURN VALUE 👑

The explain_ftello_or_die function only returns on success, see ftello(3) for more information. On failure, prints an explanation and exits, it does not return.

read that again bestie: it does not return. success only. anything else and you're getting escorted out of the building by exit. 😭

The explain_ftello_on_error function always returns the value return by the wrapped ftello(3) system call.

"always returns the value return by" — yes, that's the original wording, we're keeping it fr fr, it just means it hands you back whatever the wrapped ftello(3) gave. 🌈

---

⭐ EXAMPLE ⭐

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

off_t result = explain_ftello_or_die(fp);

one line. that's it. that's the whole demonstration. ate and left no crumbs. 🔥

---

💜 SEE ALSO 💜

• ftello(3) — get stream position
• explain_ftello(3) — explain ftello(3) errors
• exit(2) — terminate the calling process

the whole squad, assembled. 🎀

---

🎀 COPYRIGHT 🎀

libexplain version 1.4 Copyright (C) 2013 Peter Miller

---

and that's the page, bestie 💖 this whole thing lives in libexplain version 1.4, copyrighted (C) 2013 Peter Miller, and it's the explain_ftello_or_die(3) entry in the Library Functions Manual. go get that stream position. slay. 💅✨