explain_lchown(3)

💖 explain_lchown(3) — Library Functions Manual 💖

okay bestie, gather round, because we're about to talk about explain_lchown from the Library Functions Manual section, and honestly? it's giving error-decoding royalty. 👑

---

✨ NAME ✨

explain_lchown — explain lchown(2) errors 🫶

---

✨ SYNOPSIS ✨

#include <libexplain/lchown.h>
const char *explain_lchown(const char *pathname, int owner, int group);
const char *explain_errno_lchown(int errnum, const char *pathname, int owner, int group);
void explain_message_lchown(char *message, int message_size, const char *pathname, int owner, int group);
void explain_message_errno_lchown(char *message, int message_size, int errnum, const char *pathname, int owner, int group);

---

✨ DESCRIPTION ✨

so like, these functions? they're your little besties for getting explanations when the lchown(2) system call throws hands and returns an error. 💅 they don't just tell you that something broke — they tell you why, and they do it with main character energy.

---

🌸 explain_lchown 🌸

const char *explain_lchown(const char *pathname, int owner, int group);

the explain_lchown function is literally the way to get an explanation of an error that came back from the lchown(2) system call. the absolute bare minimum the message will contain is the value of strerror(errno) — but lowkey, usually it does so much better and points at the underlying cause in way more detail. no cap. ✨

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

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

if (lchown(pathname, owner, group) < 0)
{
    fprintf(stderr, "%s\n", explain_lchown(pathname, owner, group));
    exit(EXIT_FAILURE);
}

• pathname — the original pathname, exactly as passed to the lchown(2) system call. like, exactly. don't be editing it, bestie. 🎀
• owner — the original owner, exactly as passed to the lchown(2) system call.
• group — the original group, exactly as passed to the lchown(2) system call.

Returns:

the message explaining the error. 💌 but listen — 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 other threads. so don't be clinging to it like it's yours, because it is NOT. 😭

Note: this function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library. it's giving "communal apartment" energy and not in a cute way. 💀

---

🦋 explain_errno_lchown 🦋

const char *explain_errno_lchown(int errnum, const char *pathname, int owner, int group);

the explain_errno_lchown function is used to obtain an explanation of an error returned by the lchown(2) system call. the least the message will contain is the value of strerror(errnum), but usually it does much better and indicates the underlying cause in more detail. iconic behaviour, honestly. 🌈

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

if (lchown(pathname, owner, group) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_lchown(err,
        pathname, owner, group));
    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. so like, grab it early or it's gone, fr fr. 🙈
• pathname — the original pathname, exactly as passed to the lchown(2) system call.
• owner — the original owner, exactly as passed to the lchown(2) system call.
• group — the original group, exactly as passed to the lchown(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. same communal-buffer situation, bestie, we don't make the rules. 💀

---

🎀 explain_message_lchown 🎀

void explain_message_lchown(char *message, int message_size, const char *pathname, int owner, int group);

the explain_message_lchown function may be used to obtain an explanation of an error returned by the lchown(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. she's thorough. she's that girl. 👑

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 (lchown(pathname, owner, group) < 0)
{
    char message[3000];
    explain_message_lchown(message, sizeof(message),
        pathname, owner, group);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• message — the location in which to store the returned message. if a suitable message return buffer is supplied, this function is thread safe. 🫶 the glow-up we've been waiting for!!
• 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 lchown(2) system call.
• owner — the original owner, exactly as passed to the lchown(2) system call.
• group — the original group, exactly as passed to the lchown(2) system call.

---

🧚 explain_message_errno_lchown 🧚

void explain_message_errno_lchown(char *message, int message_size, int errnum, const char *pathname, int owner, int group);

the explain_message_errno_lchown function may be used to obtain an explanation of an error returned by the lchown(2) system call. 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. the whole package. the moment. ⭐

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

if (lchown(pathname, owner, group) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_lchown(message, sizeof(message), err,
        pathname, owner, group);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

• 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. 😭 grab it fast!!
• pathname — the original pathname, exactly as passed to the lchown(2) system call.
• owner — the original owner, exactly as passed to the lchown(2) system call.
• group — the original group, exactly as passed to the lchown(2) system call.

---

✨ SEE ALSO ✨

• lchown(2) — change ownership of a file 🍓
• explain_lchown_or_die(3) — change ownership of a file and report errors 💖

---

✨ COPYRIGHT ✨

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

and that's the whole page, bestie!! 🎀 you just read explain_lchown(3) from libexplain version 1.4, with Copyright (C) 2008 Peter Miller riding shotgun. go forth and decode those errors like the main character you are. 💅✨👑