QuasarApp/openssl
4
0
Fork 0
mirror of https://github.com/QuasarApp/openssl.git synced 2025-04-27 18:24:37 +00:00
Code Issues Projects Releases Wiki Activity

Document the OSSL_PARAM_DEFN macro

Browse Source 
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)
This commit is contained in:
Matt Caswell 2021-02-17 17:41:10 +00:00
parent 18b207c798
commit 510d019141
2 changed files with 23 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
doc/man3/OSSL_PARAM_int.pod
View File

@ -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.
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 @@ 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

1
util/missingmacro.txt
View File

@ -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)