AIO_MLOCK(2)

✨ aio_mlock — asynchronous mlock(2) operation ✨

okay bestie, welcome to aio_mlock(2), the FreeBSD system call manual page 💖 this one lives in the System Calls Manual and it's all about locking pages into memory but like… asynchronously. main character energy fr fr.

---

🫶 LIBRARY

Standard C Library (libc, -lc). yes queen, it's right there in libc, you don't have to go hunting 🌸

---

💅 SYNOPSIS

#include <aio.h>

int
aio_mlock(struct aiocb *iocb);

---

🌈 DESCRIPTION

okay so here's the tea ☕ — the aio_mlock() system call lets the calling process lock into memory the physical pages that belong to the virtual address range starting at iocb->aio_buf, for iocb->aio_nbytes bytes. iconic, right?

the call returns immediately after the locking request has been enqueued. so like… the operation may or may not have completed by the time the call comes back. it's giving "don't wait up" 💀

you can subsequently use that iocb pointer as an argument to aio_return() and aio_error() to figure out the return or error status for the enqueued operation while it's still in progress. lowkey genius.

if the request could not be enqueued (generally because of aio(4) limits), then the call just returns without having enqueued the request. no drama, no queue 💔

the iocb->aio_sigevent structure can be used to request notification of the operation's completion, as described in aio(4). get that notif, bestie 🔔

---

🚨 RESTRICTIONS

bestie, read this part, I'm literally begging 🙈 these are the rules and you cannot break them.

• The Asynchronous I/O Control Block structure pointed to by iocb, and the buffer that the iocb->aio_buf member of that structure references, must remain valid until the operation has completed.
• The asynchronous I/O control buffer iocb should be zeroed before the aio_mlock() call, to avoid passing bogus context information to the kernel. zero it out babe, it's not optional-vibes, it's for your own good ✨
• Modifications of the Asynchronous I/O Control Block structure or the memory mapping described by the virtual address range are not allowed while the request is queued. hands off while it's cooking 👑

---

🎀 RETURN VALUES

The aio_mlock() function returns the value 0 if successful 💖 otherwise the value -1 is returned and the global variable errno is set to indicate the error. not the slay we wanted, but at least it tells you why 😭

---

💀 ERRORS

The aio_mlock() system call will fail if:

• [EAGAIN] — The request was not queued because of system resource limitations. the queue said "no room bestie" 🫠
• [EINVAL] — The asynchronous notification method in iocb->aio_sigevent.sigev_notify is invalid or not supported. wrong method, wrong vibe 🚫

if the request is successfully enqueued but then subsequently cancelled or an error occurs:

• the value returned by the aio_return() system call is per the mlock(2) system call 📋
• the value returned by the aio_error() system call is one of the error returns from the mlock(2) system call, or ECANCELED if the request was explicitly cancelled via a call to aio_cancel(). cancelled = ECANCELED, periodt 💅

---

👀 SEE ALSO

aio_cancel(2), aio_error(2), aio_return(2), mlock(2), sigevent(3), aio(4)

go read those too, iykyk 📚

---

🌍 PORTABILITY

The aio_mlock() system call is a FreeBSD extension, and should not be used in portable code. ngl bestie, if you're writing cross-platform code, this is NOT the one. it's a FreeBSD-only moment, no cap 🦋

---

📜 HISTORY

The aio_mlock() system call first appeared in FreeBSD 10.0. a classic, a legend, an icon ⭐

---

👑 AUTHORS

The system call was introduced by Gleb Smirnoff <glebius@FreeBSD.org>. thank you for your service, king 🫡

---

and that's the whole page, bestie!! this little beauty came to you from Debian, dated August 19, 2016 — so yeah, it's been living rent-free in the AIO_MLOCK(2) files since then. lock those pages, zero that iocb, and stay hydrated 💖✨🎀