diff options
| author | Richard Levitte <levitte@openssl.org> | 2020-11-23 03:03:28 +0100 |
|---|---|---|
| committer | Richard Levitte <levitte@openssl.org> | 2020-11-26 11:10:43 +0100 |
| commit | c589c1495bdabd02a33546f9e7b849fd912130d1 (patch) | |
| tree | bbb6624a5766aadcd51cd37dc5373fc7e7b12049 | |
| parent | 2d840893e78253bcce428603fdbcda159bdebe08 (diff) | |
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)
| -rw-r--r-- | doc/man3/OSSL_PARAM.pod | 14 |
1 files 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) |