Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_SEARCH.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_SEARCH 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_SEARCH
10 \-
11 search a keyring for a key
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_SEARCH, key_serial_t " src ,
22 .BI " char *" type ", char *" desc ,
23 .BI " unsigned long " dst );
24 .fi
25 .SH DESCRIPTION
26 Search for a key in a keyring tree,
27 returning its ID and optionally linking it to a specified keyring.
28 .P
29 The tree to be searched is specified by passing
30 the ID of the head keyring in
31 .IR src .
32 The search is performed breadth-first and recursively.
33 .P
34 The
35 .I type
36 and
37 .I desc
38 arguments specify the key to be searched for:
39 .I type
40 contains the key type
41 (a null-terminated character string up to 32 bytes in size,
42 including the terminating null byte), and
43 .I desc
44 contains the description of the key
45 (a null-terminated character string up to 4096 bytes in size,
46 including the terminating null byte).
47 .P
48 The source keyring must grant
49 .I search
50 permission to the caller.
51 When performing the recursive search, only keyrings that grant the caller
52 .I search
53 permission will be searched.
54 Only keys with for which the caller has
55 .I search
56 permission can be found.
57 .P
58 If the key is found, its ID is returned as the function result.
59 .P
60 If the key is found and
61 .I dst
62 is nonzero, then, subject to the same constraints and rules as
63 .BR KEYCTL_LINK (2const),
64 the key is linked into the keyring whose ID is specified in
65 .IR dst .
66 If the destination keyring specified in
67 .I dst
68 already contains a link to a key that has the same type and description,
69 then that link will be displaced by a link to
70 the key found by this operation.
71 .P
72 Instead of valid existing keyring IDs, the source
73 .RI ( src )
74 and destination
75 .RI ( dst )
76 keyrings can be one of the special keyring IDs listed under
77 .BR KEYCTL_GET_KEYRING_ID (2const).
78 .SH RETURN VALUE
79 On success,
80 the ID of the key that was found.
81 .P
82 On error, \-1 is returned, and
83 .I errno
84 is set to indicate the error.
85 .SH ERRORS
86 .TP
87 .B EINVAL
88 The size of the description in
89 .I desc
90 (including the terminating null byte) exceeded 4096 bytes.
91 .SH VERSIONS
92 A wrapper is provided in the
93 .I libkeyutils
94 library:
95 .BR keyctl_search (3).
96 .SH STANDARDS
97 Linux.
98 .SH HISTORY
99 Linux 2.6.10.
100 .SH SEE ALSO
101 .BR keyctl (2),
102 .BR keyctl_search (3)