RECURSIVE_KEY_SCAN(3)

💖 RECURSIVE_KEY_SCAN(3) 💖

okay bestie, so this is a page from the Linux Key Utility Calls manual, and it's literally the blueprint for walking a whole keyring tree like the main character you are ✨

🌸 NAME 🌸

recursive_key_scan, recursive_session_key_scan — apply a function to all keys in a keyring tree 🎀

✨ SYNOPSIS ✨

#include <keyutils.h>

typedef int (*recursive_key_scanner_t)(key_serial_t parent,
    key_serial_t key, char *desc, int desc_len, void *data);

long recursive_key_scan(key_serial_t keyring,
    recursive_key_scanner_t func, void *data);
long recursive_session_key_scan(recursive_key_scanner_t func,
    void *data);

like, that's the whole vibe right there 💅

🦋 DESCRIPTION 🦋

recursive_key_scan() does a depth-first recursive scan of the keyring tree you point it at, and it applies func to every single link it finds in the accessible keyrings inside that tree. no cap, every link. and data gets passed along to every invocation of func 🫶

The return values of func get summed up and that sum is what you get back as the overall return value. Errors? Ignored, periodt. 🙈 Also: inaccessible keyrings don't get scanned, but the links pointing at them still get passed to func — so like, func still hears about them, she just doesn't go inside. 💀

recursive_session_key_scan() works exactly like recursive_key_scan() except the caller's session keyring is the starting keyring. same energy, different starting point. 🌈

The callback function gets called for each link found in all the keyrings in the nominated tree — which means it may be called multiple times for a particular key if that key has multiple links to it. so don't be shocked when the same key shows up again, she's just that popular. 👑

💜 the callback function's parameters 💜

• parent — the keyring containing the link, or 0 for the initial key. 💖
• key — the key to which the link points. 🔥
• desc and desc_len — a pointer to the raw description and its length, as retrieved with keyctl_describe_alloc(). These will be NULL and -1 respectively if the description couldn't be retrieved, and errno will retain the error from keyctl_describe_alloc(). 😭 so yeah, check those. fr fr.
• data — the data passed to the scanner function. ⭐

💅 RETURN VALUE 💅

These functions return the sum of the results of the callback functions they invoke. that's it, that's the whole bag. 🎀

🍓 ERRORS 🍓

Ignored. literally ignored. not even a little bit of attention. 💀✨

🧚 LINKING 🧚

When linking, -lkeyutils should be specified to the linker. don't forget it or the linker will be giving you the side eye. 👀

🌟 SEE ALSO 🌟

• keyctl(3)
• keyctl_describe_alloc(3)
• keyrings(7)

and that's the tea, bestie 💖 this page is from Linux, dated 10 Mar 2011 — iconic, historic, still slaying. now go scan that tree. 🌸🦋✨