.\" Copyright 2016, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Copyright 2016, Eugene Syromyatnikov <evgsyr@gmail.com>
.\" A very few fragments remain from an earlier version of this page
.\" written by David Howells (dhowells@redhat.com)
.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH KEYCTL_READ 2const 2024-08-21 "Linux man-pages 6.10"
.SH NAME
KEYCTL_READ
\-
read a key
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.BR "#include <linux/keyctl.h>" "  /* Definition of " KEY* " constants */"
.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.BI "long syscall(SYS_keyctl, KEYCTL_READ, key_serial_t " key ,
.BI "             char " buf "[_Nullable ." size "], size_t " size );
.fi
.SH DESCRIPTION
Read the payload data of a key.
.P
The ID of the key whose payload is to be read is specified in
.IR key .
This can be the ID of an existing key,
or any of the special key IDs listed for
.BR KEYCTL_GET_KEYRING_ID (2const).
.\" including KEY_SPEC_REQKEY_AUTH_KEY
.P
The payload is placed in the buffer pointed by
.IR buf ;
the size of that buffer must be specified in
.IR size .
.P
The returned data will be processed for presentation
according to the key type.
For example, a keyring will return an array of
.I key_serial_t
entries representing the IDs of all the keys that are linked to it.
The
.I user
key type will return its data as is.
.P
If
.I 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
.IR size .
.P
The key must either grant the caller
.I read
permission, or grant the caller
.I search
permission when searched for from the process keyrings
(i.e., the key is possessed).
.SH RETURN VALUE
On success,
the amount of data that is available in the key,
irrespective of the provided buffer size.
.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EOPNOTSUPP
The key type does not support reading
(e.g., the type is
.IR \[dq]login\[dq] ).
.SH VERSIONS
A wrapper is provided in the
.I libkeyutils
library:
.BR keyctl_read (3).
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.6.10.
.SH SEE ALSO
.BR keyctl (2),
.BR keyctl_read (3),
.BR keyctl_read_alloc (3)