keyctl.2, KEYCTL_GET_KEYRING_ID.2const: Split KEYCTL_GET_KEYRING_ID from keyctl(2)

Signed-off-by: Alejandro Colomar <alx@kernel.org>
author: Alejandro Colomar <alx@kernel.org> 2024-06-19 12:41:39 +0200
committer: Alejandro Colomar <alx@kernel.org> 2024-08-21 23:51:05 +0200
commit: 1cd77abb20247575bf0ab593c0d69cd07df1ceb4 (patch)
tree: c3ed2c84133d2ca6cbc5f81203c2692d1f56b6e0
parent: 19a2eb8b64bf898916e8fbe5026a5bf1dabc47f2 (diff)
download: man-pages-1cd77abb20247575bf0ab593c0d69cd07df1ceb4.tar.gz
2 files changed, 165 insertions, 120 deletions
diff --git a/man/man2/keyctl.2 b/man/man2/keyctl.2
index 77d644c010..a6a8466d95 100644
--- a/man/man2/keyctl.2
+++ b/man/man2/keyctl.2
@@ -42,107 +42,7 @@ The permitted values for
 .I operation
 are:
 .TP
-.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)"
-Map a special key ID to a real key ID for this process.
-.IP
-This operation looks up the special key whose ID is provided in
-.I arg2
-(cast to
-.IR key_serial_t ).
-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 arg2 :
-.RS
-.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).
-.RE
-.IP
-The behavior if the key specified in
-.I arg2
-does not exist depends on the value of
-.I arg3
-(cast to
-.IR int ).
-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 .
-.IP
-If a valid key ID is specified in
-.IR arg2 ,
-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 .
-.IP
-The caller must have
-.I search
-permission on a keyring in order for it to be found.
-.IP
-The arguments
-.I arg4
-and
-.I arg5
-are ignored.
-.IP
-This operation is exposed by
-.I libkeyutils
-via the function
-.BR keyctl_get_keyring_ID (3).
+.BR KEYCTL_GET_KEYRING_ID (2const)
 .TP
 .BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.10)"
 Replace the session keyring this process subscribes to with
@@ -441,7 +341,7 @@ Searches can recurse only into nested keyrings that have
 permission set.
 .IP
 This permission is required for the
-.BR KEYCTL_GET_KEYRING_ID ,
+.BR KEYCTL_GET_KEYRING_ID (2const),
 .BR KEYCTL_JOIN_SESSION_KEYRING ,
 .BR KEYCTL_SEARCH ,
 and
@@ -754,7 +654,7 @@ Instead of valid existing keyring IDs, the source
 and destination
 .RI ( arg5 )
 keyrings can be one of the special keyring IDs listed under
-.BR KEYCTL_GET_KEYRING_ID .
+.BR KEYCTL_GET_KEYRING_ID (2const).
 .IP
 This operation is exposed by
 .I libkeyutils
@@ -770,7 +670,7 @@ The ID of the key whose payload is to be read is specified in
 .IR key_serial_t ).
 This can be the ID of an existing key,
 or any of the special key IDs listed for
-.BR KEYCTL_GET_KEYRING_ID .
+.BR KEYCTL_GET_KEYRING_ID (2const).
 .\" including KEY_SPEC_REQKEY_AUTH_KEY
 .IP
 The payload is placed in the buffer pointed by
@@ -1599,10 +1499,7 @@ is ignored.
 .\"     Author: Mat Martineau <mathew.j.martineau@linux.intel.com>
 .\" See Documentation/security/keys.txt
 .SH RETURN VALUE
-For a successful call, the return value depends on the operation:
-.TP
-.B KEYCTL_GET_KEYRING_ID
-The ID of the requested keyring.
+For a successful call, the return value depends on the operation.
 .TP
 .B KEYCTL_JOIN_SESSION_KEYRING
 The ID of the joined session keyring.
@@ -1863,17 +1760,6 @@ argument doesn't support setting key linking restrictions.
 .B ENOKEY
 No matching key was found or an invalid key was specified.
 .TP
-.B ENOKEY
-The value
-.B KEYCTL_GET_KEYRING_ID
-was specified in
-.IR operation ,
-the key specified in
-.I arg2
-did not exist, and
-.I arg3
-was zero (meaning don't create the key if it didn't exist).
-.TP
 .B ENOMEM
 One of kernel memory allocation routines failed during the execution of the
 syscall.
@@ -2246,7 +2132,6 @@ main(int argc, char *argv[])
 .BR keyctl_describe_alloc (3),
 .BR keyctl_dh_compute (3),
 .BR keyctl_dh_compute_alloc (3),
-.BR keyctl_get_keyring_ID (3),
 .BR keyctl_get_persistent (3),
 .BR keyctl_get_security (3),
 .BR keyctl_get_security_alloc (3),
diff --git a/man/man2const/KEYCTL_GET_KEYRING_ID.2const b/man/man2const/KEYCTL_GET_KEYRING_ID.2const
new file mode 100644
index 0000000000..67cb834393
--- /dev/null
+++ b/man/man2const/KEYCTL_GET_KEYRING_ID.2const
@@ -0,0 +1,160 @@
+.\" 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 (date) "Linux man-pages (unreleased)"
+.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 " arg2 ,
+.BI "             int " arg3 );
+.fi
+.SH DESCRIPTION
+.TP
+.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.10)"
+Map a special key ID to a real key ID for this process.
+.IP
+This operation looks up the special key whose ID is provided in
+.I arg2
+(cast to
+.IR key_serial_t ).
+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 arg2 :
+.RS
+.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).
+.RE
+.IP
+The behavior if the key specified in
+.I arg2
+does not exist depends on the value of
+.I arg3
+(cast to
+.IR int ).
+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 .
+.IP
+If a valid key ID is specified in
+.IR arg2 ,
+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 .
+.IP
+The caller must have
+.I search
+permission on a keyring in order for it to be found.
+.IP
+The arguments
+.I arg4
+and
+.I arg5
+are ignored.
+.IP
+This operation is exposed by
+.I libkeyutils
+via the function
+.BR keyctl_get_keyring_ID (3).
+.SH RETURN VALUE
+.TP
+.B KEYCTL_GET_KEYRING_ID
+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 value
+.B KEYCTL_GET_KEYRING_ID
+was specified in
+.IR operation ,
+the key specified in
+.I arg2
+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)
author	Alejandro Colomar <alx@kernel.org>	2024-06-19 12:41:39 +0200
committer	Alejandro Colomar <alx@kernel.org>	2024-08-21 23:51:05 +0200
commit	1cd77abb20247575bf0ab593c0d69cd07df1ceb4 (patch)
tree	c3ed2c84133d2ca6cbc5f81203c2692d1f56b6e0
parent	19a2eb8b64bf898916e8fbe5026a5bf1dabc47f2 (diff)
download	man-pages-1cd77abb20247575bf0ab593c0d69cd07df1ceb4.tar.gz