From: Richard Levitte Date: Mon, 6 Apr 2020 12:00:55 +0000 (+0200) Subject: Fix some errors in documentation X-Git-Tag: openssl-3.0.0-alpha1~113 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=b93e2ec273f8a6e7165fddaae1fe75615c0edf5a;p=oweals%2Fopenssl.git Fix some errors in documentation Reviewed-by: Matt Caswell (Merged from https://github.com/openssl/openssl/pull/11476) --- diff --git a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod b/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod deleted file mode 100644 index a78193c2e2..0000000000 --- a/doc/internal/man3/DEFINE_SPARSE_ARRAY_OF.pod +++ /dev/null @@ -1,133 +0,0 @@ -=pod - -=head1 NAME - -DEFINE_SPARSE_ARRAY_OF, ossl_sa_TYPE_new, ossl_sa_TYPE_free, -ossl_sa_TYPE_free_leaves, ossl_sa_TYPE_num, ossl_sa_TYPE_doall, -ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set -- sparse array container - -=head1 SYNOPSIS - -=for openssl generic - - #include "crypto/sparse_array.h" - - typedef struct sparse_array_st OPENSSL_SA; - - SPARSE_ARRAY_OF(TYPE) - DEFINE_SPARSE_ARRAY_OF(TYPE) - - SPARSE_ARRAY_OF(TYPE) *ossl_sa_TYPE_new(void); - void ossl_sa_TYPE_free(const SPARSE_ARRAY_OF(TYPE) *sa); - void ossl_sa_TYPE_free_leaves(const SPARSE_ARRAY_OF(TYPE) *sa); - size_t ossl_sa_TYPE_num(const SPARSE_ARRAY_OF(TYPE) *sa); - void ossl_sa_TYPE_doall(const OPENSSL_SA *sa, void (*leaf)(ossl_uintmax_t, - void *)); - void ossl_sa_TYPE_doall_arg(const OPENSSL_SA *sa, - void (*leaf)(ossl_uintmax_t, void *, void *), - void *arg); - TYPE *ossl_sa_TYPE_get(const SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx); - int ossl_sa_TYPE_set(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx, - TYPE *value); - -=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>. DEFINE_STACK_OF() creates set of functions for a sparse -array of B>. This will mean that a pointer to type B> -is stored in each element of a sparse array, the type is referenced by -B(B>) and each function name begins with -B_>. For example: - - TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx); - -B_num>() returns the number of elements in I or 0 if I -is NULL. - -B_get>() returns element I in I, where I starts -at zero. If I refers to a value that has not been set then NULL is -returned. - -B_set>() sets element I in I to I, where I -starts at zero. The sparse array will be resized as required. - -B_new>() allocates a new empty sparse array. - -B_free>() frees up the I structure. It does I free up any -elements of I. After this call I is no longer valid. - -B_free_leaves>() frees up the I structure and all of its -elements. After this call I is no longer valid. - -B_doall>() calls the function I for each element in I -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. - -B_doall_arg>() calls the function I for each element in -I 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 -the third argument is the user supplied I. - - -=head1 NOTES - -Sparse arrays are an internal data structure and should B be used by user -applications. - -Care should be taken when accessing sparse arrays in multi-threaded -environments. The B_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. - -The underlying utility B API should not be used directly. It -defines these functions: OPENSSL_SA_doall, OPENSSL_SA_doall_arg, -OPENSSL_SA_free, OPENSSL_SA_free_leaves, OPENSSL_SA_get, OPENSSL_SA_new, -OPENSSL_SA_num and OPENSSL_SA_set. - -=head1 RETURN VALUES - -B_num>() returns the number of elements in the sparse array or -B<0> if the passed sparse array is NULL. - -B_get>() returns a pointer to a sparse array element or NULL if -the element has not be set. - -B_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. - -B_new>() returns an empty sparse array or NULL if an error -occurs. - -B_doall>(), B_doall_arg>(), -B_free>() and B_free_leaves>() -do not return values. - -=head1 HISTORY - -This functionality was added to OpenSSL 3.0. - -=head1 COPYRIGHT - -Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright -(c) 2019, Oracle and/or its affiliates. All rights reserved. - -Licensed under the Apache License 2.0 (the "License"). You may not use this -file except in compliance with the License. You can obtain a copy in the file -LICENSE in the source distribution or at -L. - -=cut diff --git a/doc/internal/man3/OPENSSL_SA.pod b/doc/internal/man3/OPENSSL_SA.pod new file mode 100644 index 0000000000..77f1a7b1c2 --- /dev/null +++ b/doc/internal/man3/OPENSSL_SA.pod @@ -0,0 +1,131 @@ +=pod + +=head1 NAME + +OPENSSL_SA, ossl_sa_TYPE_new, ossl_sa_TYPE_free, +ossl_sa_TYPE_free_leaves, ossl_sa_TYPE_num, ossl_sa_TYPE_doall, +ossl_sa_TYPE_doall_arg, ossl_sa_TYPE_get, ossl_sa_TYPE_set +- sparse array container + +=head1 SYNOPSIS + + #include "crypto/sparse_array.h" + + typedef struct sparse_array_st OPENSSL_SA; + + SPARSE_ARRAY_OF(TYPE) + DEFINE_SPARSE_ARRAY_OF(TYPE) + + SPARSE_ARRAY_OF(TYPE) *ossl_sa_TYPE_new(void); + void ossl_sa_TYPE_free(const SPARSE_ARRAY_OF(TYPE) *sa); + void ossl_sa_TYPE_free_leaves(const SPARSE_ARRAY_OF(TYPE) *sa); + size_t ossl_sa_TYPE_num(const SPARSE_ARRAY_OF(TYPE) *sa); + void ossl_sa_TYPE_doall(const OPENSSL_SA *sa, void (*leaf)(ossl_uintmax_t, + void *)); + void ossl_sa_TYPE_doall_arg(const OPENSSL_SA *sa, + void (*leaf)(ossl_uintmax_t, void *, void *), + void *arg); + TYPE *ossl_sa_TYPE_get(const SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx); + int ossl_sa_TYPE_set(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx, + TYPE *value); + +=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>. DEFINE_STACK_OF() creates set of functions for a sparse +array of B>. This will mean that a pointer to type B> +is stored in each element of a sparse array, the type is referenced by +B(B>) and each function name begins with +B_>. For example: + + TYPE *ossl_sa_TYPE_get(SPARSE_ARRAY_OF(TYPE) *sa, ossl_uintmax_t idx); + +B_num>() returns the number of elements in I or 0 if I +is NULL. + +B_get>() returns element I in I, where I starts +at zero. If I refers to a value that has not been set then NULL is +returned. + +B_set>() sets element I in I to I, where I +starts at zero. The sparse array will be resized as required. + +B_new>() allocates a new empty sparse array. + +B_free>() frees up the I structure. It does I free up any +elements of I. After this call I is no longer valid. + +B_free_leaves>() frees up the I structure and all of its +elements. After this call I is no longer valid. + +B_doall>() calls the function I for each element in I +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. + +B_doall_arg>() calls the function I for each element in +I 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 +the third argument is the user supplied I. + + +=head1 NOTES + +Sparse arrays are an internal data structure and should B be used by user +applications. + +Care should be taken when accessing sparse arrays in multi-threaded +environments. The B_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. + +The underlying utility B API should not be used directly. It +defines these functions: OPENSSL_SA_doall, OPENSSL_SA_doall_arg, +OPENSSL_SA_free, OPENSSL_SA_free_leaves, OPENSSL_SA_get, OPENSSL_SA_new, +OPENSSL_SA_num and OPENSSL_SA_set. + +=head1 RETURN VALUES + +B_num>() returns the number of elements in the sparse array or +B<0> if the passed sparse array is NULL. + +B_get>() returns a pointer to a sparse array element or NULL if +the element has not be set. + +B_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. + +B_new>() returns an empty sparse array or NULL if an error +occurs. + +B_doall>(), B_doall_arg>(), +B_free>() and B_free_leaves>() +do not return values. + +=head1 HISTORY + +This functionality was added to OpenSSL 3.0. + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright +(c) 2019, Oracle and/or its affiliates. All rights reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use this +file except in compliance with the License. You can obtain a copy in the file +LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/internal/man3/s2i_ASN1_UTF8STRING.pod b/doc/internal/man3/s2i_ASN1_UTF8STRING.pod index c5b434a5b5..9b806eb80b 100644 --- a/doc/internal/man3/s2i_ASN1_UTF8STRING.pod +++ b/doc/internal/man3/s2i_ASN1_UTF8STRING.pod @@ -3,12 +3,12 @@ =head1 NAME i2s_ASN1_UTF8STRING, -s2i_ASN1_UTF8STRING, +s2i_ASN1_UTF8STRING - convert objects from/to ASN.1/string representation =head1 SYNOPSIS -=for openssl generic + #include "crypto/x509v3.h" char *i2s_ASN1_UTF8STRING(X509V3_EXT_METHOD *method, ASN1_UTF8STRING *utf8); @@ -22,7 +22,7 @@ representation. This function is used for B extentions. =head1 NOTES -The letters B and B in B() stand for +The letters B and B in i2s_ASN1_UTF8STRING() stand for "internal" (that is, an internal C structure) and string respectively. So B() converts from internal to string.