From 29708373b10e41d61475577c4a7d568c0014feee Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Fri, 10 Feb 2017 09:57:11 +0100 Subject: [PATCH] keyctl.2: Improvements to description of KEYCTL_GET_KEYRING_ID Signed-off-by: Michael Kerrisk --- man2/keyctl.2 | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/man2/keyctl.2 b/man2/keyctl.2 index 168cf8eeb..32e81cd87 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -127,20 +127,30 @@ ceases to be available once the requested key has been instantiated; see .BR request_key (2). .RE .IP -If the key specified in +The behavior if the key specified in .I arg2 -does not exist, then a new key is created if the +does not exist depends on the value of .I arg3 -argument (cast to -.IR int ) -contains a non-zero value; otherwise the operation fails with the error -.BR ENOKEY . +(cast to +.IR int ). +If +.I arg3 +contains a non-zero value, then\(emif it is appropriate to do so +(e.g., when looking up the the user, user-session, or session key)\(ema 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 . + +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 . The caller must have .I search