Params: add OSSL_PARAM_construct_end()

[openssl.git] / doc / man3 / OSSL_PARAM_TYPE.pod

diff --git a/doc/man3/OSSL_PARAM_TYPE.pod b/doc/man3/OSSL_PARAM_TYPE.pod
index c4ca37a344494befe5e396aa9afec0134fb843f0..dd887f3089596c61d0be8cd70330cbe7a86c9975 100644 (file)
--- a/doc/man3/OSSL_PARAM_TYPE.pod
+++ b/doc/man3/OSSL_PARAM_TYPE.pod
@@ -10,7 +10,8 @@ OSSL_PARAM_SIZED_octet_ptr, OSSL_PARAM_END, OSSL_PARAM_construct_TYPE,
 OSSL_PARAM_END,
 OSSL_PARAM_construct_BN, OSSL_PARAM_construct_utf8_string,
 OSSL_PARAM_construct_utf8_ptr, OSSL_PARAM_construct_octet_string,
-OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_locate, OSSL_PARAM_get_TYPE,
+OSSL_PARAM_construct_octet_ptr, OSSL_PARAM_construct_end,
+OSSL_PARAM_locate, OSSL_PARAM_get_TYPE,
 OSSL_PARAM_set_TYPE, OSSL_PARAM_get_BN, OSSL_PARAM_set_BN,
 OSSL_PARAM_get_utf8_string, OSSL_PARAM_set_utf8_string,
 OSSL_PARAM_get_octet_string, OSSL_PARAM_set_octet_string,
@@ -46,6 +47,7 @@ OSSL_PARAM_set_octet_ptr
                                           size_t *rsize);
  OSSL_PARAM OSSL_PARAM_construct_octet_ptr(const char *key, void **buf,
                                            size_t *rsize);
+ OSSL_PARAM OSSL_PARAM_construct_end(void);
 
  OSSL_PARAM *OSSL_PARAM_locate(OSSL_PARAM *array, const char *key);
 
@@ -179,6 +181,9 @@ pointer OSSL_PARAM structure.
 A parameter with name B<key>, storage pointer B<*buf> and return size B<rsize>
 is created.
 
+OSSL_PARAM_construct_end() is a function that constructs the terminating
+OSSL_PARAM structure.
+
 OSSL_PARAM_locate() is a function that searches an B<array> of parameters for
 the one matching the B<key> name.
 
@@ -272,7 +277,9 @@ This example is for setting parameters on some object:
 
 =head2 Example 2
 
-This example is for requesting parameters on some object:
+This example is for requesting parameters on some object, and also
+demonstrates that the requestor isn't obligated to request all
+available parameters:
 
     const char *foo = NULL;
     size_t foo_l;
@@ -289,8 +296,14 @@ could fill in the parameters like this:
 
     /* const OSSL_PARAM *params */
 
-    OSSL_PARAM_set_utf8_ptr(OSSL_PARAM_locate(params, "foo"), "foo value");
-    OSSL_PARAM_set_utf8_string(OSSL_PARAM_locate(params, "bar"), "bar value");
+    const OSSL_PARAM *p;
+
+    if ((p = OSSL_PARAM_locate(params, "foo")) == NULL)
+        OSSL_PARAM_set_utf8_ptr(p, "foo value");
+    if ((p = OSSL_PARAM_locate(params, "bar")) == NULL)
+        OSSL_PARAM_set_utf8_ptr(p, "bar value");
+    if ((p = OSSL_PARAM_locate(params, "cookie")) == NULL)
+        OSSL_PARAM_set_utf8_ptr(p, "cookie value");
 
 =head1 SEE ALSO