Document the OSSL_PARAM_DEFN macro

This macro was added since 1.1.1 and was undocumented.

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14232)

diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod
index 25b87014b74faad57b1a00dc495a00bb6ff2b31c..4f482ee610bffe583e667325791c4cc0d6d5c510 100644 (file)
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -7,7 +7,7 @@ OSSL_PARAM_long, OSSL_PARAM_size_t, OSSL_PARAM_time_t, OSSL_PARAM_uint,
 OSSL_PARAM_uint32, OSSL_PARAM_uint64, OSSL_PARAM_ulong, OSSL_PARAM_BN,
 OSSL_PARAM_utf8_string, OSSL_PARAM_octet_string, OSSL_PARAM_utf8_ptr,
 OSSL_PARAM_octet_ptr,
-OSSL_PARAM_END,
+OSSL_PARAM_END, OSSL_PARAM_DEFN,
 OSSL_PARAM_construct_double, OSSL_PARAM_construct_int,
 OSSL_PARAM_construct_int32, OSSL_PARAM_construct_int64,
 OSSL_PARAM_construct_long, OSSL_PARAM_construct_size_t,
@@ -58,6 +58,9 @@ OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified
 
  #define OSSL_PARAM_UNMODIFIED
 
+ #define OSSL_PARAM_DEFN(key, type, addr, sz)    \
+    { (key), (type), (addr), (sz), OSSL_PARAM_UNMODIFIED }
+
  OSSL_PARAM OSSL_PARAM_construct_TYPE(const char *key, TYPE *buf);
  OSSL_PARAM OSSL_PARAM_construct_BN(const char *key, unsigned char *buf,
                                     size_t bsize);
@@ -107,7 +110,7 @@ OSSL_PARAM_UNMODIFIED, OSSL_PARAM_modified, OSSL_PARAM_set_all_unmodified
 =head1 DESCRIPTION
 
 A collection of utility functions that simplify and add type safety to the
-OSSL_PARAM arrays.  The following B<I<TYPE>> names are supported:
+B<OSSL_PARAM> arrays.  The following B<I<TYPE>> names are supported:
 
 =over 1
 
@@ -158,7 +161,7 @@ unsigned long int (ulong)
 =back
 
 OSSL_PARAM_TYPE() are a series of macros designed to assist initialising an
-array of OSSL_PARAM structures.
+array of B<OSSL_PARAM> structures.
 Each of these macros defines a parameter of the specified B<I<TYPE>> with the
 provided I<key> and parameter variable I<address>.
 
@@ -169,40 +172,46 @@ A parameter with name I<key> is defined.
 The storage for this parameter is at I<address> and is of I<size> bytes.
 
 OSSL_PARAM_END provides an end of parameter list marker.
-This should terminate all OSSL_PARAM arrays.
+This should terminate all B<OSSL_PARAM> arrays.
+
+The OSSL_PARAM_DEFN() macro provides the ability to construct a single
+B<OSSL_PARAM> (typically used in the construction of B<OSSL_PARAM> arrays). The
+I<key>, I<type>, I<addr> and I<sz> arguments correspond to the I<key>,
+I<data_type>, I<data> and I<data_size> fields of the B<OSSL_PARAM> structure as
+described on the L<OSSL_PARAM(3)> page.
 
-OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM
+OSSL_PARAM_construct_TYPE() are a series of functions that create B<OSSL_PARAM>
 records dynamically.
 A parameter with name I<key> is created.
 The parameter will use storage pointed to by I<buf> and return size of I<ret>.
 
 OSSL_PARAM_construct_BN() is a function that constructs a large integer
-OSSL_PARAM structure.
+B<OSSL_PARAM> structure.
 A parameter with name I<key>, storage I<buf>, size I<bsize> and return
 size I<rsize> is created.
 
 OSSL_PARAM_construct_utf8_string() is a function that constructs a UTF8
-string OSSL_PARAM structure.
+string B<OSSL_PARAM> structure.
 A parameter with name I<key>, storage I<buf> and size I<bsize> is created.
 If I<bsize> is zero, the string length is determined using strlen(3).
 Generally pass zero for I<bsize> instead of calling strlen(3) yourself.
 
 OSSL_PARAM_construct_octet_string() is a function that constructs an OCTET
-string OSSL_PARAM structure.
+string B<OSSL_PARAM> structure.
 A parameter with name I<key>, storage I<buf> and size I<bsize> is created.
 
 OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF string
-pointer OSSL_PARAM structure.
+pointer B<OSSL_PARAM> structure.
 A parameter with name I<key>, storage pointer I<*buf> and size I<bsize>
 is created.
 
 OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string
-pointer OSSL_PARAM structure.
+pointer B<OSSL_PARAM> structure.
 A parameter with name I<key>, storage pointer I<*buf> and size I<bsize>
 is created.
 
 OSSL_PARAM_construct_end() is a function that constructs the terminating
-OSSL_PARAM structure.
+B<OSSL_PARAM> structure.
 
 OSSL_PARAM_locate() is a function that searches an I<array> of parameters for
 the one matching the I<key> name.
@@ -299,10 +308,10 @@ in the array I<params>.
 OSSL_PARAM_construct_TYPE(), OSSL_PARAM_construct_BN(),
 OSSL_PARAM_construct_utf8_string(), OSSL_PARAM_construct_octet_string(),
 OSSL_PARAM_construct_utf8_ptr() and OSSL_PARAM_construct_octet_ptr()
-return a populated OSSL_PARAM structure.
+return a populated B<OSSL_PARAM> structure.
 
 OSSL_PARAM_locate() and OSSL_PARAM_locate_const() return a pointer to
-the matching OSSL_PARAM object.  They return NULL on error or when
+the matching B<OSSL_PARAM> object.  They return NULL on error or when
 no object matching I<key> exists in the I<array>.
 
 OSSL_PARAM_modified() returns 1 if the parameter was set and 0 otherwise.
@@ -326,7 +335,7 @@ possible purposes.
 =head1 EXAMPLES
 
 Reusing the examples from L<OSSL_PARAM(3)> to just show how
-C<OSSL_PARAM> arrays can be handled using the macros and functions
+B<OSSL_PARAM> arrays can be handled using the macros and functions
 defined herein.
 
 =head2 Example 1

diff --git a/util/missingmacro.txt b/util/missingmacro.txt
index 7bdb96c0d45f5c315bfc2908ae844f781afdc1ab..6b7f9fa2b323063fa96e391b22e710e55a846705 100644 (file)
--- a/util/missingmacro.txt
+++ b/util/missingmacro.txt
@@ -99,7 +99,6 @@ PEM_write_bio_OCSP_REQUEST(3)
 PEM_write_bio_OCSP_RESPONSE(3)
 ASN1_BIT_STRING_digest(3)
 OCSP_CERTSTATUS_dup(3)
-OSSL_PARAM_DEFN(3)
 OSSL_PARAM_SIZED_int(3)
 OSSL_PARAM_SIZED_uint(3)
 OSSL_PARAM_SIZED_long(3)