KEYCTL_GET_PERSISTENT(2const)

💖 KEYCTL_GET_PERSISTENT 💖

okay bestie, welcome to KEYCTL_GET_PERSISTENT(2const) — a lil slice of the Linux man pages, no cap. this one is about snagging a user's persistent keyring and linking it somewhere, and honestly? it's giving ✨immortal key storage✨. let's get into it 🫶

🌸 NAME 🌸

KEYCTL_GET_PERSISTENT — get the persistent keyring for a user

📚 LIBRARY 📚

Standard C library (libc, -lc) — the classic, the icon, the one you already have 💅

✨ SYNOPSIS ✨

#include <linux/keyctl.h>  /* Definition of KEY* constants */
#include <sys/syscall.h>   /* Definition of SYS_* constants */
#include <unistd.h>

long syscall(SYS_keyctl, KEYCTL_GET_PERSISTENT, uid_t uid,
             key_serial_t keyring);

heads up: you're going in raw through syscall(2) here, no glow-up wrapper in sight 😭 (well, mostly — check VERSIONS below, bestie)

---

💅 DESCRIPTION 💅

so what does this thing do? it gets the persistent keyring — that's persistent-keyring(7), the long-lived girlie — for a specified user, and links it to a specified keyring. two things, one syscall, main character energy 👑

the user ID goes in uid. and here's the cute part: if you pass the value -1, the caller's real user ID is used instead. lazy but valid, we love that for you 🎀

the ID of the destination keyring goes in keyring.

now, permissions check time, because the kernel will vibe check you 🔍. the caller must have the CAP_SETUID capability in its user namespace in order to fetch the persistent keyring for a user ID that does not match either the real or effective user ID of the caller. so like… fetching your own? fine. fetching someone else's? you better have the receipts 📜✨

if the call succeeds, a link to the persistent keyring gets added to the keyring whose ID you put in keyring. and — very important — the caller must have write permission on that keyring. no write perm, no link, periodt 💀

and don't worry about whether the persistent keyring exists yet: the kernel will create it if it doesn't yet exist. she's a self-starter 🦋

each time the KEYCTL_GET_PERSISTENT operation is performed, the persistent keyring has its expiration timeout reset to the value in:

/proc/sys/kernel/keys/persistent_keyring_expiry

so every call is basically a lil "hey, still alive? 💖" text message that refreshes the timer.

⚠️ but if that timeout is reached, the persistent keyring gets removed — and everything it pins can then be garbage collected. bye bestie, it was real 😭🗑️

also, tiny lore drop: persistent keyrings were added in Linux 3.13.

---

🫶 RETURN VALUE 🫶

• on success — the ID of the persistent keyring. slay 🎀
• on error — -1 is returned, and errno is set to indicate the error. classic 😔

---

🚨 ERRORS 🚨

• EPERM — uid specified a UID other than the calling thread's real or effective UID, and the caller did not have the CAP_SETUID capability. yeah… you tried it 🙈

---

🌈 VERSIONS 🌈

a wrapper is provided in the libkeyutils library: keyctl_get_persistent(3). so if raw syscall(2) isn't your vibe, there's a friendlier door to knock on 💜

---

⭐ STANDARDS ⭐

Linux. that's it, that's the tea ☕ (Linux-only, bestie, iykyk)

---

🕰️ HISTORY 🕰️

Linux 3.13.

---

👀 SEE ALSO 👀

• keyctl(2)
• keyctl_get_persistent(3)

---

and that's the whole page, fr fr 💖 this one came from Linux man-pages 6.20, dated 2026-02-08, filed under KEYCTL_GET_PERSISTENT(2const) — go forth and keyring responsibly, bestie, you got this 🌸✨🦋