OSSL_PARAM.pod: document the mechanism to figure out buffer sizes

When requesting parameters, it's acceptable to make a first pass with
the |data| field of some parameters being NULL.  That can be used to
help the requestor to figure out dynamically what buffer size is
needed.  For variable size parameters, there's no other way to find
out.

Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/10025)

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index 361028fa00d7b2feb1ddb71e414cd65b3e89d613..df532b42643414abedd5a29a898b387c07f4bb6c 100644 (file)
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -87,6 +87,11 @@ setting parameters) or shall (when requesting parameters) be stored,
 and I<data_size> is its size in bytes.
 The organization of the data depends on the parameter type and flag.
 
+When I<requesting parameters>, it's acceptable for I<data> to be NULL.
+This can be used by the I<requestor> to figure out dynamically exactly
+how much buffer space is needed to store the parameter data.
+In this case, I<data_size> is ignored.
+
 When the B<OSSL_PARAM> is used as a parameter descriptor, I<data>
 should be ignored.
 If I<data_size> is zero, it means that an arbitrary data size is