Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_LINK.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_LINK 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_LINK
12 \-
13 link a key to a keyring
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_LINK, key_serial_t " key ,
24 .BI " key_serial_t " keyring );
25 .fi
26 .SH DESCRIPTION
27 Create a link from a keyring to a key.
28 .P
29 The key to be linked is specified in
30 .IR key ;
31 the keyring is specified in
32 .IR keyring .
33 .P
34 If a key with the same type and description is already linked in the keyring,
35 then that key is displaced from the keyring.
36 .P
37 Before creating the link,
38 the kernel checks the nesting of the keyrings and returns appropriate errors
39 if the link would produce a cycle
40 or if the nesting of keyrings would be too deep
41 (The limit on the nesting of keyrings is determined by the kernel constant
42 .BR KEYRING_SEARCH_MAX_DEPTH ,
43 defined with the value 6, and is necessary to prevent overflows
44 on the kernel stack when recursively searching keyrings).
45 .P
46 The caller must have
47 .I link
48 permission on the key being added and
49 .I write
50 permission on the keyring.
51 .SH RETURN VALUE
52 On success,
53 0 is returned.
54 .P
55 On error, \-1 is returned, and
56 .I errno
57 is set to indicate the error.
58 .SH ERRORS
59 .TP
60 .B EDEADLK
61 The requested link would result in a cycle.
62 .TP
63 .B ELOOP
64 The requested link would cause the maximum nesting depth
65 for keyrings to be exceeded.
66 .TP
67 .BR ENFILE " (before Linux 3.13)"
68 The keyring is full.
69 (Before Linux 3.13,
70 .\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69
71 the available space for storing keyring links was limited to
72 a single page of memory; since Linux 3.13, there is no fixed limit.)
73 .SH VERSIONS
74 A wrapper is provided in the
75 .I libkeyutils
76 library:
77 .BR keyctl_link (3).
78 .SH STANDARDS
79 Linux.
80 .SH HISTORY
81 Linux 2.6.10.
82 .SH SEE ALSO
83 .BR keyctl (2),
84 .BR keyctl_link (3),
85 .BR KEYCTL_UNLINK (2const)