The branch master has been updated
via c589c1495bdabd02a33546f9e7b849fd912130d1 (commit)
from 2d840893e78253bcce428603fdbcda159bdebe08 (commit)
- Log -----------------------------------------------------------------
commit c589c1495bdabd02a33546f9e7b849fd912130d1
Author: Richard Levitte <levi...@openssl.org>
Date: Mon Nov 23 03:03:28 2020 +0100
DOC: Add note on how to terminate an OSSL_PARAM array
The examples are also updated to have correct terminators.
doc/man3/OSSL_PARAM.pod is deliberately written with no help from the
constructor macros described in OSSL_PARAM_int.pod. Therefore, use of
OSSL_PARAM_END isn't shown directly here, only leaving a link to its
man-page to indicate that there is that option.
Fixes #11280
Reviewed-by: Paul Dale <paul.d...@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13478)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/OSSL_PARAM.pod | 14 ++++++++++++--
1 file changed, 12 insertions(+), 2 deletions(-)
diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index 044b7a5c42..fdf376a206 100644
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -64,6 +64,13 @@ Normally, the order of the an B<OSSL_PARAM> array is not
relevant.
However, if the I<responder> can handle multiple elements with the
same key, those elements must be handled in the order they are in.
+An B<OSSL_PARAM> array must have a terminating element, where I<key>
+is NULL. The usual full terminating template is:
+
+ { NULL, 0, NULL, 0, 0 }
+
+This can also be specified using L<OSSL_PARAM_END(3)>.
+
=head2 B<OSSL_PARAM> fields
=over 4
@@ -72,6 +79,9 @@ same key, those elements must be handled in the order they
are in.
The identity of the parameter in the form of a string.
+In an B<OSSL_PARAM> array, an item with this field set to NULL is
+considered a terminating item.
+
=item I<data_type>
The I<data_type> is a value that describes the type and organization of
@@ -288,7 +298,7 @@ This example is for setting parameters on some object:
OSSL_PARAM set[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, foo_l, 0 },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
- { NULL, 0, NULL, 0, NULL }
+ { NULL, 0, NULL, 0, 0 }
};
=head3 Example 2
@@ -302,7 +312,7 @@ This example is for requesting parameters on some object:
OSSL_PARAM request[] = {
{ "foo", OSSL_PARAM_UTF8_STRING_PTR, &foo, 0 /*irrelevant*/, 0 },
{ "bar", OSSL_PARAM_UTF8_STRING, &bar, sizeof(bar), 0 },
- { NULL, 0, NULL, 0, NULL }
+ { NULL, 0, NULL, 0, 0 }
};
A I<responder> that receives this array (as I<params> in this example)
