.\" Copyright 2016, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Copyright 2016, Eugene Syromyatnikov <evgsyr@gmail.com>
.\" A very few fragments remain from an earlier version of this page
.\" written by David Howells (dhowells@redhat.com)
.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH KEYCTL_GET_KEYRING_ID 2const 2024-08-21 "Linux man-pages 6.10"
.SH NAME
KEYCTL_GET_KEYRING_ID
\-
map a special key ID to a real key ID for this process
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.BR "#include <linux/keyctl.h>" "  /* Definition of " KEY* " constants */"
.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.BI "long syscall(SYS_keyctl, KEYCTL_GET_KEYRING_ID, key_serial_t " key ,
.BI "             int " arg3 );
.fi
.SH DESCRIPTION
Map a special key ID to a real key ID for this process.
.P
This operation looks up the special key whose ID is provided in
.IR key .
If the special key is found,
the ID of the corresponding real key is returned as the function result.
The following values may be specified in
.IR key :
.TP
.B KEY_SPEC_THREAD_KEYRING
This specifies the calling thread's thread-specific keyring.
See
.BR thread\-keyring (7).
.TP
.B KEY_SPEC_PROCESS_KEYRING
This specifies the caller's process-specific keyring.
See
.BR process\-keyring (7).
.TP
.B KEY_SPEC_SESSION_KEYRING
This specifies the caller's session-specific keyring.
See
.BR session\-keyring (7).
.TP
.B KEY_SPEC_USER_KEYRING
This specifies the caller's UID-specific keyring.
See
.BR user\-keyring (7).
.TP
.B KEY_SPEC_USER_SESSION_KEYRING
This specifies the caller's UID-session keyring.
See
.BR user\-session\-keyring (7).
.TP
.BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)"
.\"            commit b5f545c880a2a47947ba2118b2509644ab7a2969
This specifies the authorization key created by
.BR request_key (2)
and passed to the process it spawns to generate a key.
This key is available only in a
.BR request\-key (8)-style
program that was passed an authorization key by the kernel and
ceases to be available once the requested key has been instantiated; see
.BR request_key (2).
.TP
.BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)"
.\"            commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
This specifies the key ID for the
.BR request_key (2)
destination keyring.
This keyring is available only in a
.BR request\-key (8)-style
program that was passed an authorization key by the kernel and
ceases to be available once the requested key has been instantiated; see
.BR request_key (2).
.P
The behavior if the key specified in
.I key
does not exist depends on the value of
.IR arg3 .
If
.I arg3
contains a nonzero value, then
\[em]if it is appropriate to do so
(e.g., when looking up the user, user-session, or session key)\[em]
a new key is created and
its real key ID returned as the function result.
.\" The keyctl_get_keyring_ID.3 page says that a new key
.\" "will be created *if it is appropriate to do so**. What is the
.\" determiner for appropriate?
.\" David Howells: Some special keys such as KEY_SPEC_REQKEY_AUTH_KEY
.\" wouldn't get created but user/user-session/session keyring would
.\" be created.
Otherwise, the operation fails with the error
.BR ENOKEY .
.P
If a valid key ID is specified in
.IR key ,
and the key exists, then this operation simply returns the key ID.
If the key does not exist, the call fails with error
.BR ENOKEY .
.P
The caller must have
.I search
permission on a keyring in order for it to be found.
.SH RETURN VALUE
On success,
the ID of the requested keyring.
.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B ENOKEY
The key specified in
.I key
did not exist, and
.I arg3
was zero
(meaning don't create the key if it didn't exist).
.SH VERSIONS
A wrapper is provided in the
.I libkeyutils
library:
.BR keyctl_get_keyring_ID (3).
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.6.10.
.SH SEE ALSO
.BR keyctl (2),
.BR keyctl_get_keyring_ID (3)