KEYCTL_GET_KEYRING_ID(2const)

💖 KEYCTL_GET_KEYRING_ID 💖

okay bestie, gather round, because we're doing a keyctl operation and it's literally the cutest little lookup you've ever seen. this is KEYCTL_GET_KEYRING_ID, a <italic>2const</italic> page from the Linux man-pages, and it's giving "map a special key ID to a real key ID for this process." no cap. that's the whole NAME energy right there. 🎀

---

🫶 LIBRARY

Standard C library (libc, -lc). the usual queen. 💅

---

✨ 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_KEYRING_ID, key_serial_t key,
             int arg3);

yes bestie we're doing the raw syscall() thing. it's giving low-level but make it iconic. 🔥

---

🌸 DESCRIPTION

so the vibe is: map a special key ID to a real key ID for this process. that's it. that's the mission.

this operation looks up the special key whose ID you handed it in key. if the special key is found, the ID of the corresponding real key gets returned as the function result. slay.

here's the menu of what you can put in key, and every single one of these is a real one, don't let anyone tell you otherwise:

• KEY_SPEC_THREAD_KEYRING — this one specifies the calling thread's thread-specific keyring. see thread-keyring(7). 🧵
• KEY_SPEC_PROCESS_KEYRING — this one specifies the caller's process-specific keyring. see process-keyring(7).
• KEY_SPEC_SESSION_KEYRING — this one specifies the caller's session-specific keyring. see session-keyring(7).
• KEY_SPEC_USER_KEYRING — this one specifies the caller's UID-specific keyring. see user-keyring(7). 👑
• KEY_SPEC_USER_SESSION_KEYRING — this one specifies the caller's UID-session keyring. see user-session-keyring(7).
• KEY_SPEC_REQKEY_AUTH_KEY (since Linux 2.6.16) — this one specifies the authorization key created by request_key(2) and passed to the process it spawns to generate a key. this key is available only in a request-key(8)-style program that was passed an authorization key by the kernel, and it ceases to be available once the requested key has been instantiated. see request_key(2). ⭐
• KEY_SPEC_REQUESTOR_KEYRING (since Linux 2.6.29) — this one specifies the key ID for the request_key(2) destination keyring. same deal: available only in a request-key(8)-style program that was passed an authorization key by the kernel, and it ceases to be available once the requested key has been instantiated. see request_key(2). 🦋

okay now the plot twist: what happens if the key you named in key does not exist? that depends entirely on arg3. 💀

• if arg3 contains a nonzero value, then — if it is appropriate to do so (like, e.g., when looking up the user, user-session, or session key) — a new key is created and its real key ID is returned as the function result. new key just dropped. ✨
• otherwise, the operation fails with the error ENOKEY. sad girl hours. 😭

and one more thing, because it's important: if a valid key ID is specified in key, and the key exists, then this operation simply returns the key ID. like, no drama, it just hands it right back to you. but if the key does not exist, the call fails with error ENOKEY. 🙈

🚨 also: the caller must have search permission on a keyring in order for it to be found. no search permission, no keyring. periodt.

---

🌈 RETURN VALUE

• on success: the ID of the requested keyring. 💖
• on error: -1 is returned, and errno is set to indicate the error.

---

💅 ERRORS

• ENOKEY — the key specified in key did not exist, and arg3 was zero (meaning don't create the key if it didn't exist). yeah, you told it not to create one and it also couldn't find one. tragic.

---

🎀 VERSIONS

a wrapper is provided in the libkeyutils library: keyctl_get_keyring_ID(3). iykyk. 🧚

---

⭐ STANDARDS

Linux. obviously. 💜

---

🦋 HISTORY

Linux 2.6.10. vintage, honestly. old money behavior.

---

💜 SEE ALSO

• keyctl(2)
• keyctl_get_keyring_ID(3)

---

and that's the whole page bestie, go forth and look up your keyrings responsibly 🫶

this has been KEYCTL_GET_KEYRING_ID(2const) from the Linux man-pages, version 6.20, dated 2026-02-08. mwah. 💋