keyctl.2: Improvements to description of KEYCTL_GET_KEYRING_ID

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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