From 9f79744c9af3a1d7bb5be3593c1032351c04acd7 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Wed, 19 Oct 2016 16:22:44 +0200
Subject: [PATCH] keyctl.2: Improve KEYCTL_INSTANTIATE details

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man2/keyctl.2 | 46 +++++++++++++++++++++++++++++++---------------
 1 file changed, 31 insertions(+), 15 deletions(-)

diff --git a/man2/keyctl.2 b/man2/keyctl.2
index 5397b8cfd..a6497a9dd 100644
--- a/man2/keyctl.2
+++ b/man2/keyctl.2
@@ -741,23 +741,39 @@ via the function
 .BR keyctl_read (3).
 .TP
 .BR KEYCTL_INSTANTIATE " (since Linux 2.6.11)"
-Instantiate a partially constructed key whose ID is provided in the
+Instantiate a partially constructed key with a specified payload.
+
+The ID of the key to be instantiated is provided in
 .I arg2
-argument (cast to
-.IR key_serial_t )
-with a payload pointed by the
-.I arg3
-argument (cast to
-.IR "char\ *")
-of size provided in the
-.I arg4
-argument (cast to
-.IR size_t ).
-The instantiated key will be linked to the keyring ID which is provided in the
-.I arg5
-argument (cast to
+(cast to
 .IR key_serial_t ).
-The caller must have the appropriate instantiation permit set (auth key).
+
+The key payload is specified in the buffer pointed to by
+.I arg3
+(cast to
+.IR "void\ *");
+the size of that buffer is specified in
+.I arg4
+(cast to
+.IR size_t ).
+
+The payload may be a NULL pointer and the buffer size may be 0
+if this is supported by the key type.
+The operation may be fail if the payload data is in the wrong format
+or is otherwise invalid.
+
+If
+.I arg5
+(cast to
+.IR key_serial_t )
+is nonzero, then, subject to the same constraints and rules as
+.BR KEYCTL_LINK ,
+the instantiated key is linked into the keyring whose ID specified in
+.IR arg5 .
+
+The caller must have the appropriate authorization key;
+see
+.BR request_key (2).
 
 This operation is exposed by
 .I libkeyutils