NAME

       KEYCTL_READ - read 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_READ, key_serial_t key,
                    char buf[_Nullable size], size_t size);

DESCRIPTION

       Read the payload data of a key.

       The  ID  of  the  key whose payload is to be read is specified in key.  This can be the ID of an existing
       key, or any of the special key IDs listed for KEYCTL_GET_KEYRING_ID(2const).

       The payload is placed in the buffer pointed by buf; the size of that buffer must be specified in size.

       The returned data will be processed for presentation according to the key type.  For example,  a  keyring
       will  return an array of key_serial_t entries representing the IDs of all the keys that are linked to it.
       The user key type will return its data as is.

       If buf is not NULL, as much of the payload data as will fit is copied into the buffer.  On  a  successful
       return,  the  return value is always the total size of the payload data.  To determine whether the buffer
       was of sufficient size, check to see that the return value is less than or equal to the value supplied in
       size.

       The key must either grant the caller read permission, or grant the caller search permission when searched
       for from the process keyrings (i.e., the key is possessed).

RETURN VALUE

       On success, the amount of data that is available in the key, irrespective of the provided buffer size.

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

ERRORS

       EOPNOTSUPP
              The key type does not support reading (e.g., the type is "login").

VERSIONS

       A wrapper is provided in the libkeyutils library: keyctl_read(3).

STANDARDS

       Linux.

HISTORY

       Linux 2.6.10.

SEE ALSO

       keyctl(2), keyctl_read(3), keyctl_read_alloc(3)

Linux man-pages 6.16                               2025-06-28                                KEYCTL_READ(2const)