KEYCTL_DESCRIBE(2const)

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).

STANDARDS
Linux.

HISTORY
Linux 2.6.10.

SEE ALSO
keyctl(2), keyctl_describe(3), keyctl_describe_alloc(3)