From: Tomas Mraz <tomas@openssl.org>
Date: Thu, 13 Oct 2022 09:39:35 +0000 (+0200)
Subject: Document the stack functions that are forgiving
X-Git-Tag: openssl-3.2.0-alpha1~1851
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0778364f8ec1f9702e62e6298aaa212ec40b6111;p=thirdparty%2Fopenssl.git

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 9cec9989249..12f033d977e 100644
--- 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(),