Params API: {utf8,octet}_ptr need to know the data size

[openssl.git] / doc / man3 / OSSL_PARAM_TYPE.pod

diff --git a/doc/man3/OSSL_PARAM_TYPE.pod b/doc/man3/OSSL_PARAM_TYPE.pod
index dd887f3089596c61d0be8cd70330cbe7a86c9975..4585f25acd5aee695a7ddf2e66510f95eeec13eb 100644 (file)
--- a/doc/man3/OSSL_PARAM_TYPE.pod
+++ b/doc/man3/OSSL_PARAM_TYPE.pod
@@ -44,9 +44,9 @@ OSSL_PARAM_set_octet_ptr
  OSSL_PARAM OSSL_PARAM_construct_octet_string(const char *key, void *buf,
                                               size_t bsize, size_t *rsize);
  OSSL_PARAM OSSL_PARAM_construct_utf8_ptr(const char *key, char **buf,
-                                          size_t *rsize);
+                                          size_t bsize, size_t *rsize);
  OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
-                                           size_t *rsize);
+                                           size_t bsize, size_t *rsize);
  OSSL_PARAM OSSL_PARAM_construct_end(void);
 
  OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
@@ -173,13 +173,13 @@ size B<rsize> is created.
 
 OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string
 pointer OSSL_PARAM structure.
-A parameter with name B<key>, storage pointer B<*buf> and return size B<rsize>
-is created.
+A parameter with name B<key>, storage pointer B<*buf>, size B<bsize> and
+return size B<rsize> is created.
 
 OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string
 pointer OSSL_PARAM structure.
-A parameter with name B<key>, storage pointer B<*buf> and return size B<rsize>
-is created.
+A parameter with name B<key>, storage pointer B<*buf>, size B<bsize> and
+return size B<rsize> is created.
 
 OSSL_PARAM_construct_end() is a function that constructs the terminating
 OSSL_PARAM structure.
@@ -254,6 +254,13 @@ Integral types will be widened and sign extended as required.
 Apart from that, the functions must be used appropriately for the
 expected type of the parameter.
 
+For OSSL_PARAM_get_utf8_ptr() and OSSL_PARAM_get_octet_ptr(), B<bsize>
+is not relevant if the purpose is to send the B<OSSL_PARAM> array to a
+I<responder>, i.e. to get parameter data back.
+In that case, B<bsize> can safely be given zero.
+See L<OSSL_PARAM(3)/DESCRIPTION> for further information on the
+possible purposes.
+
 =head1 EXAMPLES
 
 Reusing the examples from L<OSSL_PARAM(3)> to just show how