explain_lstat(3)

💖 explain_lstat(3) — Library Functions Manual 💖

okay bestie, sit DOWN, because this is the page that explains your lstat(3) errors for you 💅 it lives in the libexplain library, and honestly? it's giving "emotional support for your errno" energy. let's go 🦋

---

✨ NAME ✨

explain_lstat — explain lstat(3) errors 🌸

---

✨ SYNOPSIS ✨

#include <libexplain/lstat.h>
const char *explain_lstat(const char *pathname, const struct stat *buf);
void explain_message_lstat(char *message, int message_size, const char
*pathname, const struct stat *buf);
const char *explain_errno_lstat(int errnum, const char *pathname, const
struct stat *buf);
void explain_message_errno_lstat(char *message, int message_size, int
errnum, const char *pathname, const struct stat *buf);

like, four whole functions, all yours, no cap 👑

---

✨ DESCRIPTION ✨

These functions may be used to obtains explanations for lstat(2) errors.

(that "obtains" is the original's wording, bestie, I'm not fixing it, I'm a respectful queen 🙈)

---

🌟 explain_lstat 🌟

const char *explain_lstat(const char *pathname, const struct stat *buf);

The explain_lstat function is used to obtain an explanation of an error returned by the lstat(2) function. 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. like it's literally overachieving 💅

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

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

if (lstat(pathname, &buf) < 0)
{
    fprintf(stderr, '%s0, explain_lstat(pathname, &buf));
    exit(EXIT_FAILURE);
}

yes, that '%s0, is exactly how it appears in the source page. copying it character for character because I keep it 💯

• pathname — The original pathname, exactly as passed to the lstat(2) system call.
• buf — The original buf, exactly as passed to the lstat(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. 🚨 so if you're threading, bestie, you have been warned 🚨

---

🌟 explain_errno_lstat 🌟

const char *explain_errno_lstat(int errnum, const char *pathname, const struct stat *buf);

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

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

if (lstat(pathname, &buf) < 0)
{
    int err = errno;
    fprintf(stderr, '%s0, explain_errno_lstat(err, pathname, &buf));
    exit(EXIT_FAILURE);
}

• 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. ⚠️ like, errno is fickle, she changes her mind, save her early ⚠️
• pathname — The original pathname, exactly as passed to the lstat(2) system call.
• buf — The original buf, exactly as passed to the lstat(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.

---

🌟 explain_message_lstat 🌟

void explain_message_lstat(char *message, int message_size, const char
*pathname, const struct stat *buf);

The explain_message_lstat function is used to obtain an explanation of an error returned by the lstat(2) function. 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.

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

if (lstat(pathname, &buf) < 0)
{
    char message[3000];
    explain_message_lstat(message, sizeof(message), pathname, &buf);
    fprintf(stderr, '%s0, message);
    exit(EXIT_FAILURE);
}

• message — The location in which to store the returned message. Because a message return buffer has been supplied, this function is thread safe. 🎀 yes bestie, YOU brought the buffer, so YOU get the thread safety 🎀
• message_size — The size in bytes of the location in which to store the returned message.
• pathname — The original pathname, exactly as passed to the lstat(2) system call.
• buf — The original buf, exactly as passed to the lstat(2) system call.

---

🌟 explain_message_errno_lstat 🌟

void explain_message_errno_lstat(char *message, int message_size, int
errnum, const char *pathname, const struct stat *buf);

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

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

if (lstat(pathname, &buf) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_lstat(message, sizeof(message), err,
        pathname, &buf);
    fprintf(stderr, '%s0, message);
    exit(EXIT_FAILURE);
}

• message — The location in which to store the returned message. Because a message return buffer has been 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. 💀 grab it early, girl, grab it early 💀
• pathname — The original pathname, exactly as passed to the lstat(2) system call.
• buf — The original buf, exactly as passed to the lstat(2) system call.

---

✨ COPYRIGHT ✨

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

✨ AUTHOR ✨

Written by Peter Miller <pmiller@opensource.org.au>

---

and that's the whole page, bestie 💖 no SEE ALSO to chase down, no options list to memorise, just four functions and a whole lot of thread-safety lore 🧚 this little page is explain_lstat(3) from the Library Functions Manual, rocking libexplain version 1.4 with Copyright (C) 2008 Peter Miller — so go forth, explain your errno, and slay 💅✨🦋