From: Richard Levitte <levitte@openssl.org>
Date: Thu, 26 Sep 2019 05:42:06 +0000 (+0200)
Subject: OSSL_PARAM.pod: document the mechanism to figure out buffer sizes
X-Git-Tag: openssl-3.0.0-alpha1~1267
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=d4d28783473e5b4417068258f2553896ff618600;p=oweals%2Fopenssl.git

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 361028fa00..df532b4264 100644
--- 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