KEYCTL_DESCRIBE(2const)

💅 KEYCTL_DESCRIBE — described in the 2const manual, bestie

okay so hi!! welcome to the KEYCTL_DESCRIBE page, it's a 2const thing, and honestly? it's giving "tell me everything about this key, no gatekeeping." let's get into it 🎀

---

✨ NAME ✨

KEYCTL_DESCRIBE — spill the tea about a key, aka describe a key 🦋

📚 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(size_t size;
             SYS_keyctl, KEYCTL_DESCRIBE, key_serial_t key,
             char desc[_Nullable size], size_t size);

like yes we're raw-dogging syscall() here, iykyk 💀

---

👑 DESCRIPTION 👑

So the whole vibe of this one is: you hand it a key, it hands you back a string. A whole little string that describes that key's attributes. that's it, that's the function 💖

The ID of the key you wanna have described? that goes in key. The descriptive string comes back in the buffer that desc points at, and size says how many bytes big that buffer is. easy.

The key must grant the caller view permission. no view perms, no vibes, no description. 🙈

The returned string is null-terminated and contains this info about the key:

type;uid;gid;perm;description

In that lineup: type and description are strings, uid and gid are decimal strings, and perm is a hexadecimal permissions mask. the descriptive string gets written with this exact format:

%s;%d;%d;%08x;%s

Note: the intention is that the descriptive string should be extensible in future kernel versions. In particular, the description field will not contain semicolons; it should be parsed by working backwards from the end of the string to find the last semicolon. This allows future semicolon-delimited fields to be inserted in the descriptive string in the future.

^^ not me warning you to parse from the back, that's the main character move here 💅

Writing to the buffer is attempted only when desc is non-NULL and the specified buffer size is big enough to accept the descriptive string (including the terminating null byte). So how do you know if your buffer was too small? check whether the return value of the operation is greater than size. that's your vibe check 🌈

---

⭐ RETURN VALUE ⭐

On success, you get the size of the description (including the terminating null byte), and that's irrespective of the provided buffer size. so even if your buffer was tiny, it still tells you how much room you actually needed. iconic behaviour, honestly.

On error, -1 is returned, and errno is set to indicate the error. 😭

---

🦋 VERSIONS 🦋

A wrapper is provided in the libkeyutils library: keyctl_describe(3). yes bestie, you don't have to do the raw syscall every time 😌

🎀 STANDARDS 🎀

Linux. that's the whole list. periodt.

💜 HISTORY 💜

Linux 2.6.10. an elder, a legend, a queen 👑

🌸 SEE ALSO 🌸

• keyctl(2)
• keyctl_describe(3)
• keyctl_describe_alloc(3)

---

and that's the page!! mwah 💋 this was Linux man-pages 6.20, dated 2026-02-08, and it lives under the name KEYCTL_DESCRIBE(2const). go describe some keys, you absolute genius 🫶✨