explain_unlink(3)

✨ NAME ✨

okay bestie, gather round 💖 explain_unlink — it explains unlink(2) errors. that's it, that's the whole vibe. no cap.

---

🌸 SYNOPSIS 🌸

#include <libexplain/unlink.h>
const char *explain_unlink(const char *pathname);
void explain_message_unlink(char *message, int message_size, const char *pathname);
const char *explain_errno_unlink(int errnum, const char *pathname);
void explain_message_errno_unlink(char *message, int message_size, int errnum, const char *pathname);

like, four whole functions. we're eating good tonight 🍓

---

💅 DESCRIPTION 💅

so these functions? they're the ones you call when unlink(2) does the absolute most and fails on you 😭. you use them to get actual explanations for unlink(2) errors. obsessed.

🦋 explain_unlink

const char *explain_unlink(const char *pathname);

the explain_unlink function is how you get the tea on an error that unlink(2) returned. the bare minimum the message will contain is the value of strerror(errno), but usually it's gonna do way better than that and actually tell you the underlying cause in more detail. main character energy fr fr ✨

the errno global variable is what gets used to grab the error value to be decoded.

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

if (unlink(pathname) < 0)
{
    fprintf(stderr, '%s0, explain_unlink(pathname));
    exit(EXIT_FAILURE);
}

• pathname — the original pathname, exactly as passed to the unlink(2) system call. like, the exact same one, don't get cute with it.

Returns: the message explaining the error. 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 👀.

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, be careful bestie 💀

💜 explain_errno_unlink

const char *explain_errno_unlink(int errnum, const char * pathname);

the explain_errno_unlink function is how you get the explanation for an error that unlink(2) returned. least it'll contain is the value of strerror(errnum), but usually it goes so much harder and points out the underlying cause in more detail. slay.

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

if (unlink(pathname) < 0)
{
    int err = errno;
    fprintf(stderr, '%s0, explain_errno_unlink(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 is necessary if you need to run any code between the system call you're explaining and this function, because lots of libc functions will alter the value of errno. yes, literally.
• pathname — the original pathname, exactly as passed to the unlink(2) system call.

Returns: the message explaining the error. this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. it will be overwritten by the next call to any libexplain function that shares 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.

🎀 explain_message_unlink

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

the explain_message_unlink function is how you get the explanation for an error returned by the unlink(2) system call. the least the message will contain is the value of strerror(errno), but usually it does so much better and tells you the underlying cause in more detail 🌈.

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

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

if (unlink(pathname) < 0)
{
    char message[3000];
    explain_message_unlink(message, sizeof(message), pathname);
    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. finally, we love to see it 🫶
• 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 unlink(2) system call.

🧚 explain_message_errno_unlink

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

the explain_message_errno_unlink function is how you get the explanation for an error returned by the unlink(2) system call. least the message will contain is the value of strerror(errnum), but usually it does a lot better and indicates the underlying cause in more detail 💖.

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

if (unlink(pathname) < 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_unlink(message, sizeof(message), err,
        pathname);
    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. iconic behaviour tbh 👑
• 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. (yes we said this before, no we will not stop saying it, it's important fr)
• pathname — the original pathname, exactly as passed to the unlink(2) system call.

---

⭐ COPYRIGHT ⭐

libexplain version 1.4

Copyright (C) 2008 Peter Miller

---

🌟 AUTHOR 🌟

written by Peter Miller <pmiller@opensource.org.au> — absolute legend, no notes 💫

---

and that's the whole page bestie 🎀 it's explain_unlink(3), straight outta libexplain version 1.4, copyright 2008 Peter Miller — ty for coming to my ted talk, mwah 💋