explain_ftruncate(3)

🎀 explain_ftruncate(3) 🎀

okay bestie, so picture this: you call ftruncate(2), it fails, and all you get is a sad little errno number like it's giving cryptic ex energy 🙈. That's where this page comes in. It's the explain_ftruncate manual, and it is literally here to translate your syscall trauma into actual words. Let's go 💅

---

✨ NAME ✨

explain_ftruncate — bestie, this one explains the errors that ftruncate(2) throws at you 🫶

---

🌸 SYNOPSIS 🌸

#include <libexplain/ftruncate.h>
const char *explain_ftruncate(int fildes, long long length);
const char *explain_errno_ftruncate(int errnum, int fildes, long long
length);
void explain_message_ftruncate(char *message, int message_size, int
fildes, long long length);
void explain_message_errno_ftruncate(char *message, int message_size,
int errnum, int fildes, long long length);

---

🦋 DESCRIPTION 🦋

So these four functions are your little support group for errors coming back from the ftruncate(2) system call. They turn the cryptic into the comprehensible, no cap ✨

💖 explain_ftruncate

const char *explain_ftruncate(int fildes, long long length);

explain_ftruncate is the one you call to get an actual explanation of an error that ftruncate(2) handed you. The bare minimum you'll get back is whatever strerror(errno) says — but lowkey it usually does way better than that and tells you the underlying cause in more detail. Iconic behaviour honestly 👑

The errno global variable is the thing it reads to figure out which error value to decode.

It's designed to slot into your code kinda like this:

if (ftruncate(fildes, length) < 0)
{
    fprintf(stderr, "%s\n", explain_ftruncate(fildes, length));
    exit(EXIT_FAILURE);
}

• fildes — the original fildes, exactly as passed to the ftruncate(2) system call. Not a remix, not a vibe-adjacent version. The original 💅
• length — the original length, exactly as passed to the ftruncate(2) system call. Same energy.

Returns:

The message explaining the error. Heads up bestie, this message buffer is shared by all libexplain functions that don't take a buffer in their argument list. It will get overwritten by the next call to any libexplain function that shares this buffer — including calls from other threads. So don't be out here holding onto it like it's yours 😭

Note: This function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library. Fr fr. Not safe. Protect your threads.

💜 explain_errno_ftruncate

const char *explain_errno_ftruncate(int errnum, int fildes, long long
length);

explain_errno_ftruncate does the same explanatory thing for an error returned by ftruncate(2). Least it'll give you is strerror(errnum), but usually it goes off and gives you the underlying cause in much more detail. Slay.

Use it like this:

if (ftruncate(fildes, length) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_ftruncate(err, fildes, length));
    exit(EXIT_FAILURE);
}

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. And yes, that timing matters: you need to do it this way if you have to run any code between the system call you're explaining and this function, because a whole lot of libc functions will mess with the value of errno behind your back 💀
• fildes — the original fildes, exactly as passed to the ftruncate(2) system call.
• length — the original length, exactly as passed to the ftruncate(2) system call.

Returns:

The message explaining the error. And yeah, same warning as before: this message buffer is shared by all libexplain functions which don't supply a buffer in their argument list. It gets overwritten by the next call to any libexplain function that shares this buffer, including other threads. 🫠

Note: This function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library.

🧚 explain_message_ftruncate

void explain_message_ftruncate(char *message, int message_size, int
fildes, long long length);

explain_message_ftruncate is the version that lets you bring the buffer, bestie. You can use it to obtain an explanation of an error returned by the ftruncate(2) system call. Minimum content is the value of strerror(errno), but usually it does much better and points at the underlying cause in more detail ✨

It reads the errno global variable to get the error value to decode.

Like so:

if (ftruncate(fildes, length) < 0)
{
    char message[3000];
    explain_message_ftruncate(message, sizeof(message), fildes, length);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — where you want the returned message stored. And here's the tea: if you supply a suitable message return buffer, this function is thread safe 🎉
• message_size — the size in bytes of the location where you're storing the returned message.
• fildes — the original fildes, exactly as passed to the ftruncate(2) system call.
• length — the original length, exactly as passed to the ftruncate(2) system call.

🌈 explain_message_errno_ftruncate

void explain_message_errno_ftruncate(char *message, int message_size,
int errnum, int fildes, long long length);

explain_message_errno_ftruncate is the main character combo: your buffer and an explicit errnum. Use it to obtain an explanation of an error returned by the ftruncate(2) system call. Least it'll contain is the value of strerror(errnum), but usually it does much better and indicates the underlying cause in more detail 🌸

Example time:

if (ftruncate(fildes, length) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_ftruncate(message, sizeof(message), err,
        fildes, length);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — where the returned message goes. Supply a suitable message return buffer and boom, this function is thread safe 💖
• message_size — the size in bytes of the location where you're storing the returned message.
• errnum — the error value to be decoded, usually obtained from the errno global variable just before this function is called. This is necessary if you need to call any code between the system call to be explained and this function, because many libc functions will alter the value of errno. (Sneaky. So sneaky. 🙈)
• fildes — the original fildes, exactly as passed to the ftruncate(2) system call.
• length — the original length, exactly as passed to the ftruncate(2) system call.

---

👑 SEE ALSO 👑

• ftruncate(2) — truncate a file to a specified length
• explain_ftruncate_or_die(3) — truncate a file and report errors

---

💌 COPYRIGHT 💌

• libexplain version 1.4
• Copyright (C) 2008 Peter Miller

---

and that's the whole page, bestie 🎀 you made it to the end, I'm so proud. go forth and let explain_ftruncate handle your error messages so you never have to squint at a raw errno again. this was explain_ftruncate(3) from libexplain version 1.4, copyright (C) 2008 Peter Miller — mwah, bye 💅✨🦋