KEYCTL_GET_KEYRING_ID(3)

💖 KEYCTL_GET_KEYRING_ID 💖

okay bestie, so this one lives in the Linux Key Management Calls section of the manual (section 3, the library-function girlies), and it's genuinely so useful once you get it. let's go 🫶

✨ NAME ✨

keyctl_get_keyring_ID — the function that gets you the ID of a special keyring. yes, the name is long, yes it's giving "my parents named me after a syscall", we move on 💅

🌸 SYNOPSIS 🌸

#include <keyutils.h>

key_serial_t keyctl_get_keyring_ID(key_serial_t key,
 int create);

like. look at her. two args. one job. iconic.

🦋 DESCRIPTION 🦋

okay so keyctl_get_keyring_ID() does the thing where it maps a special key or keyring ID to the actual serial number of the key that's really representing that feature. and if that key exists? boom, you get the serial number back. that's it, that's the whole vibe.

and if the key or keyring doesn't exist yet? well. if create is non-zero, then the key or keyring gets created — but only if it's appropriate to do so. (the manpage is being mysterious about "appropriate" and honestly? same.)

these are the special key IDs you're allowed to pass in as key, and they are not interchangeable, so pay attention bestie:

• KEY_SPEC_THREAD_KEYRING — this one specifies the caller's thread-specific keyring. yes, per-thread. your threads each get their own. main character energy for every single thread 🌈
• KEY_SPEC_PROCESS_KEYRING — this specifies the caller's process-specific keyring. so, one per process.
• KEY_SPEC_SESSION_KEYRING — this specifies the caller's session-specific keyring. the session one. you know the one.
• KEY_SPEC_USER_KEYRING — this specifies the caller's UID-specific keyring. keyed off your UID, not your vibes.
• KEY_SPEC_USER_SESSION_KEYRING — this specifies the caller's UID-session keyring. yes it's a different thing from the previous two, no you may not merge them, they are siblings not twins 😭
• KEY_SPEC_REQKEY_AUTH_KEY — this specifies the authorisation key created by request_key() and passed to the process it spawns to generate a key. very specific, very niche, very "you'll know if you need it" ✨

and then the last little rule, which is important so don't skip it: if a valid keyring ID is passed in, then this will simply be returned — if the key exists. and if it doesn't exist? an error gets issued. no key, no serial, no mercy 💀

🔥 RETURN VALUE 🔥

• on success, keyctl_get_keyring_ID() returns the serial number of the key it found. slay. 👑
• on error, the value -1 gets returned and errno will have been set to an appropriate error. so like, check errno, bestie, don't just stare at the -1.

💜 ERRORS 💜

• ENOKEY — no matching key was found. she looked. she did not find. 🙈
• ENOMEM — insufficient memory to create a key. out of RAM, out of luck.
• EDQUOT — the key quota for this user would be exceeded by creating this key or linking it to the keyring. you hit your limit, babe, and the limit hit back.

🎀 LINKING 🎀

this is a library function and it can be found in libkeyutils. so when you're linking, you need to pass -lkeyutils to the linker. that's it. that's the whole tip. do not forget it or the linker will simply Not. 🫠

⭐ SEE ALSO ⭐

keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3), keyrings(7), keyutils(7)

go read those too, they're all in the group chat 📚

ngl, the create flag is lowkey the whole plot twist of this function — everything else is just mapping. treat it with respect. 💖

and that's the page, bestie!! this one's from Linux, dated 4 May 2006 — yeah, she's an elder icon but she still ate 💅✨ bye ily, go link with -lkeyutils 🦋🌸