keyctl.2: Improve KEYCTL_JOIN_SESSION_KEYRING description

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

man2/keyctl.2

@@ -78,25 +78,50 @@ via the function
 .BR keyctl_get_keyring_ID (3).
 .TP
 .B KEYCTL_JOIN_SESSION_KEYRING
-Create a new anonymous session keyring (in case
+Replace the session keyring this process subscribes to with
+a new session keyring.
+
+If
 .I arg2
-is
-.BR NULL )
-or join an existing named session keyring
-.RI ( arg2
-should be a pointer to a string containing session name in this case).
+is NULL,
+an anonymous keyring with the description "_ses" is created
+and the process is subscribed to that keyring as its session keyring,
+displacing the previous session keyring.
 
-The caller must have
+Otherwise,
+.I arg2
+(cast as
+.IR "char\ *" )
+is treated as the description (name) of a keyring,
+and the behavior is as follows:
+.RS
+.IP * 3
+If a keyring with a matching description exists,
+the process will attempt to subscribe to that keyring if possible;
+if that is not possible, an error is returned.
+.\" FIXME What error is returned?
+In order to subscribe to the keyring,
+the caller must have
 .I search
-permission on the keyring name which is provided in order
-to successfully join.
-
+permission on the keyring.
+.IP *
+If a keyring with a matching description does not exist,
+then a new keyring with that description is created,
+and the process is subscribed to that keyring as its session keyring,
+displacing the previous session keyring.
+.RE
+.IP
 The arguments
 .IR arg3 ,
 .IR arg4 ,
 and
 .IR arg5
 are ignored.
+
+This operation is exposed by
+.I libkeyutils
+via the function
+.BR keyctl_join_session_keyring (3).
 .TP
 .B KEYCTL_UPDATE
 Update a key's data payload.