KEYCTL_SEARCH(2const)

💖 KEYCTL_SEARCH — bestie, let's go find ur key 🔍✨

okay so this is a page from the KEYCTL_SEARCH(2const) manual, and honestly? it's giving treasure hunt. we're searching a keyring tree for a key and getting its ID back. no cap. 🎀

📚 LIBRARY

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

✨ 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_SEARCH, key_serial_t src,
             char *type, char *desc,
             unsigned long dst);

🌸 DESCRIPTION

So basically: we're searching for a key inside a keyring tree, and when we find it we get its ID back — and optionally we can link it into a keyring we pick. iconic behavior honestly. 💖

The tree we're searching is picked by passing the ID of the head keyring in src. The search goes down breadth-first and recursively. (yes bestie, it's methodical. it does not skip steps. main character energy. 👑)

The type and desc arguments say which key we're looking for:

• type holds the key type — a null-terminated character string up to 32 bytes in size, and that size includes the terminating null byte.
• desc holds the key's description — a null-terminated character string up to 4096 bytes in size, also including the terminating null byte. 4096!! big mood.

The source keyring has to grant search permission to the caller. And when it's doing the recursive search, only the keyrings that grant the caller search permission get searched at all. Same energy for the find itself: only keys that the caller has search permission for can actually be found. 🚪✨ (no permission, no entry, periodt.)

If the key is found, its ID is returned as the function result. slay. 💅

If the key is found and dst is nonzero, then — subject to the exact same constraints and rules as KEYCTL_LINK(2const) — the key gets linked into the keyring whose ID is in dst. And heads up: if the destination keyring in dst already has a link to a key with the same type and description, then that link gets displaced by a link to the key this operation found. it's giving "move over, i'm the link now". 💀

Also, instead of valid existing keyring IDs, the source (src) and destination (dst) keyrings can be one of the special keyring IDs listed under KEYCTL_GET_KEYRING_ID(2const). cute little shortcut, iykyk. 🦋

🫶 RETURN VALUE

• On success: the ID of the key that was found. found it, bestie!! 🔥
• On error: -1 is returned, and errno is set to indicate the error. 😭

💀 ERRORS

• EINVAL — the size of the description in desc (including the terminating null byte) exceeded 4096 bytes. too long, babe. the description overflowed. 🙈

🌈 VERSIONS

There's a wrapper for this in the libkeyutils library: keyctl_search(3). use the wrapper, it's lowkey nicer. ✨

⭐ STANDARDS

Linux. 🐧

🧚 HISTORY

Linux 2.6.10. vintage but valid. 💜

👀 SEE ALSO

• keyctl(2)
• keyctl_search(3)

---

mwah 💖 that's the whole page, from the KEYCTL_SEARCH(2const) header at the top to the footer down at the bottom — Linux man-pages 6.20, dated 2026-02-08. go find ur key, bestie, u got this 🎀✨