Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_GET_KEYRING_ID.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_KEYRING_ID 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_GET_KEYRING_ID
10 \-
11 map a special key ID to a real key ID for this process
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_KEYRING_ID, key_serial_t " key ,
22 .BI " int " arg3 );
23 .fi
24 .SH DESCRIPTION
25 Map a special key ID to a real key ID for this process.
26 .P
27 This operation looks up the special key whose ID is provided in
28 .IR key .
29 If the special key is found,
30 the ID of the corresponding real key is returned as the function result.
31 The following values may be specified in
32 .IR key :
33 .TP
34 .B KEY_SPEC_THREAD_KEYRING
35 This specifies the calling thread's thread-specific keyring.
36 See
37 .BR thread\-keyring (7).
38 .TP
39 .B KEY_SPEC_PROCESS_KEYRING
40 This specifies the caller's process-specific keyring.
41 See
42 .BR process\-keyring (7).
43 .TP
44 .B KEY_SPEC_SESSION_KEYRING
45 This specifies the caller's session-specific keyring.
46 See
47 .BR session\-keyring (7).
48 .TP
49 .B KEY_SPEC_USER_KEYRING
50 This specifies the caller's UID-specific keyring.
51 See
52 .BR user\-keyring (7).
53 .TP
54 .B KEY_SPEC_USER_SESSION_KEYRING
55 This specifies the caller's UID-session keyring.
56 See
57 .BR user\-session\-keyring (7).
58 .TP
59 .BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)"
60 .\" commit b5f545c880a2a47947ba2118b2509644ab7a2969
61 This specifies the authorization key created by
62 .BR request_key (2)
63 and passed to the process it spawns to generate a key.
64 This key is available only in a
65 .BR request\-key (8)-style
66 program that was passed an authorization key by the kernel and
67 ceases to be available once the requested key has been instantiated;
68 see
69 .BR request_key (2).
70 .TP
71 .BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)"
72 .\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
73 This specifies the key ID for the
74 .BR request_key (2)
75 destination keyring.
76 This keyring is available only in a
77 .BR request\-key (8)-style
78 program that was passed an authorization key by the kernel and
79 ceases to be available once the requested key has been instantiated;
80 see
81 .BR request_key (2).
82 .P
83 The behavior if the key specified in
84 .I key
85 does not exist depends on the value of
86 .IR arg3 .
87 If
88 .I arg3
89 contains a nonzero value, then
90 \[em]if it is appropriate to do so
91 (e.g., when looking up the user, user-session, or session key)\[em]
92 a new key is created and
93 its real key ID returned as the function result.
94 .\" The keyctl_get_keyring_ID.3 page says that a new key
95 .\" "will be created *if it is appropriate to do so*". What is the
96 .\" determiner for appropriate?
97 .\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY
98 .\" wouldn't get created but user/user-session/session keyring would
99 .\" be created.
100 Otherwise, the operation fails with the error
101 .BR ENOKEY .
102 .P
103 If a valid key ID is specified in
104 .IR key ,
105 and the key exists, then this operation simply returns the key ID.
106 If the key does not exist, the call fails with error
107 .BR ENOKEY .
108 .P
109 The caller must have
110 .I search
111 permission on a keyring in order for it to be found.
112 .SH RETURN VALUE
113 On success,
114 the ID of the requested keyring.
115 .P
116 On error, \-1 is returned, and
117 .I errno
118 is set to indicate the error.
119 .SH ERRORS
120 .TP
121 .B ENOKEY
122 The key specified in
123 .I key
124 did not exist, and
125 .I arg3
126 was zero
127 (meaning don't create the key if it didn't exist).
128 .SH VERSIONS
129 A wrapper is provided in the
130 .I libkeyutils
131 library:
132 .BR keyctl_get_keyring_ID (3).
133 .SH STANDARDS
134 Linux.
135 .SH HISTORY
136 Linux 2.6.10.
137 .SH SEE ALSO
138 .BR keyctl (2),
139 .BR keyctl_get_keyring_ID (3)