explain_mmap(3)

💖 NAME 💖

explain_mmap — ok bestie, it's the function that explains what tf went wrong with mmap(2) 💅

---

✨ SYNOPSIS ✨

#include <libexplain/mmap.h>
const char *explain_mmap(void *data, size_t data_size, int prot, int
flags, int fildes, off_t offset);
const char *explain_errno_mmap(int errnum, void *data, size_t data_size,
int prot, int flags, int fildes, off_t offset);
void explain_message_mmap(char *message, int message_size, void *data,
size_t data_size, int prot, int flags, int fildes, off_t offset);
void explain_message_errno_mmap(char *message, int message_size, int
errnum, void *data, size_t data_size, int prot, int flags, int fildes,
off_t offset);

---

🌸 DESCRIPTION 🌸

Okay so here's the tea 🫖 — these four functions are your little translators. You call mmap(2), it fails, and instead of you squinting at a cryptic number, one of these hands you back an actual explanation of what went wrong. They exist to explain errors returned by the mmap(2) system call. Slay.

🎀 explain_mmap

const char *explain_mmap(void *data, size_t data_size, int prot, int
flags, int fildes, off_t offset);

So explain_mmap gets you an explanation of an error returned by the mmap(2) system call. The bare minimum the message will contain is the value of strerror(errno), but ngl it usually does way better than that and tells you the underlying cause in more detail. It's giving ✨detective energy✨.

It pulls the error value it's decoding from the errno global variable.

• data — the original data, exactly as passed to the mmap(2) system call. No edits, no vibes-based reinterpretation, just as it was 🫶
• data_size — the original data_size, exactly as passed to the mmap(2) system call.
• prot — the original prot, exactly as passed to the mmap(2) system call.
• flags — the original flags, exactly as passed to the mmap(2) system call.
• fildes — the original fildes, exactly as passed to the mmap(2) system call.
• offset — the original offset, exactly as passed to the mmap(2) system call.

Returns: the message explaining the error 💌. Heads up though — this message buffer is shared by all libexplain functions that don't take a buffer in their argument list. So the next call to any libexplain function sharing that buffer will overwrite it. Including calls from other threads. It's a communal water bottle, bestie, and everyone's drinking from it 😭

Note: this function is not thread safe, because it shares a return buffer across all threads — and like, so do many other functions in this library. Not me getting jumpscared by a race condition 💀

Example: you'd use this function kinda like so:

void *result = mmap(data, data_size, prot, flags, fildes,
offset);
if (!result)
{
    fprintf(stderr, "%s\n", explain_mmap(data, data_size, prot,
    flags, fildes, offset));
    exit(EXIT_FAILURE);
}

And the best part?? That code example above is available pre-packaged as the explain_mmap_or_die(3) function. Obsessed. 👑

🦋 explain_errno_mmap

const char *explain_errno_mmap(int errnum, void *data, size_t data_size,
int prot, int flags, int fildes, off_t offset);

explain_errno_mmap gets you an explanation of an error returned by the mmap(2) system call. Least it'll contain is the value of strerror(errno), but usually it does way better and tells you the underlying cause in more detail 💅

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. And why does the timing matter, you ask? Because if you need to run any code between the system call you're explaining and this function, many libc functions will alter the value of errno 😭 so you gotta snag it early.
• data — the original data, exactly as passed to the mmap(2) system call.
• data_size — the original data_size, exactly as passed to the mmap(2) system call.
• prot — the original prot, exactly as passed to the mmap(2) system call.
• flags — the original flags, exactly as passed to the mmap(2) system call.
• fildes — the original fildes, exactly as passed to the mmap(2) system call.
• offset — the original offset, exactly as passed to the mmap(2) system call.

Returns: the message explaining the error 💖. Same deal as before: this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list, and it gets overwritten by the next call to any libexplain function sharing it — other threads included. 🫠

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

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

void *result = mmap(data, data_size, prot, flags, fildes,
offset);
if (!result)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_mmap(err, data,
    data_size, prot, flags, fildes, offset));
    exit(EXIT_FAILURE);
}

And yep — that code example above is also available pre-packaged as the explain_mmap_or_die(3) function. ✨

🧚 explain_message_mmap

void explain_message_mmap(char *message, int message_size, void *data,
size_t data_size, int prot, int flags, int fildes, off_t offset);

explain_message_mmap gets you an explanation of an error returned by the mmap(2) system call. Minimum content: the value of strerror(errno). Usually though? Much better, with the underlying cause spelled out in more detail 🌈

It uses the errno global variable to get the error value it's decoding.

• message — where you want the returned message stored 📥. And the slay here: if you supply a suitable message return buffer, this function is thread safe. Periodt.
• message_size — the size in bytes of the location where you're storing the returned message.
• data — the original data, exactly as passed to the mmap(2) system call.
• data_size — the original data_size, exactly as passed to the mmap(2) system call.
• prot — the original prot, exactly as passed to the mmap(2) system call.
• flags — the original flags, exactly as passed to the mmap(2) system call.
• fildes — the original fildes, exactly as passed to the mmap(2) system call.
• offset — the original offset, exactly as passed to the mmap(2) system call.

Example: use it kinda like this:

void *result = mmap(data, data_size, prot, flags, fildes,
offset);
if (!result)
{
    char message[3000];
    explain_message_mmap(message, sizeof(message), data,
    data_size, prot, flags, fildes, offset);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

You already know what I'm about to say — that code example above is available pre-packaged as the explain_mmap_or_die(3) function. 🎀

💜 explain_message_errno_mmap

void explain_message_errno_mmap(char *message, int message_size, int
errnum, void *data, size_t data_size, int prot, int flags, int fildes,
off_t offset);

explain_message_errno_mmap gets you an explanation of an error returned by the mmap(2) system call. Least it'll contain is the value of strerror(errno), but usually it goes way harder and shows the underlying cause in more detail. Iconic behaviour, honestly.

• message — the location to store the returned message 📬. If a suitable message return buffer is supplied, this function is thread safe — main character energy fr fr.
• message_size — the size in bytes of the location where the returned message goes.
• errnum — the error value to be decoded, usually taken from the errno global variable just before this function is called. This matters if you need to call any code between the system call being explained and this function, because many libc functions will alter the value of errno 😭
• data — the original data, exactly as passed to the mmap(2) system call.
• data_size — the original data_size, exactly as passed to the mmap(2) system call.
• prot — the original prot, exactly as passed to the mmap(2) system call.
• flags — the original flags, exactly as passed to the mmap(2) system call.
• fildes — the original fildes, exactly as passed to the mmap(2) system call.
• offset — the original offset, exactly as passed to the mmap(2) system call.

Example: the vibe is something like this:

void *result = mmap(data, data_size, prot, flags, fildes,
offset);
if (!result)
{
    int err = errno;
    char message[3000];
    explain_message_errno_mmap(message, sizeof(message), err,
    data, data_size, prot, flags, fildes, offset);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

And of course, that code example above is available pre-packaged as the explain_mmap_or_die(3) function. 💖

---

👀 SEE ALSO 👀

• mmap(2) — map file or device into memory
• explain_mmap_or_die(3) — map file or device into memory and report errors

---

📜 COPYRIGHT 📜

That's a wrap, bestie 🫶 — this whole thing is libexplain version 1.4, copyright (C) 2010 Peter Miller. Go forth and explain your mmap(2) errors with confidence, and remember: the buffer is shared, the knowledge is not. 💅✨

explain_mmap(3) — out 🎀