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)