Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_SET_REQKEY_KEYRING.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_SET_REQKEY_KEYRING 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_SET_REQKEY_KEYRING
10 \-
11 set the implicit destination keyring
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_SET_REQKEY_KEYRING, int " op );
22 .fi
23 .SH DESCRIPTION
24 Set the default keyring to which implicitly requested keys
25 will be linked for this thread,
26 and return the previous setting.
27 Implicit key requests are those made by internal kernel components,
28 .\" I.e., calls to the kernel's internal request_key() interface,
29 .\" which is distinct from the request_key(2) system call (which
30 .\" ultimately employs the kernel-internal interface).
31 such as can occur when, for example, opening files
32 on an AFS or NFS filesystem.
33 Setting the default keyring also has an effect
34 when requesting a key from user space;
35 see
36 .BR request_key (2)
37 for details.
38 .P
39 The
40 .I op
41 argument
42 should contain one of the following values,
43 to specify the new default keyring:
44 .TP
45 .B KEY_REQKEY_DEFL_NO_CHANGE
46 Don't change the default keyring.
47 This can be used to discover the current default keyring
48 (without changing it).
49 .TP
50 .B KEY_REQKEY_DEFL_DEFAULT
51 This selects the default behavior,
52 which is to use the thread-specific keyring if there is one,
53 otherwise the process-specific keyring if there is one,
54 otherwise the session keyring if there is one,
55 otherwise the UID-specific session keyring,
56 otherwise the user-specific keyring.
57 .TP
58 .B KEY_REQKEY_DEFL_THREAD_KEYRING
59 Use the thread-specific keyring
60 .RB ( thread\-keyring (7))
61 as the new default keyring.
62 .TP
63 .B KEY_REQKEY_DEFL_PROCESS_KEYRING
64 Use the process-specific keyring
65 .RB ( process\-keyring (7))
66 as the new default keyring.
67 .TP
68 .B KEY_REQKEY_DEFL_SESSION_KEYRING
69 Use the session-specific keyring
70 .RB ( session\-keyring (7))
71 as the new default keyring.
72 .TP
73 .B KEY_REQKEY_DEFL_USER_KEYRING
74 Use the UID-specific keyring
75 .RB ( user\-keyring (7))
76 as the new default keyring.
77 .TP
78 .B KEY_REQKEY_DEFL_USER_SESSION_KEYRING
79 Use the UID-specific session keyring
80 .RB ( user\-session\-keyring (7))
81 as the new default keyring.
82 .TP
83 .BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
84 .\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
85 Use the requestor keyring.
86 .\" FIXME The preceding explanation needs to be expanded.
87 .\" Is the following correct:
88 .\"
89 .\" The requestor keyring is the dest_keyring that
90 .\" was supplied to a call to request_key(2)?
91 .\"
92 .\" David Howells said: to be checked
93 .P
94 All other values are invalid.
95 .\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING)
96 .P
97 The setting controlled by this operation is inherited by the child of
98 .BR fork (2)
99 and preserved across
100 .BR execve (2).
101 .SH RETURN VALUE
102 On success,
103 the ID of the previous default keyring
104 to which implicitly requested keys were linked
105 (one of
106 .BR KEY_REQKEY_DEFL_USER_* ).
107 .P
108 On error, \-1 is returned, and
109 .I errno
110 is set to indicate the error.
111 .SH VERSIONS
112 A wrapper is provided in the
113 .I libkeyutils
114 library:
115 .BR keyctl_set_reqkey_keyring (3)
116 .SH STANDARDS
117 Linux.
118 .SH HISTORY
119 Linux 2.6.13.
120 .SH SEE ALSO
121 .BR keyctl (2),
122 .BR keyctl_set_reqkey_keyring (3)