KEYCTL_LINK(2const)                                        KEYCTL_LINK(2const)

NAME
       KEYCTL_LINK - link a key to a keyring

LIBRARY
       Standard C library (libc, -lc)

SYNOPSIS
       #include <linux/keyctl.h>  /* Definition of KEY* constants */
       #include <sys/syscall.h>   /* Definition of SYS_* constants */
       #include <unistd.h>

       long syscall(SYS_keyctl, KEYCTL_LINK, key_serial_t key,
                    key_serial_t keyring);

DESCRIPTION
       Create a link from a keyring to a key.

       The key to be linked is specified in key; the keyring is specified in
       keyring.

       If a key with the same type and description is already linked in the
       keyring, then that key is displaced from the keyring.

       Before creating the link, the kernel checks the nesting of the keyrings
       and returns appropriate errors if the link would produce a cycle or if
       the nesting of keyrings would be too deep (The limit on the nesting of
       keyrings is determined by the kernel constant KEYRING_SEARCH_MAX_DEPTH,
       defined with the value 6, and is necessary to prevent overflows on the
       kernel stack when recursively searching keyrings).

       The caller must have link permission on the key being added and write
       permission on the keyring.

RETURN VALUE
       On success, 0 is returned.

       On error, -1 is returned, and errno is set to indicate the error.

ERRORS
       EDEADLK
              The requested link would result in a cycle.

       ELOOP  The requested link would cause the maximum nesting depth for
              keyrings to be exceeded.

       ENFILE (before Linux 3.13)
              The keyring is full.  (Before Linux 3.13, the available space
              for storing keyring links was limited to a single page of
              memory; since Linux 3.13, there is no fixed limit.)

VERSIONS
       A wrapper is provided in the libkeyutils library: keyctl_link(3).

STANDARDS
       Linux.

HISTORY
       Linux 2.6.10.

SEE ALSO
       keyctl(2), keyctl_link(3), KEYCTL_UNLINK(2const)

Linux man-pages 6.10              2024-08-21               KEYCTL_LINK(2const)