Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_READ.2const

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