Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/keyctl_search.3 @ 68:5028fdace37b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 16:23:26 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 68:5028fdace37b
1 .\"
2 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
3 .\" Written by David Howells (dhowells@redhat.com)
4 .\"
5 .\" This program is free software; you can redistribute it and/or
6 .\" modify it under the terms of the GNU General Public License
7 .\" as published by the Free Software Foundation; either version
8 .\" 2 of the License, or (at your option) any later version.
9 .\"
10 .TH KEYCTL_SEARCH 3 "4 May 2006" Linux "Linux Key Management Calls"
11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
12 .SH NAME
13 keyctl_search \- search a keyring for a key
14 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
15 .SH SYNOPSIS
16 .nf
17 .B #include <keyutils.h>
18 .sp
19 .BI "long keyctl_search(key_serial_t " keyring ", const char *" type ,
20 .BI "const char *" description ", key_serial_t " destination ");"
21 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
22 .SH DESCRIPTION
23 .BR keyctl_search ()
24 recursively searches the
25 .I keyring
26 for a key of the specified
27 .I type
28 and
29 .IR description .
30 .P
31 If found, the key will be attached to the
32 .I destination
33 keyring (if given), and its serial number will be returned.
34 .P
35 The source keyring must grant
36 .B search
37 permission to the caller, and for a key to be found, it must also grant
38 .B search
39 permission to the caller. Child keyrings will be only be recursively searched
40 if they grant
41 .B search
42 permission to the caller as well.
43 .P
44 If the destination keyring is
45 .BR zero ,
46 no attempt will be made to forge a link to the key, and just the serial number
47 will be returned.
48 .P
49 If the destination keyring is given, then the link may only be formed if the
50 found key grants the caller
51 .B link
52 permission and the destination keyring grants the caller
53 .B write
54 permission.
55 .P
56 If the search is successful, and if the destination keyring already contains a
57 link to a key that matches the specified
58 .IR type " and " description ,
59 then that link will be replaced by a link to the found key.
60 .P
61 The source keyring and destination keyring serial numbers may be those of
62 valid keyrings to which the caller has appropriate permission, or they may be
63 special keyring IDs:
64 .TP
65 .B KEY_SPEC_THREAD_KEYRING
66 This specifies the caller's thread-specific keyring.
67 .TP
68 .B KEY_SPEC_PROCESS_KEYRING
69 This specifies the caller's process-specific keyring.
70 .TP
71 .B KEY_SPEC_SESSION_KEYRING
72 This specifies the caller's session-specific keyring.
73 .TP
74 .B KEY_SPEC_USER_KEYRING
75 This specifies the caller's UID-specific keyring.
76 .TP
77 .B KEY_SPEC_USER_SESSION_KEYRING
78 This specifies the caller's UID-session keyring.
79 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
80 .SH RETURN VALUE
81 On success
82 .BR keyctl_search ()
83 returns the serial number of the key it found. On error, the value
84 .B -1
85 will be returned and
86 .I errno
87 will have been set to an appropriate error.
88 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
89 .SH ERRORS
90 .TP
91 .B ENOKEY
92 One of the keyrings doesn't exist, no key was found by the search, or the only
93 key found by the search was a negative key.
94 .TP
95 .B ENOTDIR
96 One of the keyrings is a valid key that isn't a keyring.
97 .TP
98 .B EKEYEXPIRED
99 One of the keyrings has expired, or the only key found was expired.
100 .TP
101 .B EKEYREVOKED
102 One of the keyrings has been revoked, or the only key found was revoked.
103 .TP
104 .B ENOMEM
105 Insufficient memory to expand the destination keyring.
106 .TP
107 .B EDQUOT
108 The key quota for this user would be exceeded by creating a link to the found
109 key in the destination keyring.
110 .TP
111 .B EACCES
112 The source keyring didn't grant
113 .B search
114 permission, the destination keyring didn't grant
115 .B write
116 permission or the found key didn't grant
117 .B link
118 permission to the caller.
119 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
120 .SH LINKING
121 Although this is a Linux system call, it is not present in
122 .I libc
123 but can be found rather in
124 .IR libkeyutils .
125 When linking,
126 .B \-lkeyutils
127 should be specified to the linker.
128 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
129 .SH SEE ALSO
130 .ad l
131 .nh
132 .BR keyctl (1),
133 .BR add_key (2),
134 .BR keyctl (2),
135 .BR request_key (2),
136 .BR keyctl (3),
137 .BR keyrings (7),
138 .BR keyutils (7)