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 25b8701..4f482ee 100644
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -7,7 +7,7 @@
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 @@
#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 @@
=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 @@
=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 @@
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.
-OSSL_PARAM_construct_TYPE() are a series of functions that create OSSL_PARAM
+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 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 @@
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 @@
=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 7bdb96c..6b7f9fa 100644
--- a/util/missingmacro.txt
+++ b/util/missingmacro.txt
@@ -99,7 +99,6 @@
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)
