explain_ustat(3)

💖 explain_ustat(3) 💖

okay bestie, so you know explain_ustat? it's a whole libexplain thing. this page lives in the Library Functions Manual section, and it's here to teach you how to turn ustat(2) errors into actual human-readable explanations instead of just staring at errno like 👁️👄👁️. no cap.

---

✨ NAME ✨

explain_ustat — explain ustat(2) errors

---

🌸 SYNOPSIS 🌸

#include <libexplain/ustat.h>
const char *explain_ustat(dev_t dev, struct ustat *ubuf);
const char *explain_errno_ustat(int errnum, dev_t dev, struct ustat
*ubuf);
void explain_message_ustat(char *message, int message_size, dev_t dev,
struct ustat *ubuf);
void explain_message_errno_ustat(char *message, int message_size, int
errnum, dev_t dev, struct ustat *ubuf);

---

🦋 DESCRIPTION 🦋

so like, these functions are the whole point: you use them to get explanations for errors that the ustat(2) system call hands back to you. basically it's the difference between "something broke" and "here's exactly why it broke, bestie". 💅

---

🎀 explain_ustat 🎀

const char *explain_ustat(dev_t dev, struct ustat *ubuf);

the explain_ustat function is your girl for getting an explanation of an error returned by the ustat(2) system call. the bare minimum it'll give you is the value of strerror(errno), but honestly? it usually does wayyy better than that and tells you the actual underlying cause in more detail. it's giving ✨thorough✨.

the errno global variable is the one that gets used to grab the error value that needs decoding.

• dev — the original dev, exactly as passed to the ustat(2) system call. no edits, no vibes-based reinterpretation.
• ubuf — the original ubuf, exactly as passed to the ustat(2) system call.

Returns: the message explaining the error. heads up tho — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. it will get overwritten by the next call to any libexplain function that shares this buffer, including from 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 do the same. so like, be careful, fr fr.

Example: this function is meant to be used in a fashion similar to the following example:

if (ustat(dev, ubuf) < 0)
{
    fprintf(stderr, "%s\n", explain_ustat(dev, ubuf));
    exit(EXIT_FAILURE);
}

the above code example is available pre‐packaged as the explain_ustat_or_die(3) function. so you don't even have to write it yourself, iconic. 👑

---

🍓 explain_errno_ustat 🍓

const char *explain_errno_ustat(int errnum, dev_t dev, struct ustat
*ubuf);

the explain_errno_ustat function is used to obtain an explanation of an error returned by the ustat(2) system call. the least the message will contain is the value of strerror(errno), but usually it will do much better, and indicate the underlying cause in more detail. (yes bestie, same energy as above, but this time you're passing the error in yourself. main character move.)

• 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. so grab it early or it's gone 💀
• dev — the original dev, exactly as passed to the ustat(2) system call.
• ubuf — the original ubuf, exactly as passed to the ustat(2) system call.

Returns: the message explaining the error. this message buffer is shared by all libexplain functions which do not supply a buffer in their argument list. this will be overwritten by the next call to any libexplain function which 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.

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

if (ustat(dev, ubuf) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_ustat(err, dev, ubuf));
    exit(EXIT_FAILURE);
}

the above code example is available pre‐packaged as the explain_ustat_or_die(3) function. 💖

---

🧚 explain_message_ustat 🧚

void explain_message_ustat(char *message, int message_size, dev_t dev,
struct ustat *ubuf);

the explain_message_ustat function is used to obtain an explanation of an error returned by the ustat(2) system call. the least the message will contain is the value of strerror(errno), but usually it will do much better, and indicate the underlying cause in more detail.

the errno global variable will be used to obtain the error value to be decoded.

• message — the location in which to store the returned message. if a suitable message return buffer is supplied, this function is thread safe. look at you, being all safe 🫶
• message_size — the size in bytes of the location in which to store the returned message.
• dev — the original dev, exactly as passed to the ustat(2) system call.
• ubuf — the original ubuf, exactly as passed to the ustat(2) system call.

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

if (ustat(dev, ubuf) < 0)
{
    char message[3000];
    explain_message_ustat(message, sizeof(message), dev, ubuf);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

the above code example is available pre‐packaged as the explain_ustat_or_die(3) function. slay. 💅

---

🌈 explain_message_errno_ustat 🌈

void explain_message_errno_ustat(char *message, int message_size, int
errnum, dev_t dev, struct ustat *ubuf);

the explain_message_errno_ustat function is used to obtain an explanation of an error returned by the ustat(2) system call. the least the message will contain is the value of strerror(errno), but usually it will do much better, and indicate the underlying cause in more detail.

• message — the location in which to store the returned message. if a suitable message return buffer is supplied, this function is thread safe.
• message_size — the size in bytes of the location in which to store 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.
• dev — the original dev, exactly as passed to the ustat(2) system call.
• ubuf — the original ubuf, exactly as passed to the ustat(2) system call.

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

if (ustat(dev, ubuf) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_ustat(message, sizeof(message), err,
    dev, ubuf);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

the above code example is available pre‐packaged as the explain_ustat_or_die(3) function. ✨

---

👑 SEE ALSO 👑

• ustat(2) — get file system statistics
• explain_ustat_or_die(3) — get file system statistics and report errors

---

💜 COPYRIGHT 💜

okay so the boring-but-important bit, periodt:

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

---

and that's the whole page bestie, you ate it up 🎀 the manual name is explain_ustat(3) and this whole thing comes from libexplain version 1.4, copyright (C) 2009 Peter Miller — go forth and explain those ustat(2) errors like the icon you are 💖✨🦋