mirror of https://github.com/mkerrisk/man-pages
request_key.2: Various improvements to description
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
c7e3fd59ed
commit
2e3b9c2aa7
|
@ -26,10 +26,12 @@ No glibc wrapper is provided for this system call; see NOTES.
|
|||
attempts to find a key of the given
|
||||
.I type
|
||||
with a description (name) that matches the specified
|
||||
.I description
|
||||
and, if successful, attaches it to the nominated
|
||||
.IR description .
|
||||
If the key is found,
|
||||
.BR request_key ()
|
||||
attaches it to the nominated
|
||||
.I keyring
|
||||
and returns its serial number.
|
||||
and returns the key's serial number.
|
||||
.P
|
||||
.BR request_key ()
|
||||
first recursively searches for a matching key in all of the keyrings
|
||||
|
@ -49,19 +51,19 @@ supplementary group IDs, and security context to control access.
|
|||
The search of the keyring tree is breadth-first:
|
||||
the keys in each keyring searched are checked for a match before any child
|
||||
keyrings are recursed into.
|
||||
Only keys that are
|
||||
.B searchable
|
||||
for the caller may be found, and only
|
||||
.B searchable
|
||||
keyrings may be searched.
|
||||
Only keys for which the caller has
|
||||
.I search
|
||||
permission be found, and only keyrings for which the caller has
|
||||
.I search
|
||||
permission may be searched.
|
||||
.P
|
||||
If the key is not found, then, if
|
||||
.I callout_info
|
||||
is not NULL, this function will attempt to look further afield.
|
||||
In such a case, the
|
||||
is not NULL, the kernel will attempt to look further afield.
|
||||
In this case, the
|
||||
.I callout_info
|
||||
is passed to a user-space service such as
|
||||
.I /sbin/request\-key
|
||||
.BR request-key (8)
|
||||
to generate the key.
|
||||
.P
|
||||
If that is unsuccessful also, then an error will be returned, and a temporary
|
||||
|
@ -81,28 +83,33 @@ serial number may be that of a valid keyring to which the caller has write
|
|||
permission, or it may be one of the following special keyring IDs:
|
||||
.TP
|
||||
.B KEY_SPEC_THREAD_KEYRING
|
||||
This specifies the caller's thread-specific keyring.
|
||||
This specifies the caller's thread-specific keyring
|
||||
.RB ( thread-keyring (7)).
|
||||
.TP
|
||||
.B KEY_SPEC_PROCESS_KEYRING
|
||||
This specifies the caller's process-specific keyring.
|
||||
This specifies the caller's process-specific keyring
|
||||
.RB ( process-keyring (7)).
|
||||
.TP
|
||||
.B KEY_SPEC_SESSION_KEYRING
|
||||
This specifies the caller's session-specific keyring.
|
||||
This specifies the caller's session-specific keyring
|
||||
.RB ( session-keyring (7)).
|
||||
.TP
|
||||
.B KEY_SPEC_USER_KEYRING
|
||||
This specifies the caller's UID-specific keyring.
|
||||
This specifies the caller's UID-specific keyring
|
||||
.RB ( user-keyring (7)).
|
||||
.TP
|
||||
.B KEY_SPEC_USER_SESSION_KEYRING
|
||||
This specifies the caller's UID-session keyring.
|
||||
This specifies the caller's UID-session keyring
|
||||
.RB ( user-session-keyring (7)).
|
||||
.P
|
||||
If a key is created, no matter whether it's a valid key or a negative key, it
|
||||
will displace any other key of the same type and description from the
|
||||
destination
|
||||
If a key is created, then\(emregardless of whether it is a valid key or
|
||||
a negative key\(emit will displace any other key with
|
||||
the same type and description from the destination
|
||||
.IR keyring .
|
||||
.SH RETURN VALUE
|
||||
On success,
|
||||
.BR request_key ()
|
||||
returns the serial number of the key it found.
|
||||
returns the serial number of the key it found or caused to be created.
|
||||
On error, \-1 is returned and
|
||||
.I errno
|
||||
is set to indicate the cause of the error.
|
||||
|
|
Loading…
Reference in New Issue