---
name: "KEYCTL_DESCRIBE"
section: "2const"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/KEYCTL_DESCRIBE"
---

# KEYCTL\_DESCRIBE(2const)

describe a key

## NAME

KEYCTL\_DESCRIBE - describe a key

## LIBRARY

Standard C library (*libc*, *-lc*)

## 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***);**

## DESCRIPTION

Obtain a string describing the attributes of a specified key.

The ID of the key to be described is specified in *key*. The descriptive string is returned in the buffer pointed to by *desc*; *size* specifies the size of that buffer in bytes.

The key must grant the caller *view* permission.

The returned string is null-terminated and contains the following information about the key:

*type*;*uid*;*gid*;*perm*;*description*

In the above, *type* and *description* are strings, *uid* and *gid* are decimal strings, and *perm* is a hexadecimal permissions mask. The descriptive string is written with the following 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.

Writing to the buffer is attempted only when *desc* is non-NULL and the specified buffer size is large enough to accept the descriptive string (including the terminating null byte). In order to determine whether the buffer size was too small, check to see if the return value of the operation is greater than *size*.

## RETURN VALUE

On success, the size of the description (including the terminating null byte), irrespective of the provided buffer size.

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)](/keyctl_describe/3.md).

## STANDARDS

Linux.

## HISTORY

Linux 2.6.10.

## SEE ALSO

[**keyctl**(2)](/keyctl/2.md), [**keyctl\_describe**(3)](/keyctl_describe/3.md), [**keyctl\_describe\_alloc**(3)](/keyctl_describe_alloc/3.md)