add_key.2: Rework some text + remove FIXMEs after discussion with David Howells

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

diff --git a/man2/add_key.2 b/man2/add_key.2
index 88a52e5ff55aedf10e881a0e91d8dfc81a596137..f19ba4f49021516b73557bce90b9ecd93b27df79 100644 (file)
--- a/man2/add_key.2
+++ b/man2/add_key.2
@@ -46,12 +46,10 @@ already contains a key that matches the specified
 .IR type
 and
 .IR description ,
-then, if the key type supports it, that key will be updated rather than a new
-key being created; if not, a new key will be created and it will displace the
-link to the extant key from the keyring.
-.\" FIXME In the previous paragraph, what is the significance of the fact
-.\" that in some cases the existing key is updated versus in other cases a
-.\" new key is created? Is it just that the key ID will be different?
+then, if the key type supports it,
+that key will be updated rather than a new key being created;
+if not, a new key (with a different ID) will be created
+and it will displace the link to the extant key from the keyring.
 .P
 The destination
 .I keyring
@@ -138,7 +136,8 @@ For this key type,
 the contents can be saved in a tmpfs filesystem and
 thus swapped out to disk when memory pressure is high.
 This key type is useful for tasks such as holding Kerberos ticket caches.
-.\" FIXME Are there any other key tpes available for user-space use?
+.\" David Howells: there are also other key types available for
+.\" user-space use.
 .SH RETURN VALUE
 On success,
 .BR add_key ()
@@ -146,9 +145,6 @@ returns the serial number of the key it created or updated.
 On error, \-1 is returned and
 .I errno
 is set to indicate the cause of the error.
-.\" FIXME Is there any difference between the terms "key serial number"
-.\" and "key ID"? What about "special key IDs"? (Can one equally talk
-.\" of a "special key serial number"? 
 .SH ERRORS
 .TP
 .B EACCES