Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_LINK.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_LINK 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_LINK
10 \-
11 link a key to a keyring
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_LINK, key_serial_t " key ,
22 .BI " key_serial_t " keyring );
23 .fi
24 .SH DESCRIPTION
25 Create a link from a keyring to a key.
26 .P
27 The key to be linked is specified in
28 .IR key ;
29 the keyring is specified in
30 .IR keyring .
31 .P
32 If a key with the same type and description is already linked in the keyring,
33 then that key is displaced from the keyring.
34 .P
35 Before creating the link,
36 the kernel checks the nesting of the keyrings and returns appropriate errors
37 if the link would produce a cycle
38 or if the nesting of keyrings would be too deep
39 (The limit on the nesting of keyrings is determined by the kernel constant
40 .BR KEYRING_SEARCH_MAX_DEPTH ,
41 defined with the value 6, and is necessary to prevent overflows
42 on the kernel stack when recursively searching keyrings).
43 .P
44 The caller must have
45 .I link
46 permission on the key being added and
47 .I write
48 permission on the keyring.
49 .SH RETURN VALUE
50 On success,
51 0 is returned.
52 .P
53 On error, \-1 is returned, and
54 .I errno
55 is set to indicate the error.
56 .SH ERRORS
57 .TP
58 .B EDEADLK
59 The requested link would result in a cycle.
60 .TP
61 .B ELOOP
62 The requested link would cause the maximum nesting depth
63 for keyrings to be exceeded.
64 .TP
65 .BR ENFILE " (before Linux 3.13)"
66 The keyring is full.
67 (Before Linux 3.13,
68 .\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69
69 the available space for storing keyring links was limited to
70 a single page of memory;
71 since Linux 3.13,
72 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)