Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_READ.2const

raw
1 .\" Copyright 2016, Michael Kerrisk <[email protected]>
2 .\" Copyright 2016, Eugene Syromyatnikov <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH KEYCTL_READ 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_READ
10 \-
11 read a key
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
18 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
19 .B #include <unistd.h>
20 .P
21 .BR "long syscall(" "size_t size;"
22 .BI " SYS_keyctl, KEYCTL_READ, key_serial_t " key ,
23 .BI " char " buf "[_Nullable " size "], size_t " size );
24 .fi
25 .SH DESCRIPTION
26 Read the payload data of a key.
27 .P
28 The ID of the key whose payload is to be read is specified in
29 .IR key .
30 This can be the ID of an existing key,
31 or any of the special key IDs listed for
32 .BR KEYCTL_GET_KEYRING_ID (2const).
33 .\" including KEY_SPEC_REQKEY_AUTH_KEY
34 .P
35 The payload is placed in the buffer pointed by
36 .IR buf ;
37 the size of that buffer must be specified in
38 .IR size .
39 .P
40 The returned data will be processed for presentation
41 according to the key type.
42 For example, a keyring will return an array of
43 .I key_serial_t
44 entries representing the IDs of all the keys that are linked to it.
45 The
46 .I user
47 key type will return its data as is.
48 .P
49 If
50 .I buf
51 is not NULL,
52 as much of the payload data as will fit is copied into the buffer.
53 On a successful return,
54 the return value is always the total size of the payload data.
55 To determine whether the buffer was of sufficient size,
56 check to see that the return value is less than or equal to
57 the value supplied in
58 .IR size .
59 .P
60 The key must either grant the caller
61 .I read
62 permission, or grant the caller
63 .I search
64 permission when searched for from the process keyrings
65 (i.e., the key is possessed).
66 .SH RETURN VALUE
67 On success,
68 the amount of data that is available in the key,
69 irrespective of the provided buffer size.
70 .P
71 On error, \-1 is returned, and
72 .I errno
73 is set to indicate the error.
74 .SH ERRORS
75 .TP
76 .B EOPNOTSUPP
77 The key type does not support reading
78 (e.g., the type is
79 .IR \[dq]login\[dq] ).
80 .SH VERSIONS
81 A wrapper is provided in the
82 .I libkeyutils
83 library:
84 .BR keyctl_read (3).
85 .SH STANDARDS
86 Linux.
87 .SH HISTORY
88 Linux 2.6.10.
89 .SH SEE ALSO
90 .BR keyctl (2),
91 .BR keyctl_read (3),
92 .BR keyctl_read_alloc (3)