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,
  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,
  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);
  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.
 
 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.
 
 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.
 
 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.
 
 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
 =head1 EXAMPLES
 
 Reusing the examples from L<OSSL_PARAM(3)> to just show how