LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

keyctl.2: wfix: various fixes in discussion of casting types 

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2016-10-19 10:44:28 +02:00
parent efd4c0cdd1
commit fd2d68f9af
1 changed files with 86 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
man2/keyctl.2
View File

@ -49,7 +49,7 @@ Map a special key ID to a real key ID for this process.
This operation looks up the special key whose ID is provided in This operation looks up the special key whose ID is provided in
.I arg2 .I arg2
(which is cast as (cast to
.IR key_serial_t ) .IR key_serial_t )
and (if it is found) the ID of corresponding real key is returned and (if it is found) the ID of corresponding real key is returned
@ -57,7 +57,7 @@ If the key specified in
.I arg2 .I arg2
does not exist, then a new key is created if the does not exist, then a new key is created if the
.I arg3 .I arg3
argument (cast as an argument (cast to
.IR int ) .IR int )
contains a non-zero value; otherwise the operation fails with the error contains a non-zero value; otherwise the operation fails with the error
.BR ENOKEY . .BR ENOKEY .
@ -90,7 +90,7 @@ displacing the previous session keyring.
Otherwise, Otherwise,
.I arg2 .I arg2
(cast as (cast to
.IR "char\ *" ) .IR "char\ *" )
is treated as the description (name) of a keyring, is treated as the description (name) of a keyring,
and the behavior is as follows: and the behavior is as follows:
@ -128,16 +128,16 @@ Update a key's data payload.
The The
.I arg2 .I arg2
argument (cast as argument (cast to
.IR key_serial_t ) .IR key_serial_t )
specifies the ID of the key to be updated. specifies the ID of the key to be updated.
The The
.I arg3 .I arg3
argument (cast as argument (cast to
.IR "void\ *" ) .IR "void\ *" )
points to the new payload and points to the new payload and
.I arg4 .I arg4
(cast as (cast to
.IR size_t ) .IR size_t )
contains the new payload size in bytes. contains the new payload size in bytes.
@ -160,7 +160,7 @@ via the function
.B KEYCTL_REVOKE .B KEYCTL_REVOKE
Revoke the key with the ID provided in Revoke the key with the ID provided in
.I arg2 .I arg2
(cast as (cast to
.IR key_serial_t ). .IR key_serial_t ).
The caller must have The caller must have
@ -185,20 +185,20 @@ via the function
.BR keyctl_revoke (3). .BR keyctl_revoke (3).
.TP .TP
.B KEYCTL_CHOWN .B KEYCTL_CHOWN
Set the ownership of a key. Change the ownership of a key.
The The
.I arg2 .I arg2
argument (converted to argument (cast to
.IR key_serial_t ) .IR key_serial_t )
contains the key ID. contains the key ID.
The The
.I arg3 .I arg3
argument (converted to argument (cast to
.IR uid_t ) .IR uid_t )
contains the new user ID (or \-1 in case the user ID shouldn't be changed). contains the new user ID (or \-1 in case the user ID shouldn't be changed).
The The
.I arg4 .I arg4
argument (converted to argument (cast to
.IR gid_t ) .IR gid_t )
contains the new group ID (or \-1 in case the group ID shouldn't be changed). contains the new group ID (or \-1 in case the group ID shouldn't be changed).
The key must grant the caller The key must grant the caller
@ -226,11 +226,11 @@ via the function
.B KEYCTL_SETPERM .B KEYCTL_SETPERM
Change the permissions of the key with the ID provided in the Change the permissions of the key with the ID provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.IR key_serial_t ) .IR key_serial_t )
to the permissions provided in the to the permissions provided in the
.I arg3 .I arg3
argument (converted to argument (cast to
.IR key_perms_t ). .IR key_perms_t ).
The key must grant The key must grant
.I setattr .I setattr
@ -305,7 +305,7 @@ via the function
Describe a key. Describe a key.
The ID of the key to be described should be provided in the The ID of the key to be described should be provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.IR key_serial_t ). .IR key_serial_t ).
The The
.I arg3 .I arg3
@ -342,7 +342,7 @@ via the function
.B KEYCTL_CLEAR .B KEYCTL_CLEAR
Clear the contents of the keyring with the ID provided in the Clear the contents of the keyring with the ID provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.IR key_serial_t ). .IR key_serial_t ).
The caller must have The caller must have
@ -364,11 +364,11 @@ via the function
.B KEYCTL_LINK .B KEYCTL_LINK
Link a key (provided in the Link a key (provided in the
.I arg2 .I arg2
argument converted to argument cast to
.I key_serial_t .I key_serial_t
type) to a keyring (provided in the type) to a keyring (provided in the
.I arg3 .I arg3
argument converted to argument cast to
.I key_serial_t .I key_serial_t
type) of there is no matching key in the keyring, or replace the link type) of there is no matching key in the keyring, or replace the link
to the matching key with a link to the new key. to the matching key with a link to the new key.
@ -393,11 +393,11 @@ via the function
.B KEYCTL_UNLINK .B KEYCTL_UNLINK
Unlink a key (provided in the Unlink a key (provided in the
.I arg2 .I arg2
argument converted to argument cast to
.I key_serial_t .I key_serial_t
type) from a keyring (provided in the type) from a keyring (provided in the
.I arg3 .I arg3
argument converted to argument cast to
.I key_serial_t .I key_serial_t
type). type).
@ -422,9 +422,8 @@ via the function
.B KEYCTL_SEARCH .B KEYCTL_SEARCH
Search for a key in a keyring with the ID provided in the Search for a key in a keyring with the ID provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
The The
.I arg3 .I arg3
argument should be a argument should be a
@ -448,9 +447,9 @@ permission can be found.
If the If the
.I arg5 .I arg5
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t )
type) contains a non-zero value, it is interpreted as a keyring ID to which contains a non-zero value, it is interpreted as a keyring ID to which
the found key should be linked. the found key should be linked.
This operation is exposed by This operation is exposed by
@ -461,19 +460,16 @@ via the function
.B KEYCTL_READ .B KEYCTL_READ
Read the payload of the key whose ID is provided in the Read the payload of the key whose ID is provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
The payload is placed in the buffer pointed by the The payload is placed in the buffer pointed by the
.I arg3 .I arg3
argument (converted to argument (cast to
.I char * .IR "char\ *" );
type);
the size of that buffer must be provided in the the size of that buffer must be provided in the
.I arg4 .I arg4
argument (converted to kernel's argument (cast to
.I size_t .IR size_t ).
type).
The key must either grant the caller The key must either grant the caller
.I read .I read
permission, or it must grant the caller permission, or it must grant the caller
@ -492,22 +488,20 @@ via the function
.B KEYCTL_INSTANTIATE .B KEYCTL_INSTANTIATE
Instantiate a partially constructed key whose ID is provided in the Instantiate a partially constructed key whose ID is provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t )
type) with a payload pointed by the with a payload pointed by the
.I arg3 .I arg3
argument (converted to argument (cast to
.I char * .IR "char\ *")
type) of size provided in the of size provided in the
.I arg4 .I arg4
argument (converted to kernel's argument (cast to
.I size_t .IR size_t ).
type).
The instantiated key will be linked to the keyring ID which is provided in the The instantiated key will be linked to the keyring ID which is provided in the
.I arg5 .I arg5
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
The caller must have the appropriate instantiation permit set (auth key). The caller must have the appropriate instantiation permit set (auth key).
This operation is exposed by This operation is exposed by
@ -518,18 +512,16 @@ via the function
.B KEYCTL_NEGATE .B KEYCTL_NEGATE
Negatively instantiate a partially constructed key with the ID provided in the Negatively instantiate a partially constructed key with the ID provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ),
type), setting the timeout (in seconds) to the value provided in the setting the timeout (in seconds) to the value provided in the
.I arg3 .I arg3
argument (converted to argument (cast to
.I unsigned int .IR "unsigned int" ).
type).
The instantiated key will be linked to the keyring ID which is provided in the The instantiated key will be linked to the keyring ID which is provided in the
.I arg4 .I arg4
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
The caller must have the appropriate instantiation permit set The caller must have the appropriate instantiation permit set
(authorization key, see (authorization key, see
@ -561,9 +553,9 @@ Read or set the default keyring in which
will cache keys. will cache keys.
The The
.I arg2 .I arg2
argument (converted to argument (cast to
.I int .IR int )
type) should contain one of the following values, defined in should contain one of the following values, defined in
.IR <linux/keyring.h> : .IR <linux/keyring.h> :
.RS .RS
.TP 33 .TP 33
@ -612,13 +604,12 @@ via the function
Set timeout on a key. Set timeout on a key.
ID of a key provided in the ID of a key provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ),
type), timeout value (in seconds from current time) provided in the timeout value (in seconds from current time) provided in the
.I arg3 .I arg3
argument (converted to argument (cast to
.I unsigned int .IR "unsigned int" ).
type).
The caller must either have the The caller must either have the
.I setattr .I setattr
@ -643,9 +634,8 @@ via the function
Assume (or clear) the authority for the key instantiation. Assume (or clear) the authority for the key instantiation.
The ID of the authorization key provided in the The ID of the authorization key provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
The caller must have the instantiation key in their process keyrings The caller must have the instantiation key in their process keyrings
with a with a
@ -672,18 +662,16 @@ via the function
Get the LSM security label of the specified key. Get the LSM security label of the specified key.
The ID of the key should be provided in the The ID of the key should be provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
The buffer where the security label should be stored is provided in the The buffer where the security label should be stored is provided in the
.I arg3 .I arg3
argument (converted to argument (cast to
.I char * .IR "char\ *" )
type) with its size provided in the with its size provided in the
.I arg4 .I arg4
argument (converted to kernel's argument (cast to
.I size_t .IR size_t ).
type).
The The
.I arg5 .I arg5
@ -725,22 +713,20 @@ via the function
.BR KEYCTL_REJECT " (since Linux 2.6.39)" .BR KEYCTL_REJECT " (since Linux 2.6.39)"
Negatively instantiate a partially constructed key with the ID provided in the Negatively instantiate a partially constructed key with the ID provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ),
type), setting timeout (in seconds) to the value provided in the setting timeout (in seconds) to the value provided in the
.I arg3 .I arg3
argument (converted to argument (cast to
.I unsigned int .IR "unsigned int" )
type) and instantiation error to the value provided in the and instantiation error to the value provided in the
.I arg4 .I arg4
argument (converted to argument (cast to
.I unsigned int .IR "unsigned int" ).
type).
The instantiated key will be linked to the keyring ID which is provided in the The instantiated key will be linked to the keyring ID which is provided in the
.I arg5 .I arg5
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
The caller must have the appropriate instantiation permit set The caller must have the appropriate instantiation permit set
(authorization key, see (authorization key, see
@ -793,9 +779,8 @@ via the function
.BR KEYCTL_INVALIDATE " (since Linux 3.5)" .BR KEYCTL_INVALIDATE " (since Linux 3.5)"
Invalidate a key with the ID provided in the Invalidate a key with the ID provided in the
.I arg2 .I arg2
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
The caller must have The caller must have
.I search .I search
@ -819,13 +804,12 @@ via the function
.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)" .BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
Get the persistent keyring of the user specified in the Get the persistent keyring of the user specified in the
.I arg2 .I arg2
(converted to (cast to
.I uid_t .IR uid_t )
type) and link it to the keyring with the ID provided in the and link it to the keyring with the ID provided in the
.I arg3 .I arg3
argument (converted to argument (cast to
.I key_serial_t .IR key_serial_t ).
type).
If \-1 is provided as UID, current user's ID is used. If \-1 is provided as UID, current user's ID is used.
The arguments The arguments
@ -868,13 +852,12 @@ The result is calculated as
The The
.I arg3 .I arg3
argument (converted to argument (cast to
.I char * .IR "char\ *" )
type) should point to an output buffer whose size is passed in the should point to an output buffer whose size is passed in the
.I arg4 .I arg4
argument (converted to kernel's argument (cast to
.I size_t .IR size_t ).
type).
The buffer should be big enough in order to accommodate the output data, The buffer should be big enough in order to accommodate the output data,
otherwise an error is returned. otherwise an error is returned.
A NULL pointer can be provided as buffer in order A NULL pointer can be provided as buffer in order