From 0778364f8ec1f9702e62e6298aaa212ec40b6111 Mon Sep 17 00:00:00 2001
From: Tomas Mraz <tomas@openssl.org>
Date: Thu, 13 Oct 2022 11:39:35 +0200
Subject: 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)
---
 doc/man3/DEFINE_STACK_OF.pod | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod
index 9cec998924..12f033d977 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(),
-- 
cgit v1.2.3