pkey_alloc(2)

💖 pkey_alloc(2) — bestie, let's talk protection keys

okay so this is a System Calls Manual page, section 2, and it's all about pkey_alloc and pkey_free. Buckle up, we're doing memory protection keys today 🦋

---

✨ NAME ✨

pkey_alloc, pkey_free — allocate or free a protection key

📚 LIBRARY 📚

Standard C library (libc, -lc)

🎀 SYNOPSIS 🎀

#define _GNU_SOURCE             /* See feature_test_macros(7) */
#include <sys/mman.h>

int pkey_alloc(unsigned int flags, unsigned int access_rights);
int pkey_free(int pkey);

💅 DESCRIPTION 💅

So pkey_alloc() allocates a protection key (we call it a pkey, iykyk) and lets you hand it over to pkey_mprotect(2). That's the whole point. 👑

The pkey_alloc() flags argument? Yeah, it's reserved for future use, so right now you literally must always pass it as 0. No cap. Don't try to be cute with it.

The pkey_alloc() access_rights argument can hold zero or more disable operations, and here's the menu:

• PKEY_DISABLE_ACCESS — disables all data access to memory covered by the returned protection key. All of it. Gone. 🙈
• PKEY_DISABLE_WRITE — disables write access to memory covered by the returned protection key.

Then pkey_free() frees a protection key and makes it available again for later allocations. The way that a freed key is just... recyclable ✨. But heads up: after a protection key has been freed, it may no longer be used in any protection-key-related operations. Periodt.

🚨 bestie listen: an application should not call pkey_free() on any protection key that has been assigned to an address range by pkey_mprotect(2) and is still in use. The behavior in that case is undefined and may result in an error. That's not a vibe. That's chaos. 💀

🌈 RETURN VALUE 🌈

• On success, pkey_alloc() returns a positive protection key value. Slay.
• On success, pkey_free() returns zero.
• On error, -1 is returned, and errno is set to indicate the error. 😭

🔥 ERRORS 🔥

• EINVAL — pkey, flags, or access_rights is invalid.
• ENOSPC (from pkey_alloc()) — all protection keys available for the current process have been allocated. The number of keys available is architecture-specific and implementation-specific, and may be reduced by kernel-internal use of certain keys. There are currently 15 keys available to user programs on x86.

This error will also be returned if the processor or operating system does not support protection keys. Applications should always be prepared to handle this error, since factors outside of the application's control can reduce the number of available pkeys. Fr fr, always handle it. 🫶

⭐ STANDARDS ⭐

Linux.

🕰️ HISTORY 🕰️

Linux 4.9, glibc 2.27. Vintage-ish but iconic.

👑 NOTES 👑

pkey_alloc() is always safe to call regardless of whether or not the operating system supports protection keys. You can use it in lieu of any other mechanism for detecting pkey support — it will simply fail with the error ENOSPC if the operating system has no pkey support. Built-in vibe check, honestly. 💖

The kernel guarantees that the contents of the hardware rights register (PKRU) will be preserved only for allocated protection keys. Any time a key is unallocated — either before the first call returning that key from pkey_alloc() or after it is freed via pkey_free() — the kernel may make arbitrary changes to the parts of the rights register affecting access to that key. So like... don't go reading those bits, bestie. The kernel said what it said. 🧚

🍓 EXAMPLES 🍓

See pkeys(7).

🌸 SEE ALSO 🌸

pkey_mprotect(2), pkeys(7)

---

okay that's the whole page, you ate that 💅 this was Linux man-pages 6.20, dated 2026-02-08 — go protect some memory, bestie, and remember: free responsibly 🦋💜