MLOCK(3POSIX)

👑 MLOCK(3POSIX) 💅

okay so hi bestie 💖 this page lives in the POSIX Programmer's Manual, and it's all about mlock and munlock — the two functions that let your process ✨ pin memory down ✨ so it cannot get yeeted out to swap. Let's get into it, no cap.

---

🌈 PROLOG

Heads up before we even start, bestie: this manual page is part of the POSIX Programmer's Manual. That means the Linux implementation of this interface may differ — like, consult the corresponding Linux manual page for the deets on actual Linux behavior, fr fr. Also possible: the interface may not be implemented on Linux at all. Vibe check first, always. 🫶

---

🎀 NAME

mlock, munlock — lock or unlock a range of process address space (REALTIME)

---

✨ SYNOPSIS

#include <sys/mman.h>

int mlock(const void *addr, size_t len);
int munlock(const void *addr, size_t len);

---

💖 DESCRIPTION

So here's the tea. 🍵

The mlock() function shall cause those whole pages containing any part of the address space of the process starting at address addr and continuing for len bytes to be memory-resident until unlocked, or until the process exits, or until it execs another process image. And just so you know — the implementation may require that addr be a multiple of {PAGESIZE}. Iconic of it to be picky like that. 💅

The munlock() function shall unlock those whole pages containing any part of the address space of the process starting at address addr and continuing for len bytes — and it does this regardless of how many times mlock() has been called by the process for any of the pages in the specified range. Same disclaimer: the implementation may require that addr be a multiple of {PAGESIZE}.

Now the part that's giving shared custody energy, bestie. 😭 If any of the pages in the range specified to a call to munlock() are also mapped into the address spaces of other processes, any locks established on those pages by another process are unaffected by this process's call to munlock(). And if any of the pages in the range specified by a call to munlock() are also mapped into other portions of the address space of the calling process outside the range specified, any locks established on those pages via those other mappings are also unaffected by this call. It's giving "not my range, not my problem." 🙈

Upon successful return from mlock(), pages in the specified range shall be locked and memory-resident. Upon successful return from munlock(), pages in the specified range shall be unlocked with respect to the address space of the process. And the memory residency of unlocked pages? Unspecified. Mystery. Chaos. Main character energy. 🦋

⚠️ Also, real talk: appropriate privileges are required to lock process memory with mlock(). You can't just walk in and pin memory like you own the place. 👑

---

🫶 RETURN VALUE

Upon successful completion, the mlock() and munlock() functions shall return a value of zero. Slay. ✅

Otherwise — and this is the important bit — no change is made to any locks in the address space of the process, and the function shall return a value of -1 and set errno to indicate the error. So it's all-or-nothing, periodt. 💀

---

💅 ERRORS

The mlock() and munlock() functions shall fail if:

• ENOMEM — Some or all of the address range specified by the addr and len arguments does not correspond to valid mapped pages in the address space of the process. Bestie, that range isn't even real. 🫠

The mlock() function shall fail if:

• EAGAIN — Some or all of the memory identified by the operation could not be locked when the call was made. Not right now, try again later energy. 😭

The mlock() and munlock() functions may fail if:

• EINVAL — The addr argument is not a multiple of {PAGESIZE}. Told you it was picky about alignment. 💅

The mlock() function may fail if:

• ENOMEM — Locking the pages mapped by the specified range would exceed an implementation-defined limit on the amount of memory that the process may lock.
• EPERM — The calling process does not have appropriate privileges to perform the requested operation. No privileges, no locking, sorry queen. 🙈

---

The following sections are informative.

---

🌸 EXAMPLES

None. Nothing. Empty. The silence is loud. 🤐

---

🧚 APPLICATION USAGE

None. Also empty. Also iconic. ✨

---

⭐ RATIONALE

None. We're not explaining ourselves today. 💅

---

🌈 FUTURE DIRECTIONS

None. The future is unwritten, bestie. 🦋

---

💜 SEE ALSO

• exec
• exit()
• fork()
• mlockall()
• munmap()

And from the Base Definitions volume of POSIX.1‐2017: <sys_mman.h> 🎀

---

📜 COPYRIGHT

Legal bestie moment, gotta keep it 💯 accurate:

Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between this version and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

Any typographical or formatting errors that appear in this page are most likely to have been introduced during the conversion of the source files to man page format. To report such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .

---

And that's the whole page, bestie — courtesy of IEEE/The Open Group, dated 2017, filed under MLOCK(3POSIX). Lock those pages, stay memory-resident, and don't let anybody swap you out. 💖✨🎀🦋