=end comment
SPARSE_ARRAY_OF() returns the name for a sparse array of the specified
-I<TYPE>. DEFINE_STACK_OF() creates set of functions for a sparse array of
-I<TYPE>. This will mean that a pointer to type I<TYPE> is stored in each
-element of a sparse array, the type is referenced by B<SPARSE_ARRAY_OF>(I<TYPE>)
-and each function name begins with B<ossl_sa_I<TYPE>_>. For example:
+B<I<TYPE>>. DEFINE_STACK_OF() creates set of functions for a sparse
+array of B<I<TYPE>>. This will mean that a pointer to type B<I<TYPE>>
+is stored in each element of a sparse array, the type is referenced by
+B<SPARSE_ARRAY_OF>(B<I<TYPE>>) and each function name begins with
+B<ossl_sa_I<TYPE>_>. For example:
TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx);
=head1 DESCRIPTION
A collection of utility functions that simplify the creation of OSSL_PARAM
-arrays. The B<TYPE> names are as per L<OSSL_PARAM_int(3)>.
+arrays. The B<I<TYPE>> names are as per L<OSSL_PARAM_int(3)>.
ossl_param_bld_init() initialises the OSSL_PARAM_BLD structure so that values
can be added.
Applications can create and use their own stacks by placing any of the macros
described below in a header file. These macros define typesafe inline
functions that wrap around the utility B<OPENSSL_sk_> API.
-In the description here, I<TYPE> is used
-as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
+In the description here, B<I<TYPE>> is used
+as a placeholder for any of the OpenSSL datatypes, such as B<X509>.
-STACK_OF() returns the name for a stack of the specified B<TYPE>.
-DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This
-will mean that type B<TYPE> is stored in each stack, the type is referenced by
-STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example:
+STACK_OF() returns the name for a stack of the specified B<I<TYPE>>.
+DEFINE_STACK_OF() creates set of functions for a stack of B<I<TYPE>>. This
+will mean that type B<I<TYPE>> is stored in each stack, the type is referenced by
+B<STACK_OF>(B<I<TYPE>>) and each function name begins with B<sk_I<TYPE>_>.
+For example:
TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
-DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but
+DEFINE_SPECIAL_STACK_OF() defines a stack of B<I<TYPE>> but
each function uses B<FUNCNAME> in the function name. For example:
TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
-sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is
-B<NULL>.
+B<sk_I<TYPE>_num>() returns the number of elements in I<sk> or -1 if I<sk> is
+NULL.
-sk_TYPE_value() returns element B<idx> in B<sk>, where B<idx> starts at
-zero. If B<idx> is out of range then B<NULL> is returned.
+B<sk_I<TYPE>_value>() returns element I<idx> in I<sk>, where I<idx> starts at
+zero. If I<idx> is out of range then NULL is returned.
-sk_TYPE_new() allocates a new empty stack using comparison function B<compare>.
-If B<compare> is B<NULL> then no comparison function is used. This function is
-equivalent to sk_TYPE_new_reserve(compare, 0).
+B<sk_I<TYPE>_new>() allocates a new empty stack using comparison function
+I<compare>. If I<compare> is NULL then no comparison function is used. This
+function is equivalent to B<sk_I<TYPE>_new_reserve>(I<compare>, 0).
-sk_TYPE_new_null() allocates a new empty stack with no comparison function. This
-function is equivalent to sk_TYPE_new_reserve(NULL, 0).
+B<sk_I<TYPE>_new_null>() allocates a new empty stack with no comparison
+function. This function is equivalent to B<sk_I<TYPE>_new_reserve>(NULL, 0).
-sk_TYPE_reserve() allocates additional memory in the B<sk> structure
-such that the next B<n> calls to sk_TYPE_insert(), sk_TYPE_push()
-or sk_TYPE_unshift() will not fail or cause memory to be allocated
-or reallocated. If B<n> is zero, any excess space allocated in the
-B<sk> structure is freed. On error B<sk> is unchanged.
+B<sk_I<TYPE>_reserve>() allocates additional memory in the I<sk> structure
+such that the next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>()
+or B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated
+or reallocated. If I<n> is zero, any excess space allocated in the
+I<sk> structure is freed. On error I<sk> is unchanged.
-sk_TYPE_new_reserve() allocates a new stack. The new stack will have additional
-memory allocated to hold B<n> elements if B<n> is positive. The next B<n> calls
-to sk_TYPE_insert(), sk_TYPE_push() or sk_TYPE_unshift() will not fail or cause
-memory to be allocated or reallocated. If B<n> is zero or less than zero, no
-memory is allocated. sk_TYPE_new_reserve() also sets the comparison function
-B<compare> to the newly created stack. If B<compare> is B<NULL> then no
-comparison function is used.
+B<sk_I<TYPE>_new_reserve>() allocates a new stack. The new stack will have
+additional memory allocated to hold I<n> elements if I<n> is positive.
+The next I<n> calls to B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() or
+B<sk_I<TYPE>_unshift>() will not fail or cause memory to be allocated or
+reallocated. If I<n> is zero or less than zero, no memory is allocated.
+B<sk_I<TYPE>_new_reserve>() also sets the comparison function I<compare>
+to the newly created stack. If I<compare> is NULL then no comparison
+function is used.
-sk_TYPE_set_cmp_func() sets the comparison function of B<sk> to B<compare>.
-The previous comparison function is returned or B<NULL> if there was
-no previous comparison function.
+B<sk_I<TYPE>_set_cmp_func>() sets the comparison function of I<sk> to
+I<compare>. The previous comparison function is returned or NULL if there
+was no previous comparison function.
-sk_TYPE_free() frees up the B<sk> structure. It does B<not> free up any
-elements of B<sk>. After this call B<sk> is no longer valid.
+B<sk_I<TYPE>_free>() frees up the I<sk> structure. It does I<not> free up any
+elements of I<sk>. After this call I<sk> is no longer valid.
-sk_TYPE_zero() sets the number of elements in B<sk> to zero. It does not free
-B<sk> so after this call B<sk> is still valid.
+B<sk_I<TYPE>_zero>() sets the number of elements in I<sk> to zero. It does not
+free I<sk> so after this call I<sk> is still valid.
-sk_TYPE_pop_free() frees up all elements of B<sk> and B<sk> itself. The
+B<sk_I<TYPE>_pop_free>() frees up all elements of I<sk> and I<sk> itself. The
free function freefunc() is called on each element to free it.
-sk_TYPE_delete() deletes element B<i> from B<sk>. It returns the deleted
-element or B<NULL> if B<i> is out of range.
+B<sk_I<TYPE>_delete>() deletes element I<i> from I<sk>. It returns the deleted
+element or NULL if I<i> is out of range.
-sk_TYPE_delete_ptr() deletes element matching B<ptr> from B<sk>. It returns
-
the deleted element or B<NULL> if no element matching B<ptr> was found.
+B<sk_I<TYPE>_delete_ptr>() deletes element matching I<ptr> from I<sk>. It
+
returns the deleted element or NULL if no element matching I<ptr> was found.
-sk_TYPE_insert() inserts B<ptr> into B<sk> at position B<idx>. Any existing
-elements at or after B<idx> are moved downwards. If B<idx> is out of range
-the new element is appended to B<sk>. sk_TYPE_insert() either returns the
-number of elements in B<sk> after the new element is inserted or zero if
-an error (such as memory allocation failure) occurred.
+B<sk_I<TYPE>_insert>() inserts I<ptr> into I<sk> at position I<idx>. Any
+existing elements at or after I<idx> are moved downwards. If I<idx> is out
+of range the new element is appended to I<sk>. B<sk_I<TYPE>_insert>() either
+returns the number of elements in I<sk> after the new element is inserted or
+zero if an error (such as memory allocation failure) occurred.
-sk_TYPE_push() appends B<ptr> to B<sk> it is equivalent to:
+B<sk_I<TYPE>_push>() appends I<ptr> to I<sk> it is equivalent to:
sk_TYPE_insert(sk, ptr, -1);
-sk_TYPE_unshift() inserts B<ptr> at the start of B<sk> it is equivalent to:
+B<sk_I<TYPE>_unshift>() inserts I<ptr> at the start of I<sk> it is equivalent
+to:
sk_TYPE_insert(sk, ptr, 0);
-sk_TYPE_pop() returns and removes the last element from B<sk>.
+B<sk_I<TYPE>_pop>() returns and removes the last element from I<sk>.
-sk_TYPE_shift() returns and removes the first element from B<sk>.
+B<sk_I<TYPE>_shift>() returns and removes the first element from I<sk>.
-
sk_TYPE_set() sets element B<idx> of B<sk> to B<ptr> replacing the current
-element. The new element value is returned or B<NULL> if an error occurred:
-this will only happen if B<sk> is B<NULL> or B<idx> is out of range.
+
B<sk_I<TYPE>_set>() sets element I<idx> of I<sk> to I<ptr> replacing the current
+element. The new element value is returned or NULL if an error occurred:
+this will only happen if I<sk> is NULL or I<idx> is out of range.
-
sk_TYPE_find() searches B<sk> for the element B<ptr>. In the case
+
B<sk_I<TYPE>_find>() searches I<sk> for the element I<ptr>. In the case
where no comparison function has been specified, the function performs
-a linear search for a pointer equal to
B<ptr>. The index of the first
+a linear search for a pointer equal to
I<ptr>. The index of the first
matching element is returned or B<-1> if there is no match. In the case
-where a comparison function has been specified, B<sk> is sorted then
-sk_TYPE_find() returns the index of a matching element or B<-1> if there
+where a comparison function has been specified, I<sk> is sorted then
+B<sk_I<TYPE>_find>() returns the index of a matching element or B<-1> if there
is no match. Note that, in this case, the matching element returned is
not guaranteed to be the first; the comparison function will usually
compare the values pointed to rather than the pointers themselves and
-the order of elements in B<sk> could change.
+the order of elements in I<sk> could change.
-sk_TYPE_find_ex() operates like sk_TYPE_find() except when a comparison
-function has been specified and no matching element is found. Instead
-of returning B<-1>, sk_TYPE_find_ex() returns the index of the element
-e
ither before or after the location where B<ptr> would be if it were
-present in B<sk>.
+B<sk_I<TYPE>_find_ex>() operates like B<sk_I<TYPE>_find>() except when a
+comparison function has been specified and no matching element is found.
+Instead of returning B<-1>, B<sk_I<TYPE>_find_ex>() returns the index of the
+e
lement either before or after the location where I<ptr> would be if it were
+present in I<sk>.
-sk_TYPE_sort() sorts B<sk> using the supplied comparison function.
+B<sk_I<TYPE>_sort>() sorts I<sk> using the supplied comparison function.
-sk_TYPE_is_sorted() returns B<1> if B<sk> is sorted and B<0> otherwise.
+B<sk_I<TYPE>_is_sorted>() returns B<1> if I<sk> is sorted and B<0> otherwise.
-sk_TYPE_dup() returns a copy of B<sk>. Note the pointers in the copy
+B<sk_I<TYPE>_dup>() returns a copy of I<sk>. Note the pointers in the copy
are identical to the original.
-sk_TYPE_deep_copy() returns a new stack where each element has been copied.
-Copying is performed by the supplied copyfunc() and freeing by freefunc(). The
-function freefunc() is only called if an error occurs.
+B<sk_I<TYPE>_deep_copy>() returns a new stack where each element has been
+copied. Copying is performed by the supplied copyfunc() and freeing by
+freefunc(). The function freefunc() is only called if an error occurs.
=head1 NOTES
Care should be taken when accessing stacks in multi-threaded environments.
-Any operation which increases the size of a stack such as sk_TYPE_insert() or
-sk_push() can "grow" the size of an internal array and cause race conditions
-if the same stack is accessed in a different thread. Operations such as
-sk_find() and sk_sort() can also reorder the stack.
+Any operation which increases the size of a stack such as B<sk_I<TYPE>_insert>()
+or B<sk_I<TYPE>_push>() can "grow" the size of an internal array and cause race
+conditions if the same stack is accessed in a different thread. Operations such
+as B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_sort>() can also reorder the stack.
Any comparison function supplied should use a metric suitable
for use in a binary search operation. That is it should return zero, a
-positive or negative value if
B<a> is equal to, greater than
-or less than B<b> respectively.
+positive or negative value if
I<a> is equal to, greater than
+or less than I<b> respectively.
Care should be taken when checking the return values of the functions
-sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the
+B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>(). They return an index to the
matching element. In particular B<0> indicates a matching first element.
A failed search is indicated by a B<-1> return value.
=head1 RETURN VALUES
-sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
-passed stack is B<NULL>.
+B<sk_I<TYPE>_num>() returns the number of elements in the stack or B<-1> if the
+passed stack is NULL.
-sk_TYPE_value() returns a pointer to a stack element or B<NULL> if the
+B<sk_I<TYPE>_value>() returns a pointer to a stack element or NULL if the
index is out of range.
-sk_TYPE_new(), sk_TYPE_new_null() and sk_TYPE_new_reserve() return an empty
-stack or B<NULL> if an error occurs.
+B<sk_I<TYPE>_new>(), B<sk_I<TYPE>_new_null>() and B<sk_I<TYPE>_new_reserve>()
+return an empty stack or NULL if an error occurs.
-sk_TYPE_reserve() returns B<1> on successful allocation of the required memory
-or B<0> on error.
+B<sk_I<TYPE>_reserve>() returns B<1> on successful allocation of the required
+memory or B<0> on error.
-sk_TYPE_set_cmp_func() returns the old comparison function or B<NULL> if
+B<sk_I<TYPE>_set_cmp_func>() returns the old comparison function or NULL if
there was no old comparison function.
-sk_TYPE_free(), sk_TYPE_zero(), sk_TYPE_pop_free() and sk_TYPE_sort() do
-not return values.
+B<sk_I<TYPE>_free>(), B<sk_I<TYPE>_zero>(), B<sk_I<TYPE>_pop_free>() and
+B<sk_I<TYPE>_sort>() do not return values.
-sk_TYPE_pop(), sk_TYPE_shift(), sk_TYPE_delete() and sk_TYPE_delete_ptr()
-return a pointer to the deleted element or B<NULL> on error.
+B<sk_I<TYPE>_pop>(), B<sk_I<TYPE>_shift>(), B<sk_I<TYPE>_delete>() and
+B<sk_I<TYPE>_delete_ptr>() return a pointer to the deleted element or NULL
+on error.
-sk_TYPE_insert(), sk_TYPE_push() and sk_TYPE_unshift() return the total
-number of elements in the stack and 0 if an error occurred.
+B<sk_I<TYPE>_insert>(), B<sk_I<TYPE>_push>() and B<sk_I<TYPE>_unshift>() return
+the total number of elements in the stack and 0 if an error occurred.
-sk_TYPE_set() returns a pointer to the replacement element or B<NULL> on
+B<sk_I<TYPE>_set>() returns a pointer to the replacement element or NULL on
error.
-sk_TYPE_find() and sk_TYPE_find_ex() return an index to the found element
-or B<-1> on error.
+B<sk_I<TYPE>_find>() and B<sk_I<TYPE>_find_ex>() return an index to the found
+element or B<-1> on error.
-sk_TYPE_is_sorted() returns B<1> if the stack is sorted and B<0> if it is
+B<sk_I<TYPE>_is_sorted>() returns B<1> if the stack is sorted and B<0> if it is
not.
-sk_TYPE_dup() and sk_TYPE_deep_copy() return a pointer to the copy of the
-stack.
+B<sk_I<TYPE>_dup>() and B<sk_I<TYPE>_deep_copy>() return a pointer to the copy
+of the stack.
=head1 HISTORY
Before OpenSSL 1.1.0, this was implemented via macros and not inline functions
and was not a public API.
-sk_TYPE_reserve() and sk_TYPE_new_reserve() were added in OpenSSL 1.1.1.
+B<sk_I<TYPE>_reserve>() and B<sk_I<TYPE>_new_reserve>() were added in OpenSSL
+1.1.1.
=head1 COPYRIGHT
This library implements type-checked dynamic hash tables. The hash
table entries can be arbitrary structures. Usually they consist of key
-and value fields. In the description here, I<TYPE> is used a placeholder
+and value fields. In the description here, B<I<TYPE>> is used a placeholder
for any of the OpenSSL datatypes, such as I<SSL_SESSION>.
-lh_TYPE_new() creates a new B<LHASH_OF(TYPE)> structure to store
+B<lh_I<TYPE>_new>() creates a new B<LHASH_OF>(B<I<TYPE>>) structure to store
arbitrary data entries, and specifies the 'hash' and 'compare'
-callbacks to be used in organising the table's entries. The B<hash>
+callbacks to be used in organising the table's entries. The I<hash>
callback takes a pointer to a table entry as its argument and returns
an unsigned long hash value for its key field. The hash value is
normally truncated to a power of 2, so make sure that your hash
-function returns well mixed low order bits. The B<compare> callback
+function returns well mixed low order bits. The I<compare> callback
takes two arguments (pointers to two hash table entries), and returns
0 if their keys are equal, non-zero otherwise.
If your hash table
-will contain items of some particular type and the B<hash> and
-B<compare> callbacks hash/compare these types, then the
+will contain items of some particular type and the I<hash> and
+I<compare> callbacks hash/compare these types, then the
B<IMPLEMENT_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be
used to create callback wrappers of the prototypes required by
-lh_TYPE_new() as shown in this example:
+B<lh_I<TYPE>_new>() as shown in this example:
/*
* Implement the hash and compare functions; "stuff" can be any word.
DECLARE_LHASH_HASH_FN(stuff, TYPE)
DECLARE_LHASH_COMP_FN(stuff, TYPE)
-Then a hash table of TYPE objects can be created using this:
+Then a hash table of B<I<TYPE>> objects can be created using this:
LHASH_OF(TYPE) *htable;
- htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
+ htable = B<lh_I<TYPE>_new>(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
-lh_TYPE_free() frees the B<LHASH_OF(TYPE)> structure
-
B<table>. Allocated hash table entries will not be freed; consider
-using lh_TYPE_doall() to deallocate any remaining entries in the
+B<lh_I<TYPE>_free>() frees the B<LHASH_OF>(B<I<TYPE>>) structure
+
I<table>. Allocated hash table entries will not be freed; consider
+using B<lh_I<TYPE>_doall>() to deallocate any remaining entries in the
hash table (see below).
-
lh_TYPE_flush() empties the B<LHASH_OF(TYPE)> structure B<table>. New
+
B<lh_I<TYPE>_flush>() empties the B<LHASH_OF>(B<I<TYPE>>) structure I<table>. New
entries can be added to the flushed table. Allocated hash table entries
-will not be freed; consider using lh_TYPE_doall() to deallocate any
+will not be freed; consider using B<lh_I<TYPE>_doall>() to deallocate any
remaining entries in the hash table (see below).
-lh_TYPE_insert() inserts the structure pointed to by B<data> into
-
B<table>. If there already is an entry with the same key, the old
-value is replaced. Note that lh_TYPE_insert() stores pointers, the
+B<lh_I<TYPE>_insert>() inserts the structure pointed to by I<data> into
+
I<table>. If there already is an entry with the same key, the old
+value is replaced. Note that B<lh_I<TYPE>_insert>() stores pointers, the
data are not copied.
-
lh_TYPE_delete() deletes an entry from B<table>.
+
B<lh_I<TYPE>_delete>() deletes an entry from I<table>.
-lh_TYPE_retrieve() looks up an entry in B<table>. Normally, B<data>
+B<lh_I<TYPE>_retrieve>() looks up an entry in I<table>. Normally, I<data>
is a structure with the key field(s) set; the function will return a
pointer to a fully populated structure.
-lh_TYPE_doall() will, for every entry in the hash table, call
-B<func> with the data item as its parameter.
+B<lh_I<TYPE>_doall>() will, for every entry in the hash table, call
+I<func> with the data item as its parameter.
For example:
/* Cleans up resources belonging to 'a' (this is implemented elsewhere) */
The best solution is probably to avoid deleting items from the hash
table inside a "doall" callback!
-lh_TYPE_doall_arg() is the same as lh_TYPE_doall() except that
-B<func> will be called with B<arg> as the second argument and B<func>
-should be of type B<LHASH_DOALL_ARG_FN_TYPE> (a callback prototype
+B<lh_I<TYPE>_doall_arg>() is the same as B<lh_I<TYPE>_doall>() except that
+I<func> will be called with I<arg> as the second argument and I<func>
+should be of type B<LHASH_DOALL_ARG_FN>(B<I<TYPE>>) (a callback prototype
that is passed both the table entry and an extra argument). As with
lh_doall(), you can instead choose to declare your callback with a
prototype matching the types you are dealing with and use the
logging_bio);
-lh_TYPE_error() can be used to determine if an error occurred in the last
+B<lh_I<TYPE>_error>() can be used to determine if an error occurred in the last
operation.
=head1 RETURN VALUES
-lh_TYPE_new() returns B<NULL> on error, otherwise a pointer to the new
+B<lh_I<TYPE>_new>() returns NULL on error, otherwise a pointer to the new
B<LHASH> structure.
-When a hash table entry is replaced, lh_TYPE_insert() returns the value
-being replaced. B<NULL> is returned on normal operation and on error.
+When a hash table entry is replaced, B<lh_I<TYPE>_insert>() returns the value
+being replaced. NULL is returned on normal operation and on error.
-lh_TYPE_delete() returns the entry being deleted. B<NULL> is returned if
+B<lh_I<TYPE>_delete>() returns the entry being deleted. NULL is returned if
there is no such value in the hash table.
-lh_TYPE_retrieve() returns the hash table entry if it has been found,
-B<NULL> otherwise.
+B<lh_I<TYPE>_retrieve>() returns the hash table entry if it has been found,
+NULL otherwise.
-lh_TYPE_error() returns 1 if an error occurred in the last operation, 0
+B<lh_I<TYPE>_error>() returns 1 if an error occurred in the last operation, 0
otherwise. It's meaningful only after non-retrieve operations.
-lh_TYPE_free(), lh_TYPE_flush, lh_TYPE_doall() and lh_TYPE_doall_arg()
-return no values.
+B<lh_I<TYPE>_free>(), B<lh_I<TYPE>_flush>(), B<lh_I<TYPE>_doall>() and
+B<lh_I<TYPE>_doall_arg>() return no values.
=head1 NOTE
The LHASH code is not thread safe. All updating operations, as well as
-lh_TYPE_error call must be performed under a write lock. All retrieve
+B<lh_I<TYPE>_error>() call must be performed under a write lock. All retrieve
operations should be performed under a read lock, I<unless> accurate
usage statistics are desired. In which case, a write lock should be used
for retrieve operations as well. For output of the usage statistics,
=head1 BUGS
-lh_TYPE_insert() returns B<NULL> both for success and error.
+B<lh_I<TYPE>_insert>() returns NULL both for success and error.
=head1 SEE ALSO
=head1 DESCRIPTION
-In the description below, I<TYPE> is used
-as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
+In the description below, B<I<TYPE>> is used
+as a placeholder for any of the OpenSSL datatypes, such as B<X509>.
The macro B<DECLARE_PEM_rw> expands to the set of declarations shown in
the next four lines of the synopsis.
L<ASN1_ITEM(3)>. For more information on the lower-level routines used
by the functions here, see L<PEM_read(3)>.
-PEM_read_TYPE() reads a PEM-encoded object of I<TYPE> from the file B<fp>
-and returns it. The B<cb> and B<u> parameters are as described in
+B<PEM_read_I<TYPE>>() reads a PEM-encoded object of B<I<TYPE>> from the file
+I<fp> and returns it. The I<cb> and I<u> parameters are as described in
L<pem_password_cb(3)>.
-PEM_read_bio_TYPE() is similar to PEM_read_TYPE() but reads from the BIO B<bp>.
+B<PEM_read_bio_I<TYPE>>() is similar to B<PEM_read_I<TYPE>>() but reads from
+the BIO I<bp>.
-PEM_write_TYPE() writes the PEM encoding of the object B<a> to the file B<fp>.
+B<PEM_write_I<TYPE>>() writes the PEM encoding of the object I<a> to the file
+I<fp>.
-PEM_write_bio_TYPE() similarly writes to the BIO B<bp>.
+B<PEM_write_bio_I<TYPE>>() similarly writes to the BIO I<bp>.
=head1 NOTES
=head1 RETURN VALUES
-PEM_read_TYPE() and PEM_read_bio_TYPE() return a pointer to an allocated
-object, which should be released by calling TYPE_free(), or NULL on error.
+B<PEM_read_I<TYPE>>() and B<PEM_read_bio_I<TYPE>>() return a pointer to an
+allocated object, which should be released by calling B<I<TYPE>_free>(), or
+NULL on error.
-PEM_write_TYPE() and PEM_write_bio_TYPE() return the number of bytes written
-or zero on error.
+B<PEM_write_I<TYPE>>() and B<PEM_write_bio_I<TYPE>>() return the number of bytes
+written or zero on error.
=head1 SEE ALSO
B<PEM FUNCTION ARGUMENTS> section.
Each operation has four functions associated with it. For
-brevity the term "B<TYPE> functions" will be used below to collectively
-refer to the PEM_read_bio_TYPE(), PEM_read_TYPE(),
-PEM_write_bio_TYPE(), and PEM_write_TYPE() functions.
+brevity the term "B<I<TYPE>> functions" will be used below to collectively
+refer to the B<PEM_read_bio_I<TYPE>>(), B<PEM_read_I<TYPE>>(),
+B<PEM_write_bio_I<TYPE>>(), and B<PEM_write_I<TYPE>>() functions.
The B<PrivateKey> functions read or write a private key in PEM format using an
EVP_PKEY structure. The write routines use PKCS#8 private key format and are
PEM_write_bio_PKCS8PrivateKey() and PEM_write_PKCS8PrivateKey() write a private
key in an EVP_PKEY structure in PKCS#8 EncryptedPrivateKeyInfo format using
-PKCS#5 v2.0 password based encryption algorithms. The B<cipher> argument
+PKCS#5 v2.0 password based encryption algorithms. The I<cipher> argument
specifies the encryption algorithm to use: unlike some other PEM routines the
encryption is applied at the PKCS#8 level and not in the PEM headers. If
-B<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
+I<cipher> is NULL then no encryption is used and a PKCS#8 PrivateKeyInfo
structure is used instead.
PEM_write_bio_PKCS8PrivateKey_nid() and PEM_write_PKCS8PrivateKey_nid()
also write out a private key as a PKCS#8 EncryptedPrivateKeyInfo however
it uses PKCS#5 v1.5 or PKCS#12 encryption algorithms instead. The algorithm
-to use is specified in the B<nid> parameter and should be the NID of the
+to use is specified in the I<nid> parameter and should be the NID of the
corresponding OBJECT IDENTIFIER (see NOTES section).
The B<PUBKEY> functions process a public key using an EVP_PKEY
The PEM functions have many common arguments.
-The B<bp> BIO parameter (if present) specifies the BIO to read from
+The I<bp> BIO parameter (if present) specifies the BIO to read from
or write to.
-The B<fp> FILE parameter (if present) specifies the FILE pointer to
+The I<fp> FILE parameter (if present) specifies the FILE pointer to
read from or write to.
-The PEM read functions all take an argument B<TYPE **x> and return
-a B<TYPE *> pointer. Where B<TYPE> is whatever structure the function
-uses. If B<x> is NULL then the parameter is ignored. If B<x> is not
-NULL but B<*x> is NULL then the structure returned will be written
-to B<*x>. If neither B<x> nor B<*x> is NULL then an attempt is made
-to reuse the structure at B<*x> (but see BUGS and EXAMPLES sections).
-Irrespective of the value of B<x> a pointer to the structure is always
+The PEM read functions all take an argument I<B<TYPE> **x> and return
+a I<B<TYPE> *> pointer. Where I<B<TYPE>> is whatever structure the function
+uses. If I<x> is NULL then the parameter is ignored. If I<x> is not
+NULL but I<*x> is NULL then the structure returned will be written
+to I<*x>. If neither I<x> nor I<*x> is NULL then an attempt is made
+to reuse the structure at I<*x> (but see BUGS and EXAMPLES sections).
+Irrespective of the value of I<x> a pointer to the structure is always
returned (or NULL if an error occurred).
-The PEM functions which write private keys take an B<enc> parameter
+The PEM functions which write private keys take an I<enc> parameter
which specifies the encryption algorithm to use, encryption is done
at the PEM level. If this parameter is set to NULL then the private
key is written in unencrypted form.
-The B<cb> argument is the callback to use when querying for the pass
+The I<cb> argument is the callback to use when querying for the pass
phrase used for encrypted PEM structures (normally only private keys).
-For the PEM write routines if the B<kstr> parameter is not NULL then
-B<klen> bytes at B<kstr> are used as the passphrase and B<cb> is
+For the PEM write routines if the I<kstr> parameter is not NULL then
+I<klen> bytes at I<kstr> are used as the passphrase and I<cb> is
ignored.
-If the B<cb> parameters is set to NULL and the B<u> parameter is not
-NULL then the B<u> parameter is interpreted as a null terminated string
-to use as the passphrase. If both B<cb> and B<u> are NULL then the
+If the I<cb> parameters is set to NULL and the I<u> parameter is not
+NULL then the I<u> parameter is interpreted as a null terminated string
+to use as the passphrase. If both I<cb> and I<u> are NULL then the
default callback routine is used which will typically prompt for the
passphrase on the current terminal with echoing turned off.
int cb(char *buf, int size, int rwflag, void *u);
-B<buf> is the buffer to write the passphrase to. B<size> is the maximum
-length of the passphrase (i.e. the size of buf). B<rwflag> is a flag
+I<buf> is the buffer to write the passphrase to. I<size> is the maximum
+length of the passphrase (i.e. the size of buf). I<rwflag> is a flag
which is set to 0 when reading and 1 when writing. A typical routine
will ask the user to verify the passphrase (for example by prompting
-for it twice) if B<rwflag> is 1. The B<u> parameter has the same
-value as the B<u> parameter passed to the PEM routine. It allows
+for it twice) if I<rwflag> is 1. The I<u> parameter has the same
+value as the I<u> parameter passed to the PEM routine. It allows
arbitrary data to be passed to the callback by the application
(for example a window handle in a GUI application). The callback
-B<must> return the number of characters in the passphrase or -1 if
+I<must> return the number of characters in the passphrase or -1 if
an error occurred.
=head1 NOTES
PEM_read_bio_X509(bp, &x, 0, NULL);
-this is a bug because an attempt will be made to reuse the data at B<x>
+this is a bug because an attempt will be made to reuse the data at I<x>
which is an uninitialised pointer.
These functions make no assumption regarding the pass phrase received from the
the base64-encoded encrypted data.
The encryption key is derived using EVP_BytesToKey(). The cipher's
-initialization vector is passed to EVP_BytesToKey() as the B<salt>
+initialization vector is passed to EVP_BytesToKey() as the I<salt>
parameter. Internally, B<PKCS5_SALT_LEN> bytes of the salt are used
(regardless of the size of the initialization vector). The user's
-password is passed to EVP_BytesToKey() using the B<data> and B<datal>
+password is passed to EVP_BytesToKey() using the I<data> and I<datal>
parameters. Finally, the library uses an iteration count of 1 for
EVP_BytesToKey().
-The B<key> derived by EVP_BytesToKey() along with the original initialization
-vector is then used to decrypt the encrypted data. The B<iv> produced by
+The I<key> derived by EVP_BytesToKey() along with the original initialization
+vector is then used to decrypt the encrypted data. The I<iv> produced by
EVP_BytesToKey() is not utilized or needed, and NULL should be passed to
the function.
PEM_read_bio_X509(bp, &x, 0, NULL);
-where B<x> already contains a valid certificate, may not work, whereas:
+where I<x> already contains a valid certificate, may not work, whereas:
X509_free(x);
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
=head1 DESCRIPTION
-In the description below, I<TYPE> is used
-as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
+In the description below, B<I<TYPE>> is used
+as a placeholder for any of the OpenSSL datatypes, such as B<X509>.
The OpenSSL ASN1 parsing library templates are like a data-driven bytecode
interpreter.
to generate the function bodies.
-TYPE_new() allocates an empty object of the indicated type.
-The object returned must be released by calling TYPE_free().
+B<I<TYPE>_new>() allocates an empty object of the indicated type.
+The object returned must be released by calling B<I<TYPE>_free>().
-TYPE_dup() copies an existing object, leaving it untouched.
+B<I<TYPE>_dup>() copies an existing object, leaving it untouched.
-TYPE_free() releases the object and all pointers and sub-objects
+B<I<TYPE>_free>() releases the object and all pointers and sub-objects
within it.
-TYPE_print_ctx() prints the object B<a> on the specified BIO B<out>.
-Each line will be prefixed with B<indent> spaces.
-The
B<pctx> specifies the printing context and is for internal
+B<I<TYPE>_print_ctx>() prints the object I<a> on the specified BIO I<out>.
+Each line will be prefixed with I<indent> spaces.
+The
I<pctx> specifies the printing context and is for internal
use; use NULL to get the default behavior. If a print function is
-user-defined, then pass in any
B<pctx> down to any nested calls.
+user-defined, then pass in any
I<pctx> down to any nested calls.
=head1 RETURN VALUES
-TYPE_new() and TYPE_dup() return a pointer to the object or NULL on failure.
+B<I<TYPE>_new>() and B<I<TYPE>_dup>() return a pointer to the object or NULL on
+failure.
-TYPE_print_ctx() returns 1 on success or zero on failure.
+B<I<TYPE>_print_ctx>() returns 1 on success or zero on failure.
=head1 COPYRIGHT
=head1 DESCRIPTION
-In the description here, I<TYPE> is used a placeholder
+In the description here, B<I<TYPE>> is used a placeholder
for any of the OpenSSL datatypes, such as I<X509_CRL>.
The function parameters I<ppin> and I<ppout> are generally
either both named I<pp> in the headers, or I<in> and I<out>.
within, the DER is a serialized encoding, suitable for sending over the
network, writing to a file, and so on.
-d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a
-pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to
-the byte following the parsed data. If B<a> is not B<NULL> then a pointer
-to the returned structure is also written to B<*a>. If an error occurred
-then B<NULL> is returned.
+B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
+pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
+the byte following the parsed data. If I<a> is not NULL then a pointer
+to the returned structure is also written to I<*a>. If an error occurred
+then NULL is returned.
-On a successful return, if B<*a> is not B<NULL> then it is assumed that B<*a>
-contains a valid B<TYPE> structure and an attempt is made to reuse it. This
+On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
+contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This
"reuse" capability is present for historical compatibility but its use is
B<strongly discouraged> (see BUGS below, and the discussion in the RETURN
VALUES section).
-d2i_TYPE_bio() is similar to d2i_TYPE() except it attempts
-to parse data from BIO B<bp>.
+B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
+to parse data from BIO I<bp>.
-d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts
-to parse data from FILE pointer B<fp>.
+B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts
+to parse data from FILE pointer I<fp>.
-
i2d_TYPE() encodes the structure pointed to by B<a> into DER format.
-If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer
-at B<*ppout>, and increments it to point after the data just written.
+
B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format.
+If I<ppout> is not NULL, it writes the DER encoded data to the buffer
+at I<*ppout>, and increments it to point after the data just written.
If the return value is negative an error occurred, otherwise it
returns the length of the encoded data.
-If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded
-data written to it. In this case B<*ppout> is not incremented and it points
+If I<*ppout> is NULL memory will be allocated for a buffer and the encoded
+data written to it. In this case I<*ppout> is not incremented and it points
to the start of the data just written.
-i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
-the encoding of the structure B<a> to BIO B<bp> and it
+B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes
+the encoding of the structure I<a> to BIO I<bp> and it
returns 1 for success and 0 for failure.
-i2d_TYPE_fp() is similar to i2d_TYPE() except it writes
-the encoding of the structure B<a> to BIO B<bp> and it
+B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes
+the encoding of the structure I<a> to BIO I<bp> and it
returns 1 for success and 0 for failure.
These routines do not encrypt private keys and therefore offer no
=head1 NOTES
-The letters B<i> and B<d> in B<i2d_TYPE> stand for
+The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for
"internal" (that is, an internal C structure) and "DER" respectively.
-So B<i2d_TYPE> converts from internal to DER.
+So B<i2d_I<TYPE>>() converts from internal to DER.
The functions can also understand B<BER> forms.
-The actual TYPE structure passed to i2d_TYPE() must be a valid
-populated B<TYPE> structure -- it B<cannot> simply be fed with an
+The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid
+populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an
empty structure such as that returned by TYPE_new().
The encoded data is in binary form and may contain embedded zeroes.
Functions such as strlen() will B<not> return the correct length
of the encoded structure.
-The ways that B<*ppin> and B<*ppout> are incremented after the operation
+The ways that I<*ppin> and I<*ppout> are incremented after the operation
can trap the unwary. See the B<WARNINGS> section for some common
errors.
The reason for this-auto increment behaviour is to reflect a typical
Represents a DSA public key using a B<SubjectPublicKeyInfo> structure.
-=item B<DSAPublicKey, DSAPrivateKey>
+=item B<DSAPublicKey>, B<DSAPrivateKey>
Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>,
-
B<PEM_write_PrivateKey(3)>, or similar instead.
+
L<PEM_write_PrivateKey(3)>, or similar instead.
=item B<ECDSA_SIG>
=head1 RETURN VALUES
-d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
-or B<NULL> if an error occurs. If the "reuse" capability has been used with
-a valid structure being passed in via B<a>, then the object is freed in
-the event of error and B<*a> is set to NULL.
+B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid
+B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has
+been used with a valid structure being passed in via I<a>, then the object is
+freed in the event of error and I<*a> is set to NULL.
-i2d_TYPE() returns the number of bytes successfully encoded or a negative
+B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative
value if an error occurs.
-i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
-occurs.
+B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an
+error occurs.
=head1 EXAMPLES
...
OPENSSL_free(buf);
-This code will result in B<buf> apparently containing garbage because
+This code will result in I<buf> apparently containing garbage because
it was incremented after the call to point after the data just written.
-Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
+Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
and the subsequent call to OPENSSL_free() is likely to crash.
-Another trap to avoid is misuse of the B<a> argument to d2i_TYPE():
+Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>():
X509 *x;
/* error */
This will probably crash somewhere in d2i_X509(). The reason for this
-is that the variable B<x> is uninitialized and an attempt will be made to
+is that the variable I<x> is uninitialized and an attempt will be made to
interpret its (invalid) value as an B<X509> structure, typically causing
-a segmentation violation. If B<x> is set to NULL first then this will not
+a segmentation violation. If I<x> is set to NULL first then this will not
happen.
=head1 BUGS
-In some versions of OpenSSL the "reuse" behaviour of d2i_TYPE() when
-B<*a> is valid is broken and some parts of the reused structure may
+In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when
+I<*a> is valid is broken and some parts of the reused structure may
persist if they are not present in the new one. Additionally, in versions of
OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs
the behaviour is inconsistent. Some functions behaved as described here, while
-some did not free B<*a> on error and did not set B<*a> to NULL.
+some did not free I<*a> on error and did not set I<*a> to NULL.
As a result of the above issues the "reuse" behaviour is strongly discouraged.
-i2d_TYPE() will not return an error in many versions of OpenSSL,
+B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL,
if mandatory fields are not initialized due to a programming error
then the encoded structure may contain invalid data or omit the
-fields entirely and will not be parsed by d2i_TYPE(). This may be
-fixed in future so code should not assume that i2d_TYPE() will
+fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be
+fixed in future so code should not assume that B<i2d_I<TYPE>>() will
always succeed.
-Any function which encodes a structure (i2d_TYPE(),
-i2d_TYPE() or i2d_TYPE()) may return a stale encoding if the
+Any function which encodes a structure (B<i2d_I<TYPE>>(),
+B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) may return a stale encoding if the
structure has been modified after deserialization or previous
serialization. This is because some objects cache the encoding for
efficiency reasons.
projects / openssl / commitdiff