signal.7: Some reworking of Michal Sekletar's text

[thirdparty/man-pages.git] / man7 / user-keyring.7

diff --git a/man7/user-keyring.7 b/man7/user-keyring.7
index 4fc3e0990c616faca96d90e8412f25b239568889..c1791e3daa2b50eeaff13ac240f0992e83cfb626 100644 (file)
--- a/man7/user-keyring.7
+++ b/man7/user-keyring.7
@@ -4,42 +4,57 @@
 .\"
 .\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
 .\" This program is free software; you can redistribute it and/or
-.\" modify it under the terms of the GNU General Public Licence
+.\" modify it under the terms of the GNU General Public License
 .\" as published by the Free Software Foundation; either version
-.\" 2 of the Licence, or (at your option) any later version.
+.\" 2 of the License, or (at your option) any later version.
 .\" %%%LICENSE_END
 .\"
-.TH "USER-KEYRING" 7 2016-11-01 Linux "Linux Programmer's Manual"
+.TH "USER-KEYRING" 7 2017-03-13 Linux "Linux Programmer's Manual"
 .SH NAME
 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.
-.P
-The user keyring is created on demand when a thread requests it.
-Normally,
-this happens when
+Each UID the kernel deals with has its own user keyring that
+is shared by all processes with that UID.
+The user keyring has a name (description) of the form
+.I _uid.<UID>
+where
+.I <UID>
+is the user ID of the corresponding user.
+.PP
+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.)
+.PP
+Typically, the user keyring is created by
 .BR pam_keyinit (8)
-is invoked when a user logs in.
-.P
-The user keyring is not searched by default by \fBrequest_key\fP().
+when a user logs in.
+.PP
+The user keyring is not searched by default by
+.BR request_key (2).
 When
 .BR pam_keyinit (8)
 creates a session keyring, it adds to it a link to the user
 keyring so that the user keyring will be searched when the session keyring is.
-.P
+.PP
 A special serial number value,
 .BR KEY_SPEC_USER_KEYRING ,
-is defined that
-can be used in lieu of the calling process's user keyring's actual serial
-number.
-.P
-From the keyctl utility, '\fB@u\fP' can be used instead of a numeric key ID in
+is defined that can be used in lieu of the actual serial number of
+the calling process's user keyring.
+.PP
+From the
+.BR keyctl (1)
+utility, '\fB@u\fP' can be used instead of a numeric key ID in
 much the same way.
-.P
+.PP
 User keyrings are independent of
 .BR clone (2),
 .BR fork (2),
@@ -49,13 +64,14 @@ and
 .BR _exit (2)
 excepting that the keyring is destroyed when the UID record is destroyed when
 the last process pinning it exits.
-.P
-If it necessary to for a key associated with a user to exist beyond the UID
-record being garbage collected - for example for use by a cron script - then
-the
+.PP
+If it is necessary for a key associated with a user to exist beyond the UID
+record being garbage collected\(emfor example, for use by a
+.BR cron (8)
+script\(emthen the
 .BR persistent-keyring (7)
 should be used instead.
-.P
+.PP
 If a user keyring does not exist when it is accessed, it will be created.
 .SH SEE ALSO
 .ad l