KEYCTL_JO...ON_KEYRING(3)

💖 KEYCTL_JOIN_SESSION_KEYRING — from the Linux Key Management Calls girlies 💖

okay so bestie, welcome to keyctl_join_session_keyring(3), a page that lives in the Linux Key Management Calls section of your friendly neighbourhood manual. yes the header up top got a lil truncated (KEYCTL_JO...ON_KEYRING(3)) because man pages are dramatic like that, but we know who she is. 🎀

✨ NAME ✨

keyctl_join_session_keyring — literally just: go join a different session keyring. that's the whole job. she's a switcher. 💅

✨ SYNOPSIS ✨

#include <keyutils.h>

key_serial_t keyctl_join_session_keyring(const char *name);

one include, one function, one const char *. we love a minimal icon. 🌸

✨ DESCRIPTION ✨

okay so here's the tea 🫖 — keyctl_join_session_keyring() changes the session keyring that a process is subscribed to. like, it's moving your process into a new group chat. no cap.

now, the vibe of what happens depends entirely on what you pass in as name:

• if name is NULL? a brand new anonymous keyring gets created, and the process gets subscribed to that one. no name, no drama, just a fresh little mystery keyring. ✨
• if name points to a string? then:
  • if a keyring with that name is already available, the process will attempt to subscribe to it — and if that's not permitted, it's an error, periodt. 😭
  • otherwise, a new keyring of that name gets created and attached as the session keyring. glow up achieved. 👑

important bestie: to attach to an extant named keyring, that keyring must have search permission available to the calling process. no search perms, no entry. it's giving velvet rope. 🚫

✨ RETURN VALUE ✨

• on success? she returns the serial number of the key she found or created. 🔥
• on error? you get -1, and errno has been set to an appropriate error. classic.

✨ ERRORS ✨

here's the mood board of ways this can go wrong:

• ENOMEM — not enough memory to create a key. she's running on fumes. 💀
• EDQUOT — creating this key, or linking it to the keyring, would blow past the key quota for this user. budget said no. 🙈
• EACCES — the named keyring exists, but the calling process can't search it. you're outside. looking in. 😭

✨ LINKING ✨

this is a library function and she lives in libkeyutils. when you're linking, you gotta hand the linker -lkeyutils. don't forget her, she'll ghost you. 🦋

✨ SEE ALSO ✨

go read these next, they're all in the same friend group 🫶:

• keyctl(1)
• add_key(2)
• keyctl(2)
• request_key(2)
• keyctl(3)
• keyrings(7)
• keyutils(7)
• session-keyring(7)
• user-session-keyring(7)

and that's the whole page bestie, you ate that 💅✨

this lil masterpiece came from Linux, dated 20 Feb 2014, and she answers to the name KEYCTL_JO...ON_KEYRING(3). mwah, go join a keyring. 🎀💖