Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_SEARCH.2const

raw
1 .\" Copyright 2016, Michael Kerrisk <[email protected]>
2 .\" Copyright 2016, Eugene Syromyatnikov <[email protected]>
3 .\" A very few fragments remain from an earlier version of this page
4 .\" written by David Howells ([email protected])
5 .\" Copyright 2024, Alejandro Colomar <[email protected]>
6 .\"
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\"
9 .TH KEYCTL_SEARCH 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_SEARCH
12 \-
13 search a keyring for a key
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ,\~ \-lc )
17 .SH SYNOPSIS
18 .nf
19 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
20 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
21 .B #include <unistd.h>
22 .P
23 .BI "long syscall(SYS_keyctl, KEYCTL_SEARCH, key_serial_t " src ,
24 .BI " char *" type ", char *" desc ,
25 .BI " unsigned long " dst );
26 .fi
27 .SH DESCRIPTION
28 Search for a key in a keyring tree,
29 returning its ID and optionally linking it to a specified keyring.
30 .P
31 The tree to be searched is specified by passing
32 the ID of the head keyring in
33 .IR src .
34 The search is performed breadth-first and recursively.
35 .P
36 The
37 .I type
38 and
39 .I desc
40 arguments specify the key to be searched for:
41 .I type
42 contains the key type
43 (a null-terminated character string up to 32 bytes in size,
44 including the terminating null byte), and
45 .I desc
46 contains the description of the key
47 (a null-terminated character string up to 4096 bytes in size,
48 including the terminating null byte).
49 .P
50 The source keyring must grant
51 .I search
52 permission to the caller.
53 When performing the recursive search, only keyrings that grant the caller
54 .I search
55 permission will be searched.
56 Only keys with for which the caller has
57 .I search
58 permission can be found.
59 .P
60 If the key is found, its ID is returned as the function result.
61 .P
62 If the key is found and
63 .I dst
64 is nonzero, then, subject to the same constraints and rules as
65 .BR KEYCTL_LINK (2const),
66 the key is linked into the keyring whose ID is specified in
67 .IR dst .
68 If the destination keyring specified in
69 .I dst
70 already contains a link to a key that has the same type and description,
71 then that link will be displaced by a link to
72 the key found by this operation.
73 .P
74 Instead of valid existing keyring IDs, the source
75 .RI ( src )
76 and destination
77 .RI ( dst )
78 keyrings can be one of the special keyring IDs listed under
79 .BR KEYCTL_GET_KEYRING_ID (2const).
80 .SH RETURN VALUE
81 On success,
82 the ID of the key that was found.
83 .P
84 On error, \-1 is returned, and
85 .I errno
86 is set to indicate the error.
87 .SH ERRORS
88 .TP
89 .B EINVAL
90 The size of the description in
91 .I desc
92 (including the terminating null byte) exceeded 4096 bytes.
93 .SH VERSIONS
94 A wrapper is provided in the
95 .I libkeyutils
96 library:
97 .BR keyctl_search (3).
98 .SH STANDARDS
99 Linux.
100 .SH HISTORY
101 Linux 2.6.10.
102 .SH SEE ALSO
103 .BR keyctl (2),
104 .BR keyctl_search (3)