From c589c1495bdabd02a33546f9e7b849fd912130d1 Mon Sep 17 00:00:00 2001
From: Richard Levitte <levitte@openssl.org>
Date: Mon, 23 Nov 2020 03:03:28 +0100
Subject: 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.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/13478)
---
 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)
-- 
cgit v1.2.3