Debian Codegraph @

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