explain_mmap_or_die(3)

💖 explain_mmap_or_die — Library Functions Manual 💖

okay bestie, pull up a chair, because we're talking about explain_mmap_or_die from the libexplain girlies. this is manual section 3, the library functions one, and she is so iconic for one specific reason: she maps your file or device into memory and then ✨tells you what went wrong✨. no cap.

---

✨ NAME ✨

explain_mmap_or_die — map file or device into memory and report errors 🗺️💅

---

🌸 SYNOPSIS 🌸

#include <libexplain/mmap.h>
void *explain_mmap_or_die(void *data, size_t data_size, int prot, int
flags, int fildes, off_t offset);
void *explain_mmap_on_error(void *data, size_t data_size, int prot, int
flags, int fildes, off_t offset);

two functions, same six args, two very different attitudes. one of them ends you (affectionately) and one of them just… comes back. we'll get there. 🫶

---

🦋 DESCRIPTION 🦋

so, the explain_mmap_or_die function is literally just here to call the mmap(2) system call for you. but here's the tea: if it fails, it prints an explanation to stderr — and that explanation comes straight from the explain_mmap(3) function — and then it terminates your whole process by calling exit(EXIT_FAILURE). that's it. that's the vibe. it does not return on failure. she's dramatic like that. 💀

and then we have explain_mmap_on_error, which is the chill sibling. it also calls the mmap(2) system call, and on failure it also prints an explanation to stderr obtained from the explain_mmap(3) function — but then it still returns to the caller. no exit, no drama, just a lil "hey, that broke, here's why" and you get to keep going. main character energy, honestly. 👑

now let's meet the parameters, because every single one of them is passed through exactly as-is to the mmap(2) system call. no editing, no glow-up, no notes. 💖

• data — the data, exactly as to be passed to the mmap(2) system call.
• data_size — the data_size, exactly as to be passed to the mmap(2) system call.
• prot — the prot, exactly as to be passed to the mmap(2) system call.
• flags — the flags, exactly as to be passed to the mmap(2) system call.
• fildes — the fildes, exactly as to be passed to the mmap(2) system call.
• offset — the offset, exactly as to be passed to the mmap(2) system call.

(yeah, every single one says "exactly as to be passed to the mmap(2) system call." that's not me being lazy, that's the whole point — these are pass-throughs, bestie. she does not touch your args. periodt. 🎀)

---

💜 RETURN VALUE 💜

the explain_mmap_or_die function only returns on success — see mmap(2) for more information. on failure, it prints an explanation and exits. it does not return. like, at all. girl said goodbye and meant it. 😭

the explain_mmap_on_error function, on the other hand, always returns the value return by the wrapped mmap(2) system call. (yes, "return by" — that's the original wording, I'm not fixing it, I'm not touching it, it's canon now. 🙈) so you always get your answer back, for better or for worse.

---

🌈 EXAMPLE 🌈

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

explain_mmap_or_die(data, data_size, prot, flags, fildes, offset);

that's the whole thing. six args, one call, and if the mapping gods say no, she tells you why and then exits. slay. ⭐

---

🎀 SEE ALSO 🎀

• mmap(2) — map file or device into memory
• explain_mmap(3) — explain mmap(2) errors
• exit(2) — terminate the calling process

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2010 Peter Miller

---

and that's the whole page, bestie!! 🫶💖 this was libexplain version 1.4, copyright 2010 Peter Miller — huge thanks to him for the explanation machinery, fr fr. go forth and map some memory, and remember: if it breaks, she'll tell you exactly why. 💅✨🌸🦋🎀