user-keyring.7: Add details on user keyring lifetime

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

diff --git a/man7/user-keyring.7 b/man7/user-keyring.7
index ee3d6fef68327f0f96414110f91665d714e1e5c8..7e642c6ae98433cb0240c027c584eedc24d8e819 100644 (file)
--- a/man7/user-keyring.7
+++ b/man7/user-keyring.7
@@ -14,15 +14,24 @@
 user-keyring \- per-user keyring
 .SH DESCRIPTION
 The user keyring is a keyring used to anchor keys on behalf of a user.
-Each UID the kernel deals with has its own user keyring.
-This keyring is associated with the record that the kernel maintains
-for the UID and, once created, is retained as long as that record persists.
-It is shared amongst all processes of that UID.
+Each UID the kernel deals with has its own user keyring that
+is shared by all processes with that UID.
 
-The user keyring is created on demand when a thread requests it.
-Normally, this happens when
+The user keyring is associated with the record that the kernel maintains
+for the UID.
+It comes into existence upon the first attempt to access either the
+user keyring, the
+.BR user-session-keyring (7),
+or the
+.BR session-keyring (7).
+The keyring remains pinned in existence so long as there are processes
+running with that real UID or files opened by those processes remain open.
+(The keyring can also be pinned indefinitely by linking it
+into another keyring.)
+
+Typically, the user keyring is created by
 .BR pam_keyinit (8)
-is invoked when a user logs in.
+when a user logs in.
 
 The user keyring is not searched by default by
 .BR request_key (2).