explain_chown(3)

💖 NAME 💖

explain_chown — ok so bestie, this is the girl who explains your chown(2) errors to you in full sentences instead of just yelling "no". It lives in the Library Functions Manual, page explain_chown(3). ✨

---

🎀 SYNOPSIS 🎀

#include <libexplain/chown.h>
const char *explain_chown(const char *pathname, int owner, int group);
const char *explain_errno_chown(int errnum, const char *pathname, int owner, int group);
void explain_message_chown(char *message, int message_size, const char *pathname, int owner, int group);
void explain_message_errno_chown(char *message, int message_size, int errnum, const char *pathname, int owner, int group);

---

🌸 DESCRIPTION 🌸

These functions are literally your emotional support translators for errors that come back from the chown(2) system call. 🫶 You hand them what you handed the kernel, they hand you back a whole explanation.

---

🦋 explain_chown 🦋

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

explain_chown is the one you call to get an explanation of an error returned by the chown(2) system call. The least you're gonna get in that message is the value of strerror(errno), but bestie, usually it does so much better and actually tells you the underlying cause in way more detail. 👑

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 vibe like the following example:

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

• pathname — The original pathname, exactly as passed to the chown(2) system call. No edits, no glow-up.
• owner — The original owner, exactly as passed to the chown(2) system call.
• group — The original group, exactly as passed to the chown(2) system call.

Returns: The message explaining the error. 💌 Heads up though — this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. So it gets overwritten by the next call to any libexplain function sharing that buffer, including calls 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 too. Fr fr, don't fight it.

---

🧚 explain_errno_chown 🧚

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

explain_errno_chown is the version where you bring the errno, because you know the drill. It gives you an explanation of an error returned by the chown(2) system call. The least the message will contain is the value of strerror(errnum), but usually it does way better and points at the underlying cause in more detail. ✨

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

if (chown(pathname, owner, group) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_chown(err, pathname, owner,
        group));
    exit(EXIT_FAILURE);
}

• errnum — The error value to be decoded, usually grabbed from the errno global variable right before this function is called. This is necessary if you need to run any code between the system call being explained and this function, because many libc functions will alter the value of errno. She's fickle like that. 💀
• pathname — The original pathname, exactly as passed to the chown(2) system call.
• owner — The original owner, exactly as passed to the chown(2) system call.
• group — The original group, exactly as passed to the chown(2) system call.

Returns: The message explaining the error. Same tea as before: this message buffer is shared by all libexplain functions which do not supply a buffer in their argument list, and it 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_chown 🌈

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

explain_message_chown may be used to obtain an explanation of an error returned by the chown(2) system call. The least the message will contain is the value of strerror(errno), but usually it does much better and indicates 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 (chown(pathname, owner, group) < 0)
{
    char message[3000];
    explain_message_chown(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. Slay. 👑
• 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 chown(2) system call.
• owner — The original owner, exactly as passed to the chown(2) system call.
• group — The original group, exactly as passed to the chown(2) system call.

---

💜 explain_message_errno_chown 💜

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

explain_message_errno_chown may be used to obtain an explanation of an error returned by the chown(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. 🦋

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

if (chown(pathname, owner, group) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_chown(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. 🙈
• pathname — The original pathname, exactly as passed to the chown(2) system call.
• owner — The original owner, exactly as passed to the chown(2) system call.
• group — The original group, exactly as passed to the chown(2) system call.

---

👀 SEE ALSO 👀

• chown(2) — change ownership of a file
• explain_chown_or_die(3) — change ownership of a file and report errors

---

🎀 COPYRIGHT 🎀

libexplain version 1.4 Copyright (C) 2008 Peter Miller

---

ok that's the whole page bestie, go forth and decode your chown(2) errors with main character energy. 💖✨ this was explain_chown(3) from the Library Functions Manual, brought to you by libexplain version 1.4, Copyright (C) 2008 Peter Miller — mwah, no cap. 🎀🦋💅