KEYCTL_DESCRIBE(2const)                                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(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)

Linux man-pages 6.10              2024-08-21           KEYCTL_DESCRIBE(2const)