explain_lchmod(3)

✨ explain_lchmod ✨

okay bestie, so we're in the Library Functions Manual and today's main character is explain_lchmod(3) 💅 she's here to tell you why your lchmod(2) call said no. no cap.

---

🦋 NAME 🦋

explain_lchmod — the girl who explains your lchmod(2) errors to you, gently, in full sentences 💖

---

🌸 SYNOPSIS 🌸

#include <libexplain/lchmod.h>
const char *explain_lchmod(const char *pathname, mode_t mode);
const char *explain_errno_lchmod(int errnum, const char *pathname,
mode_t mode);
void explain_message_lchmod(char *message, int message_size, const char
*pathname, mode_t mode);
void explain_message_errno_lchmod(char *message, int message_size, int
errnum, const char *pathname, mode_t mode);

---

👑 DESCRIPTION 👑

so these functions are literally your little support system 🫶 you call one of them when lchmod(2) returns an error, and it gives you an explanation of what went wrong. that's the whole vibe. that's the job.

💜 explain_lchmod

const char *explain_lchmod(const char *pathname, mode_t mode);

explain_lchmod gets you an explanation of an error that came back from the lchmod(2) system call. the least you're getting is the value of strerror(errno), but bestie, usually it does so much better than that and tells you the underlying cause in actual detail ✨

the errno global variable is what it peeks at to grab the error value it's gonna decode. she reads the room, basically.

• pathname — the original pathname, exactly as you passed it to the lchmod(2) system call. not edited, not trimmed, the original, periodt.
• mode — the original mode, exactly as passed to the lchmod(2) system call. same energy.

Returns: the message explaining the error 💌 this message buffer is shared by all the libexplain functions that don't take a buffer in their argument list. so the next call to any libexplain function that shares this buffer will overwrite it — and yes, that includes 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. iykyk.

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

if (lchmod(pathname, mode) < 0)
{
    fprintf(stderr, "%s\n", explain_lchmod(pathname, mode));
    exit(EXIT_FAILURE);
}

the above code example is available pre-packaged as the explain_lchmod_or_die(3) function 🎀 (yes she already did the work for you, iconic)

🧚 explain_errno_lchmod

const char *explain_errno_lchmod(int errnum, const char *pathname,
mode_t mode);

explain_errno_lchmod gets you an explanation of an error returned by the lchmod(2) system call. least it'll contain is the value of strerror(errno), but usually it does way better and points at the underlying cause in more detail 🔥

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function gets called. this one's necessary if you need to run any code between the system call you're explaining and this function, because so many libc functions will go and mess with the value of errno 🙈 (rude of them honestly)
• pathname — the original pathname, exactly as passed to the lchmod(2) system call.
• mode — the original mode, exactly as passed to the lchmod(2) system call.

Returns: the message explaining the error 💌 shared buffer situation again — all the libexplain functions that don't supply a buffer in their argument list share it, and the next call to any libexplain function sharing this buffer (other threads included) will overwrite it.

Note: not thread safe, because it shares a return buffer across all threads, and many other functions in this library do too.

Example: intended to be used in a fashion similar to this:

if (lchmod(pathname, mode) < 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_lchmod(err, pathname,
    mode));
    exit(EXIT_FAILURE);
}

the above code example is available pre-packaged as the explain_lchmod_or_die(3) function ✨

🍓 explain_message_lchmod

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

explain_message_lchmod gets you an explanation of an error returned by the lchmod(2) system call. least the message will contain is the value of strerror(errno), but usually it does much better and shows the underlying cause in more detail 💖

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

• message — the location in which to store the returned message. if you supply a suitable message return buffer, this function is thread safe 👑 (look at her go)
• 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 lchmod(2) system call.
• mode — the original mode, exactly as passed to the lchmod(2) system call.

Example: intended to be used in a fashion similar to this:

if (lchmod(pathname, mode) < 0)
{
    char message[3000];
    explain_message_lchmod(message, sizeof(message), pathname,
    mode);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

the above code example is available pre-packaged as the explain_lchmod_or_die(3) function 🌈

🌟 explain_message_errno_lchmod

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

explain_message_errno_lchmod gets you an explanation of an error returned by the lchmod(2) system call. 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 💜

• 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. 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 lchmod(2) system call.
• mode — the original mode, exactly as passed to the lchmod(2) system call.

Example: intended to be used in a fashion similar to this:

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

the above code example is available pre-packaged as the explain_lchmod_or_die(3) function ⭐

---

💅 SEE ALSO 💅

• lchmod(2) — change permissions of a file
• explain_lchmod_or_die(3) — change permissions of a file and report errors

---

🎀 COPYRIGHT 🎀

libexplain version 1.4 Copyright (C) 2012 Peter Miller

---

and that's the whole page, bestie 🦋 libexplain version 1.4, brought to you by Peter Miller with the copyright from 2012 — go forth and let explain_lchmod explain things to you, mwah 💋✨