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.