explain_chmod(3)

💖 explain_chmod — bestie edition 💖

okay so this is explain_chmod(3) from the Library Functions Manual, and it's literally the glow-up your error messages deserve. it's all about chmod(2) errors and how to explain them like a main character instead of just going "permission denied 💀". let's get into it 🫶

---

✨ NAME ✨

explain_chmod — explain chmod(2) errors

---

✨ SYNOPSIS ✨

#include <libexplain/chmod.h>
const char *explain_chmod(const char *pathname, int mode);
const char *explain_errno_chmod(int errnum, const char *pathname, int
mode);
void explain_message_chmod(char *message, int message_size, const char
*pathname, int mode);
void explain_message_errno_chmod(char *message, int message_size, int
errnum, const char *pathname, int mode);

---

✨ DESCRIPTION ✨

so these functions? they're the ones you call when chmod(2) said no and you wanna know why. they give you explanations for chmod(2) errors. no cap. 🌸

---

🎀 explain_chmod 🎀

const char *explain_chmod(const char *pathname, int mode);

the explain_chmod function is your go-to for getting an explanation of an error that came back from the chmod(2) system call. the absolute least the message will contain is the value of strerror(errno), but usually it does way better than that and tells you the actual underlying cause in more detail. it's giving detective energy 🔍✨

the errno global variable is what it uses to get the error value it's gonna decode.

this function is meant to be used kinda like this:

if (chmod(pathname, mode) < 0)
{
    fprintf(stderr, '%s0, explain_chmod(pathname, mode));
    exit(EXIT_FAILURE);
}

• pathname — the original pathname, exactly as passed to the chmod(2) system call. like, don't get creative with it, pass the same thing.
• mode — the original mode, exactly as passed to the chmod(2) system call. same deal bestie.

Returns:

the message explaining the error. lowkey important: 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 that shares this buffer — including calls from other threads. 😭

Note: this function is not thread safe, because it shares a return buffer across all threads, and so do many other functions in this library. bestie please be careful with your threads. 🙈

---

🦋 explain_errno_chmod 🦋

const char *explain_errno_chmod(int errnum, const char *pathname, int
mode);

the explain_errno_chmod function does the same thing — it gets you an explanation of an error returned by the chmod(2) system call. the least the message will contain is the value of strerror(errnum), but usually it does much better and points at the actual underlying cause in more detail. iconic behavior honestly 👑

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

if (chmod(pathname) < 0)
{
    int err = errno;
    fprintf(stderr, '%s0, explain_errno_chmod(err, pathname));
    exit(EXIT_FAILURE);
}

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. this matters if you need to run any code between the system call you're explaining and this function, because lots of libc functions will change the value of errno on you. sneak attack fr fr 💀
• pathname — the original pathname, exactly as passed to the chmod(2) system call.
• mode — the original mode, exactly as passed to the chmod(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'll get overwritten by the next call to any libexplain function sharing this buffer, other threads included. 😭

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. 🫶

---

🌸 explain_message_chmod 🌸

void explain_message_chmod(char *message, int message_size, const char
*pathname, int mode);

the explain_message_chmod function is here to obtain an explanation of an error returned by the chmod(2) system call. the least the message will contain is the value of strerror(errno), but usually it does much better and tells you the underlying cause in more detail. she's thorough 💅

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 this example:

if (chmod(pathname, mode) < 0)
{
    char message[3000];
    explain_message_chmod(message, sizeof(message), pathname, mode);
    fprintf(stderr, '%s0, message);
    exit(EXIT_FAILURE);
}

• message — the location in which to store the returned message. and here's the slay: because a message return buffer has been supplied, this function is thread safe. periodt ✨
• 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 chmod(2) system call.
• mode — the original mode, exactly as passed to the chmod(2) system call.

---

🧚 explain_message_errno_chmod 🧚

void explain_message_errno_chmod(char * message, int message_size, int
errnum, const char *pathname, int mode);

the explain_message_errno_chmod function is used to obtain an explanation of an error returned by the chmod(2) system call. the least the message will contain is the value of strerror(errnum), but usually it will do much better than that and indicate the underlying cause in more detail. she ate and left no crumbs 🍓

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

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

• message — the location in which to store the returned message. since a message return buffer has been supplied, this function is thread safe. we love to see it 🌈
• 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. you need this if you have to call any code between the system call being explained and this function, because many libc functions will alter the value of errno. keep it safe bestie 🙈
• pathname — the original pathname, exactly as passed to the chmod(2) system call.
• mode — the original mode, exactly as passed to the chmod(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 cap, that's every last detail. this was explain_chmod(3) from the Library Functions Manual — libexplain version 1.4, Copyright (C) 2008 Peter Miller, written by Peter Miller <pmiller@opensource.org.au>. go explain some chmod(2) errors and be the main character of your own stderr 🌟👑💅