diff options
| -rw-r--r-- | doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod | 57 | ||||
| -rw-r--r-- | doc/internal/man3/ossl_param_bld_init.pod | 10 | ||||
| -rw-r--r-- | doc/man7/bio.pod | 4 |
3 files changed, 44 insertions, 27 deletions
diff --git a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod index 8afd48ec4d..60695266a7 100644 --- a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod +++ b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod @@ -33,38 +33,46 @@ ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set =head1 DESCRIPTION +=begin comment + +POD is pretty good at recognising function names and making them appropriately +bold... however, when part of the function name is variable, we have to help +the processor along + +=end comment + SPARSE_ARRAY_OF() returns the name for a sparse array of the specified -B<TYPE>. DEFINE_STACK_OF() creates set of functions for a sparse array of -B<TYPE>. This will mean that a pointer to type B<TYPE> is stored in each -element of a sparse array, the type is referenced by SPARSE_ARRAY_OF(TYPE) and -each function name begins with B<ossl_sa_TYPE_>. For example: +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: TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx); -ossl_sa_TYPE_num() returns the number of elements in I<sa> or 0 if I<sa> is -NULL. +B<ossl_sa_I<TYPE>_num>() returns the number of elements in I<sa> or 0 if I<sa> +is NULL. -ossl_sa_TYPE_get() returns element I<idx> in I<sa>, where I<idx> starts at -zero. If I<idx> refers to a value that has not been set then NULL is +B<ossl_sa_I<TYPE>_get>() returns element I<idx> in I<sa>, where I<idx> starts +at zero. If I<idx> refers to a value that has not been set then NULL is returned. -ossl_sa_TYPE_set() sets element I<idx> in I<sa> to I<value>, where I<idx> +B<ossl_sa_I<TYPE>_set>() sets element I<idx> in I<sa> to I<value>, where I<idx> starts at zero. The sparse array will be resized as required. -ossl_sa_TYPE_new() allocates a new empty sparse array. +B<ossl_sa_I<TYPE>_new>() allocates a new empty sparse array. -ossl_sa_TYPE_free() frees up the I<sa> structure. It does I<not> free up any +B<ossl_sa_I<TYPE>_free>() frees up the I<sa> structure. It does I<not> free up any elements of I<sa>. After this call I<sa> is no longer valid. -ossl_sa_TYPE_free_leaves() frees up the I<sa> structure and all of its +B<ossl_sa_I<TYPE>_free_leaves>() frees up the I<sa> structure and all of its elements. After this call I<sa> is no longer valid. -ossl_sa_TYPE_doall() calls the function I<leaf> for each element in I<sa> +B<ossl_sa_I<TYPE>_doall>() calls the function I<leaf> for each element in I<sa> in ascending index order. The index position, within the sparse array, of each item is passed as the first argument to the leaf function and a pointer to the associated value is is passed as the second argument. -ossl_sa_TYPE_doall_arg() calls the function I<leaf> for each element in +B<ossl_sa_I<TYPE>_doall_arg>() calls the function I<leaf> for each element in I<sa> in ascending index order. The index position, within the sparse array, of each item is passed as the first argument to the leaf function, a pointer to the associated value is passed as the second argument and @@ -77,9 +85,9 @@ Sparse arrays are an internal data structure and should B<not> be used by user applications. Care should be taken when accessing sparse arrays in multi-threaded -environments. The ossl_sa_TYPE_set operation can cause the internal structure -of the sparse array to change which causes race conditions if the sparse array -is accessed in a different thread. +environments. The B<ossl_sa_I<TYPE>_set>() operation can cause the internal +structure of the sparse array to change which causes race conditions if the +sparse array is accessed in a different thread. SPARSE_ARRAY_OF() and DEFINE_SPARSE_ARRAY_OF() are implemented as macros. @@ -90,21 +98,22 @@ OPENSSL_SA_num and OPENSSL_SA_set. =head1 RETURN VALUES -ossl_sa_TYPE_num() returns the number of elements in the sparse array or B<0> -if the passed sparse array is NULL. +B<ossl_sa_I<TYPE>_num>() returns the number of elements in the sparse array or +B<0> if the passed sparse array is NULL. -ossl_sa_TYPE_get() returns a pointer to a sparse array element or NULL if +B<ossl_sa_I<TYPE>_get>() returns a pointer to a sparse array element or NULL if the element has not be set. -ossl_sa_TYPE_set() return B<1> on success and B<0> on error. In the latter +B<ossl_sa_I<TYPE>_set>() return B<1> on success and B<0> on error. In the latter case, the elements of the sparse array remain unchanged, although the internal structures might have. -ossl_sa_TYPE_new() returns an empty sparse array or NULL if an error +B<ossl_sa_I<TYPE>_new>() returns an empty sparse array or NULL if an error occurs. -ossl_sa_TYPE_doall, ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_free() and -ossl_sa_TYPE_free_leaves() do not return values. +B<ossl_sa_I<TYPE>_doall>(), B<ossl_sa_I<TYPE>_doall_arg>(), +B<ossl_sa_I<TYPE>_free>() and B<ossl_sa_I<TYPE>_free_leaves>() +do not return values. =head1 HISTORY diff --git a/doc/internal/man3/ossl_param_bld_init.pod b/doc/internal/man3/ossl_param_bld_init.pod index 2eb838d9a9..fb439f24a6 100644 --- a/doc/internal/man3/ossl_param_bld_init.pod +++ b/doc/internal/man3/ossl_param_bld_init.pod @@ -70,7 +70,15 @@ by I<data> of at least I<data_n> bytes in size. If required, secure memory for private BIGNUMs should be pointed to by I<secure> of at least I<secure_n> bytes in size. -ossl_param_bld_push_TYPE() are a series of functions which will create +=begin comment + +POD is pretty good at recognising function names and making them appropriately +bold... however, when part of the function name is variable, we have to help +the processor along + +=end comment + +B<ossl_param_bld_push_I<TYPE>>() are a series of functions which will create OSSL_PARAM objects of the specified size and correct type for the I<val> argument. I<val> is stored by value and an expression or auto variable can be used. diff --git a/doc/man7/bio.pod b/doc/man7/bio.pod index 1d3276b730..84892e71ac 100644 --- a/doc/man7/bio.pod +++ b/doc/man7/bio.pod @@ -49,8 +49,8 @@ BIO_free() on it other than the discarded return value. Normally the I<type> argument is supplied by a function which returns a pointer to a BIO_METHOD. There is a naming convention for such functions: -a source/sink BIO is normally called BIO_s_*() and a filter BIO -BIO_f_*(); +a source/sink BIO is normally called B<BIO_s_I<*>>() and a filter BIO +B<BIO_f_I<*>>(); =head1 EXAMPLES |