.\"
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
.\" Written by David Howells (dhowells@redhat.com)
.\"
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License
.\" as published by the Free Software Foundation; either version
.\" 2 of the License, or (at your option) any later version.
.\"
.TH KEYCTL_LINK 3 "4 May 2006" Linux "Linux Key Management Calls"
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH NAME
keyctl_link, keyctl_unlink \- link/unlink a key to/from a keyring
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH SYNOPSIS
.nf
.B #include <keyutils.h>
.sp
.BI "long keyctl_link(key_serial_t " key ", key_serial_t " keyring ");"
.sp
.BI "long keyctl_unlink(key_serial_t " key ", key_serial_t " keyring ");"
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH DESCRIPTION
.BR keyctl_link ()
creates a link from
.I keyring
to
.IR key ,
displacing any link to another key of the same type and description in that
keyring if one exists.
.P
.BR keyctl_unlink ()
removes the link from
.I keyring
to
.I key
if it exists.
.P
The caller must have
.B write
permission on a keyring to be able to create or remove links in it.
.P
The caller must have
.B link
permission on a key to be able to create a link to it.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH RETURN VALUE
On success
.BR keyctl_link ()
and
.BR keyctl_unlink ()
return
.BR 0 .
On error, the value
.B -1
will be returned and
.I errno
will have been set to an appropriate error.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH ERRORS
.TP
.B ENOKEY
The key or the keyring specified are invalid.
.TP
.B EKEYEXPIRED
The key or the keyring specified have expired.
.TP
.B EKEYREVOKED
The key or the keyring specified have been revoked.
.TP
.B EACCES
The keyring exists, but is not
.B writable
by the calling process.
.P
For
.BR keyctl_link ()
only:
.TP
.B ENOMEM
Insufficient memory to expand the keyring
.TP
.B EDQUOT
Expanding the keyring would exceed the keyring owner's quota.
.TP
.B EACCES
The key exists, but is not
.B linkable
by the calling process.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH LINKING
This is a library function that can be found in
.IR libkeyutils .
When linking,
.B \-lkeyutils
should be specified to the linker.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH SEE ALSO
.ad l
.nh
.BR keyctl (1),
.BR add_key (2),
.BR keyctl (2),
.BR request_key (2),
.BR keyctl (3),
.BR keyrings (7),
.BR keyutils (7)