Document the stack functions that are forgiving

I.e., those that can be called with NULL stack parameter or invalid index.

Reviewed-by: Todd Short <todd.short@me.com>
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19400)

diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod
index 9cec9989249133c051bfd78aa236ca5095209b40..12f033d977e0464b70673516b9d453ea1fef99fb 100644 (file)
--- a/doc/man3/DEFINE_STACK_OF.pod
+++ b/doc/man3/DEFINE_STACK_OF.pod
@@ -229,6 +229,13 @@ A failed search is indicated by a B<-1> return value.
 STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and
 DEFINE_SPECIAL_STACK_OF() are implemented as macros.
 
+It is not an error to call B<sk_I<TYPE>_num>(), B<sk_I<TYPE>_value>(),
+B<sk_I<TYPE>_free>(), B<sk_I<TYPE>_zero>(), B<sk_I<TYPE>_pop_free>(),
+B<sk_I<TYPE>_delete>(), B<sk_I<TYPE>_delete_ptr>(), B<sk_I<TYPE>_pop>(),
+B<sk_I<TYPE>_shift>(), B<sk_I<TYPE>_find>(), B<sk_I<TYPE>_find_ex>(),
+and B<sk_I<TYPE>_find_all>() on a NULL stack, empty stack, or with
+an invalid index. An error is not raised in these conditions.
+
 The underlying utility B<OPENSSL_sk_> API should not be used directly.
 It defines these functions: OPENSSL_sk_deep_copy(),
 OPENSSL_sk_delete(), OPENSSL_sk_delete_ptr(), OPENSSL_sk_dup(),