pkcs11: clarify gnutls_pkcs11_*_get_info output_size

It was not clear whether @output_size contains the actual string length
or the buffer length (including null terminator).

Signed-off-by: Peter Wu <peter@lekensteyn.nl>

1 files changed, 15 insertions, 4 deletions

diff --git a/lib/pkcs11.c b/lib/pkcs11.c
index 1a335ea959..3b81aa4dd2 100644
--- a/lib/pkcs11.c
+++ b/lib/pkcs11.c
@@ -612,12 +612,17 @@ gnutls_pkcs11_obj_set_info(gnutls_pkcs11_obj_t obj,
  * @obj: should contain a #gnutls_pkcs11_obj_t type
  * @itype: Denotes the type of information requested
  * @output: where output will be stored
- * @output_size: contains the maximum size of the output and will be overwritten with actual
+ * @output_size: contains the maximum size of the output buffer and will be
+ *     overwritten with the actual size.
  *
  * This function will return information about the PKCS11 certificate
  * such as the label, id as well as token information where the key is
- * stored. When output is text it returns null terminated string
- * although @output_size contains the size of the actual data only.
+ * stored.
+ *
+ * When output is text, a null terminated string is written to @output and its
+ * string length is written to @output_size (without null terminator). If the
+ * buffer is too small, @output_size will contain the expected buffer size
+ * (with null terminator for text) and return %GNUTLS_E_SHORT_MEMORY_BUFFER.
  *
  * In versions previously to 3.6.0 this function included the null terminator
  * to @output_size. After 3.6.0 the output size doesn't include the terminator character.
@@ -2447,11 +2452,17 @@ gnutls_pkcs11_token_get_url(unsigned int seq,
  * @url: should contain a PKCS 11 URL
  * @ttype: Denotes the type of information requested
  * @output: where output will be stored
- * @output_size: contains the maximum size of the output and will be overwritten with actual
+ * @output_size: contains the maximum size of the output buffer and will be
+ *     overwritten with the actual size.
  *
  * This function will return information about the PKCS 11 token such
  * as the label, id, etc.
  *
+ * When output is text, a null terminated string is written to @output and its
+ * string length is written to @output_size (without null terminator). If the
+ * buffer is too small, @output_size will contain the expected buffer size
+ * (with null terminator for text) and return %GNUTLS_E_SHORT_MEMORY_BUFFER.
+ *
  * Returns: %GNUTLS_E_SUCCESS (0) on success or a negative error code
  * on error.
  *