From 1fe70a6764f837f2ed96b5a832f7ef4541513eb7 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Sat, 29 Oct 2016 11:42:31 +0200 Subject: [PATCH] keyctl.2: srcfix: FIXME clean-up Signed-off-by: Michael Kerrisk --- man2/keyctl.2 | 41 ++++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/man2/keyctl.2 b/man2/keyctl.2 index 394e918b4..51eba843c 100644 --- a/man2/keyctl.2 +++ b/man2/keyctl.2 @@ -161,7 +161,7 @@ and the behavior is as follows: If a keyring with a matching description exists, the process will attempt to subscribe to that keyring if possible; if that is not possible, an error is returned. -.\" FIXME What error is returned? +.\" FIXME What error is returned in the above case? In order to subscribe to the keyring, the caller must have .I search @@ -235,8 +235,8 @@ or .IR setattr permission on the key. .\" FIXME Keys with the KEY_FLAG_KEEP bit set cause an EPERM -.\" error for KEYCTL_REVOKE. Does this need to be documented? -.\" (It's not clear how KEY_FLAG_KEEP gets set.) +.\" error for KEYCTL_REVOKE. Does this need to be documented? +.\" (It's not clear how KEY_FLAG_KEEP gets set.) The arguments .IR arg3 , @@ -723,8 +723,9 @@ then that link will be displaced by a link to the key found by this operation. Instead of valid existing keyring IDs, the source -.\" FIXME Is it really true that both of these arguments can be -.\" special key IDs? +.\" FIXME Regarding the next sentence: +.\" Is it really true that both 'arg2' (keyring to search) +.\" and 'arg5' (destination keyring) can be special key IDs? .RI ( arg2 ) and destination .RI ( arg5 ) @@ -784,8 +785,8 @@ The key must either grant the caller .I read permission, or grant the caller .I search -.\" FIXME What does the following piece mean? permission when searched for from the process keyrings. +.\" FIXME Above, what does "searched for from the process keyrings" mean? The .I arg5 @@ -797,7 +798,6 @@ via the function .BR keyctl_read (3). .TP .BR KEYCTL_INSTANTIATE " (since Linux 2.6.11)" -.\" FIXME There's a lot more detail to add here... .\" FIXME I added the word "(Positively)" in the next sentence. Okay? (Positively) instantiate an uninstantiated key with a specified payload. @@ -817,6 +817,9 @@ the size of that buffer is specified in The payload may be a NULL pointer and the buffer size may be 0 if this is supported by the key type. +.\" FIXME Above, what is an example of a key type that supports a +.\" a NULL payload plus buffer size of zero? Keyrings? + The operation may be fail if the payload data is in the wrong format or is otherwise invalid. @@ -856,10 +859,13 @@ via the function .TP .BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)" Set the default keyring to which implicitly requested keys -.\" FIXME What are implcitly requested keys? +.\" FIXME What are implicitly requested keys? .\" -.\" The implicit requests make use of the kernel-internal request_key() -.\" function (which is not the same as the request_key(2) system call). +.\" Are implicit requests just the ones that use the kernel-internal +.\" request_key() function (which is not the same as the request_key(2) +.\" system call)? +.\" +.\" Does this operation have any effect for the request_key(2) system call? will be linked for this thread, and return the previous setting. Implicit key requests can occur when, for example, opening files on an AFS or NFS filesystem. @@ -872,9 +878,9 @@ should contain one of the following values, to specify the new default keyring: .RS .TP -.\" FIXME: what is the purpose of KEY_REQKEY_DEFL_NO_CHANGE? .BR KEY_REQKEY_DEFL_NO_CHANGE No change. +.\" FIXME: What is the purpose of KEY_REQKEY_DEFL_NO_CHANGE? .TP .BR KEY_REQKEY_DEFL_DEFAULT This selects the default behaviour, @@ -911,8 +917,8 @@ as the new default keyring. .TP .BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)" '\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640 -.\" FIXME The following needs to be expanded. Use the requestor keyring. +.\" FIXME The preceding explanation needs to be expanded. .RE .IP All other values are invalid. @@ -937,10 +943,11 @@ via the function .TP .BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)" .\" FIXME Against which clock is the timeout measured? -.\" (It looks to be the REALTIME clock) -.\" FIXME Other than looking in /proc/keys, is there any way of -.\" discovering the timeout on a key? +.\" (It looks to be the REALTIME clock; was there a particular reason to +.\" choose the REALTIME clock over the MONOTONIC clock?) Set a timeout on a key. +.\" FIXME Other than looking in /proc/keys, is there any way of +.\" discovering the timeout on a key? The ID of the key is specified in .I arg2 @@ -1498,8 +1505,8 @@ for keyrings to be exceeded. .TP .B ENFILE .\" FIXME Does this error really occur? I could not find where -.\" in the kernel source it is generated, but have not tested -.\" this case from a user-space program +.\" in the kernel source it is generated, but have not tested +.\" this case from a user-space program .IR operation is .BR KEYCTL_LINK