keyctl.2: Further details for KEYCTL_READ

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

man2/keyctl.2

@@ -754,6 +754,11 @@ The ID of the key whose payload is to be read is specified in
 .I arg2
 (cast to
 .IR key_serial_t ).
+This can be the ID of an existing key,
+or any of the special key IDs listed for
+.BR KEYCTL_SEARCH .
+.\" including KEY_SPEC_REQKEY_AUTH_KEY
+
 The payload is placed in the buffer pointed by
 .I arg3
 (cast to
@@ -763,10 +768,34 @@ the size of that buffer must be specified in
 (cast to
 .IR size_t ).
 
+The returned data will be processed for presentation
+according to the key type.
+For example, a keyring will return an array of
+.I key_serial_t
+entries representing the IDs of all the keys that are linked to it.
+The
+.IR "user"
+key type will return its data as is.
+If a key type does not implement this function,
+the operation fails with the error
+.BR EOPNOTSUPP .
+
+If
+.I arg3
+is not NULL,
+as much of the payload data as will fit is copied into the buffer.
+On a successful return,
+the return value is always the total size of the payload data.
+To determine whether the buffer was of sufficient size,
+check to see that the return value is less than or equal to
+the value supplied in
+.IR arg4 .
+
 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.
 
 The
@@ -1474,6 +1503,14 @@ a different type was provided.
 .B EOPNOTSUPP
 .I operation
 is
+.B KEYCTL_READ
+and the key type does not support reading
+(e.g., the type is
+.IR """login""" ).
+.TP
+.B EOPNOTSUPP
+.I operation
+is
 .B KEYCTL_UPDATE
 and the key type does not support updating.
 .TP