keyrings.7, persistent-keyring.7, process-keyring.7, session-keyring.7, thread-keyring.7, user-keyring.7, user-session-keyring.7: ffix + pages xref fixes

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

man7/keyrings.7

@@ -27,7 +27,7 @@ A library and some userspace utilities are provided to allow access to the
 facility.
 See
 .BR keyutils (7)
-manual page for more information.
+for more information.
 .P
 This document contains the following sections:
 .P
@@ -94,11 +94,12 @@ memory and the owning user ID specifies whose quota is to be debited.
 Each key can have an expiration time set.
 When that time is reached,
 the key is marked as being expired and accesses to it fail with
-\fIEKEYEXPIRED\fR.
+.BR EKEYEXPIRED .
 If not deleted, updated or replaced, after a set amount of time,
 expired keys are
-automatically removed along with all links to them and \fIENOKEY\fR will be
-reported.
+automatically removed along with all links to them and
+.B ENOKEY
+will be reported.
 .IP "\fBReference count\fR"
 Each key has a reference count.
 Keys are referenced by keyrings, by current active users
@@ -190,17 +191,28 @@ These keyrings are pinned as long as the set of credentials exists - which is
 usually as long as the process does.
 .IP
 There are three keyrings with different inheritance/sharing rules:
-The \fBsession keyring\fR (inherited and shared by all child processes),
-the \fBprocess keyring\fR (shared by all threads in a process) and
-the \fBthread keyring\fR (specific to a particular thread).
+The
+.BR session-keyring (7)
+(inherited and shared by all child processes),
+the
+.BR process-keyring (7)
+(shared by all threads in a process) and
+the
+.BR thread-keyring (7)
+(specific to a particular thread).
 .IP "\fBUser keyrings\fR"
 Each UID known to the kernel has a record that contains two keyrings: The
-\fBuser keyring\fR and the \fBuser session keyring\fR.
+.BR user-keyring (7)
+and the
+.BR user-session-keyring (7).
 These exist for as long as the UID record in the kernel exists.
 A link to the user keyring is placed in a new session keyring by
-\fBpam_keyinit\fR when a new login session is initiated.
+.BR pam_keyinit (8) 
+when a new login session is initiated.
 .IP "\fBPersistent keyrings\fR"
-There is a \fBpersistent keyring\fR available to each UID known to the system.
+There is a
+.BR persistent-keyring (7)
+available to each UID known to the system.
 It may persist beyond the life of the UID record previously mentioned,
 but has an expiration time set such that it is automatically cleaned up
 after a set time.
@@ -256,9 +268,10 @@ to access the user's keys.
 It also allows the prevention of access to keys
 just on the basis of UID and GID matches.
 .P
-When it creates the session keyring, the \fBpam_keyinit\fR module adds a link
-to the user keyring, thus making the user keyring and anything it contains
-possessed by default.
+When it creates the session keyring,
+.BR pam_keyinit (8)
+adds a link to the user keyring,
+thus making the user keyring and anything it contains possessed by default.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SH ACCESS RIGHTS
 .P
@@ -338,7 +351,9 @@ manual pages for more information.
 .P
 One of the key features of this facility is the ability to find a key that it
 is retaining.
-The \fBrequest_key\fR() system call is the primary point of
+The
+.BR request_key (2)
+system call is the primary point of
 access for userspace to find a key to use
 (the kernel has something similar available).
 .P
@@ -346,7 +361,10 @@ The search algorithm works as follows:
 .IP (1)
 The three process keyrings are searched in the following order: the thread
 keyring if it exists, the process keyring if it exists and then either the
-session keyring if it exists or the user session keyring if that exists.
+.BR session-keyring (7)
+if it exists or the
+.BR user-session-keyring (7)
+if that exists.
 .IP (2)
 If the caller was a process that was invoked by the \fBrequest_key\fR() upcall
 mechanism then the keyrings of the original caller of that \fBrequest_key\fR()
@@ -367,20 +385,24 @@ then the first noted error state is returned or else \fBENOKEY\fR is returned.
 It is also possible to search a specific keyring, in which case only steps (3)
 to (6) apply.
 .P
-See the
+See
 .BR request_key (2)
 and
 .BR keyctl_search (3)
-manual pages for more information.
+for more information.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SH ON-DEMAND KEY CREATION
 .P
-If a key cannot be found, the \fBrequest_key\fR() system call will, if given a
-\fIcallout_info\fR argument, create a new key and then upcall to userspace to
+If a key cannot be found,
+.BR request_key (2)
+will, if given a
+.I callout_info
+argument, create a new key and then upcall to userspace to
 instantiate the key.
 This allows keys to be created on an as-needed basis.
 .P
-Typically, this will involve the kernel forking and exec'ing \fBrequest-key\fR
+Typically, this will involve the kernel forking and exec'ing
+.BR request-key (8)
 program, which will then execute the appopriate handler based on its
 configuration.
 .P

man7/persistent-keyring.7

@@ -14,9 +14,7 @@
 .SH NAME
 persistent-keyring \- per-user persistent keyring
 .SH DESCRIPTION
-The
-.B persistent keyring
-is a keyring used to anchor keys on behalf of a user.
+The persistent keyring is a keyring used to anchor keys on behalf of a user.
 Each UID the kernel deals with has its own persistent keyring that
 is shared between all threads owned by that UID.
 .P
@@ -36,8 +34,12 @@ first before that keyring can access it by virtue of its possessor permits.
 This is done with \fBkeyctl_get_persistent\fP().
 .P
 Persistent keyrings are independent of
-clone(), fork(), vfork(), execve() and
-exit().
+.BR clone (2),
+.BR fork (2),
+.BR vfork (2),
+.BR execve (2),
+and
+.BR exit (2).
 They persist until their expiration timers trigger - at which point
 they are garbage collected.
 This allows them to carry keys beyond the life of
@@ -51,7 +53,9 @@ The keyutils library provides a special operation for manipulating persistent
 keyrings:
 .IP \fBkeyctl_get_persistent\fP()
 This operation allows the caller to get the persistent keyring corresponding
-to their own UID or, if they have \fBCAP_SETUID\fR, the persistent keyring
+to their own UID or, if they have
+.BR CAP_SETUID ,
+the persistent keyring
 corresponding to some other UID in the same user namespace.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SH SEE ALSO

man7/process-keyring.7

@@ -14,12 +14,12 @@
 .SH NAME
 process-keyring \- per-process shared keyring
 .SH DESCRIPTION
-The
-.B process keyring
-is a keyring used to anchor keys on behalf of a process.
+The process keyring is a keyring used to anchor keys on behalf of a process.
 It is only created when a process requests it.
 .P
-A special serial number value, \fBKEY_SPEC_PROCESS_KEYRING\fP, is defined that
+A special serial number value,
+.BR KEY_SPEC_PROCESS_KEYRING ,
+is defined that
 can be used in lieu of the calling process's process keyring's actual serial
 number.
 .P
@@ -27,14 +27,20 @@ From the keyctl utility, '\fB@p\fP' can be used instead of a numeric key ID in
 much the same way, but as keyctl is a program run after forking, this is of no
 utility.
 .P
-A process's process keyring is inherited across clone() with CLONE_THREAD and
-is cleared by execve().
+A process's process keyring is inherited across
+.BR clone (2)
+with
+.B CLONE_THREAD
+and is cleared by
+.BR execve (2).
 The process keyring will be destroyed when the last
 thread that refers to it exits.
 .P
 If a process doesn't have a process keyring when it is accessed, then the
 process keyring will be created if the keyring is to be modified, otherwise
-error ENOKEY will be issued.
+error
+.B ENOKEY
+will be issued.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SH SEE ALSO
 .ad l

man7/session-keyring.7

@@ -14,12 +14,12 @@
 .SH NAME
 session-keyring \- session shared process keyring
 .SH DESCRIPTION
-The
-.B session keyring
-is a keyring used to anchor keys on behalf of a process.
-It is typically created by the \fBpam_keyinit\fP module
+The session keyring is a keyring used to anchor keys on behalf of a process.
+It is typically created by
+.BR pam_keyinit (8)
 when a user logs in and a link will be
-added that refers to the \fBuser keyring\fP.
+added that refers to the
+.BR user-keyring (7).
 .P
 A special serial number value, \fBKEY_SPEC_SESSION_KEYRING\fP, is defined that
 can be used in lieu of the calling process's session keyring's actual serial
@@ -28,8 +28,15 @@ number.
 From the keyctl utility, '\fB@s\fP' can be used instead of a numeric key ID in
 much the same way.
 .P
-A process's session keyring is inherited across clone(), fork() and vfork() and
-is retained across execve() - even when the target executable is setuid or
+A process's session keyring is inherited across
+.BR clone (2),
+.BR fork (2),
+and
+.BR vfork (2)
+and
+is retained across
+.BR execve (2)
+- even when the target executable is setuid or
 setgid.
 The session keyring will be destroyed when the last process that
 refers to it exits.

man7/thread-keyring.7

@@ -14,12 +14,12 @@
 .SH NAME
 thread-keyring \- per-thread keyring
 .SH DESCRIPTION
-The
-.B thread keyring
-is a keyring used to anchor keys on behalf of a process.
+The thread keyring is a keyring used to anchor keys on behalf of a process.
 It is only created when a thread requests it.
 .P
-A special serial number value, \fBKEY_SPEC_THREAD_KEYRING\fP, is defined that
+A special serial number value,
+.BR KEY_SPEC_THREAD_KEYRING ,
+is defined that
 can be used in lieu of the calling thread's thread keyring's actual serial
 number.
 .P
@@ -27,12 +27,16 @@ From the keyctl utility, '\fB@t\fP' can be used instead of a numeric key ID in
 much the same way, but as keyctl is a program run after forking, this is of no
 utility.
 .P
-Thread keyrings are not inherited across clone() and are cleared by execve().
+Thread keyrings are not inherited across
+.BR clone (2)
+and are cleared by
+.BR execve (2).
 A thread keyring is destroyed when the thread that refers to it exits.
 .P
 If a thread doesn't have a thread keyring when it is accessed, then the thread
 keyring will be created if the keyring is to be modified, otherwise error
-ENOKEY will be issued.
+.B ENOKEY
+will be issued.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SH SEE ALSO
 .ad l

man7/user-keyring.7

@@ -14,9 +14,7 @@
 .SH NAME
 user-keyring \- per-user keyring
 .SH DESCRIPTION
-The
-.B user keyring
-is a keyring used to anchor keys on behalf of a user.
+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.
@@ -24,27 +22,40 @@ 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 \fBpam_keyinit\fP is invoked when a user logs in.
+this happens when
+.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 the
-pam_keyinit module creates a session keyring, it adds to it a link to the user
+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
-A special serial number value, \fBKEY_SPEC_USER_KEYRING\fP, is defined that
+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
 much the same way.
 .P
-User keyrings are independent of clone(), fork(), vfork(), execve() and exit()
+User keyrings are independent of
+.BR clone (2),
+.BR fork (2),
+.BR vfork (2),
+.BR execve (2),
+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 \fBpersistent keyring\fP should be used instead.
+the
+.BR persistent-keyring (7)
+should be used instead.
 .P
 If a user keyring does not exist when it is accessed, it will be created.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

man7/user-session-keyring.7

@@ -14,9 +14,7 @@
 .SH NAME
 user-session-keyring \- per-user default session keyring
 .SH DESCRIPTION
-The
-.B user session keyring
-is a keyring used to anchor keys on behalf of a user.
+The user session keyring is a keyring used to anchor keys on behalf of a user.
 Each UID the kernel
 deals with has its own user session keyring.
 This keyring is associated with
@@ -26,7 +24,9 @@ It is shared amongst all processes of that
 UID.
 .P
 The user session keyring is created on demand when a thread requests it
-or when a thread asks for its \fBsession keyring\fP and that doesn't exist.
+or when a thread asks for its
+.BR session-keyring (7)
+and that doesn't exist.
 In the latter case,
 a user session keyring will be created and, if the session keyring
 wasn't to be created, the user session keyring will be set as the process's
@@ -35,22 +35,34 @@ actual session keyring.
 The user session keyring is searched by \fBrequest_key\fP() if the actual
 session keyring does not exist and is ignored otherwise.
 .P
-A special serial number value, \fBKEY_SPEC_USER_SESSION_KEYRING\fP, is defined
+A special serial number value,
+.BR KEY_SPEC_USER_SESSION_KEYRING ,
+is defined
 that can be used in lieu of the calling process's user session keyring's actual
 serial number.
 .P
 From the keyctl utility, '\fB@us\fP' can be used instead of a numeric key ID in
 much the same way.
 .P
-User session keyrings are independent of clone(), fork(), vfork(), execve() and
-exit() excepting that the keyring is destroyed when the UID record is destroyed
+User session keyrings are independent of
+.BR clone (2),
+.BR fork (2),
+.BR vfork (2),
+.BR execve (2),
+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 a user session keyring does not exist when it is accessed, it will be
 created.
 .P
-It is strongly recommended that a \fBsession keyring\fP be set explicitly, for
-example by \fBpam_keyinit\fP, rather than relying on the user session keyring -
+It is strongly recommended that a
+.BR session-keyring (7)
+be set explicitly, for
+example by
+.BR pam_keyinit (8),
+rather than relying on the user session keyring -
 particularly if a process is running as root.
 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 .SH SEE ALSO