Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_GET_PERSISTENT.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_GET_PERSISTENT 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_GET_PERSISTENT
12 \-
13 get the persistent keyring for a user
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_GET_PERSISTENT, uid_t " uid ,
24 .BI " key_serial_t " keyring );
25 .fi
26 .SH DESCRIPTION
27 Get the persistent keyring
28 .RB ( persistent\-keyring (7))
29 for a specified user and link it to a specified keyring.
30 .P
31 The user ID is specified in
32 .IR uid .
33 If the value \-1 is specified, the caller's real user ID is used.
34 The ID of the destination keyring is specified in
35 .IR keyring .
36 .P
37 The caller must have the
38 .B CAP_SETUID
39 capability in its user namespace in order to fetch the persistent keyring
40 for a user ID that does not match either the real or effective user ID
41 of the caller.
42 .P
43 If the call is successful,
44 a link to the persistent keyring is added to the keyring
45 whose ID was specified in
46 .IR keyring .
47 .P
48 The caller must have
49 .I write
50 permission on the keyring.
51 .P
52 The persistent keyring will be created by the kernel
53 if it does not yet exist.
54 .P
55 Each time the
56 .B KEYCTL_GET_PERSISTENT
57 operation is performed, the persistent keyring will
58 have its expiration timeout reset to the value in:
59 .P
60 .in +4n
61 .EX
62 /proc/sys/kernel/keys/persistent_keyring_expiry
63 .EE
64 .in
65 .P
66 Should the timeout be reached,
67 the persistent keyring will be removed and
68 everything it pins can then be garbage collected.
69 .P
70 Persistent keyrings were added in Linux 3.13.
71 .SH RETURN VALUE
72 On success,
73 the ID of the persistent keyring.
74 .P
75 On error, \-1 is returned, and
76 .I errno
77 is set to indicate the error.
78 .SH ERRORS
79 .TP
80 .B EPERM
81 .I uid
82 specified a UID other than the calling thread's real or effective UID,
83 and the caller did not have the
84 .B CAP_SETUID
85 capability.
86 .SH VERSIONS
87 A wrapper is provided in the
88 .I libkeyutils
89 library:
90 .BR keyctl_get_persistent (3).
91 .SH STANDARDS
92 Linux.
93 .SH HISTORY
94 Linux 3.13.
95 .\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
96 .SH SEE ALSO
97 .BR keyctl (2),
98 .BR keyctl_get_persistent (3)