2 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
3 .\" Written by David Howells (dhowells@redhat.com)
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.
10 .TH KEYCTL_SEARCH 3 "4 May 2006" Linux "Linux Key Management Calls"
11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
13 keyctl_search \- Search a keyring for a key
14 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
17 .B #include <keyutils.h>
19 .BI "long keyctl_search(key_serial_t " keyring ", const char *" type ,
20 .BI "const char *" description ", key_serial_t " destination ");"
21 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
24 recursively searches the
26 for a key of the specified
31 If found, the key will be attached to the
33 keyring (if given), and its serial number will be returned.
35 The source keyring must grant
37 permission to the caller, and for a key to be found, it must also grant
39 permission to the caller. Child keyrings will be only be recursively searched
42 permission to the caller as well.
44 If the destination keyring is
46 no attempt will be made to forge a link to the key, and just the serial number
49 If the destination keyring is given, then the link may only be formed if the
50 found key grants the caller
52 permission and the destination keyring grants the caller
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.
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
65 .B KEY_SPEC_THREAD_KEYRING
66 This specifies the caller's thread-specific keyring.
68 .B KEY_SPEC_PROCESS_KEYRING
69 This specifies the caller's process-specific keyring.
71 .B KEY_SPEC_SESSION_KEYRING
72 This specifies the caller's session-specific keyring.
74 .B KEY_SPEC_USER_KEYRING
75 This specifies the caller's UID-specific keyring.
77 .B KEY_SPEC_USER_SESSION_KEYRING
78 This specifies the caller's UID-session keyring.
79 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
83 returns the serial number of the key it found. On error, the value
85 will be returned and errno will have been set to an appropriate error.
86 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
90 One of the keyrings doesn't exist, no key was found by the search, or the only
91 key found by the search was a negative key.
94 One of the keyrings is a valid key that isn't a keyring.
97 One of the keyrings has expired, or the only key found was expired.
100 One of the keyrings has been revoked, or the only key found was revoked.
103 Insufficient memory to expand the destination keyring.
106 The key quota for this user would be exceeded by creating a link to the found
107 key in the destination keyring.
110 The source keyring didn't grant
112 permission, the destination keyring didn't grant
114 permission or the found key didn't grant
116 permission to the caller.
117 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
119 Although this is a Linux system call, it is not present in
121 but can be found rather in
125 should be specified to the linker.
126 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""