From: Bob Beck <beck@openssl.org>
Date: Tue, 16 Sep 2025 21:30:31 +0000 (-0600)
Subject: Correct the documentation for OPENSSL_sk_find
X-Git-Tag: openssl-3.3.5~23
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=c4bbbc1badbbde3c25e579f2da2bf29e8843787b;p=thirdparty%2Fopenssl.git

Correct the documentation for OPENSSL_sk_find

Since April of 2023 with commit eb0935f, these functions have not
sorted the stack if it was not sorted. The documentation was noti
changed at the time to reflect this changed behaviour.

This corrects the documentation to reflect the current behaviour
of these functions

Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/28578)

(cherry picked from commit 07e70f951e7c4618b4a275d60f7410f77999f92a)
---

diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod
index ff2074820f6..7ab3a108b1d 100644
--- a/doc/man3/DEFINE_STACK_OF.pod
+++ b/doc/man3/DEFINE_STACK_OF.pod
@@ -170,15 +170,14 @@ B<sk_I<TYPE>_set>() sets element I<idx> of I<sk> to I<ptr> replacing the current
 element. The new element value is returned or NULL if an error occurred:
 this will only happen if I<sk> is NULL or I<idx> is out of range.
 
-B<sk_I<TYPE>_find>() searches I<sk> for the element I<ptr>.  In the case
-where no comparison function has been specified, the function performs
-a linear search for a pointer equal to I<ptr>. The index of the first
-matching element is returned or B<-1> if there is no match. In the case
-where a comparison function has been specified, I<sk> is sorted and
-B<sk_I<TYPE>_find>() returns the index of a matching element or B<-1> if there
-is no match. Note that, in this case the comparison function will usually
-compare the values pointed to rather than the pointers themselves and
-the order of elements in I<sk> can change.
+B<sk_I<TYPE>_find>() searches I<sk> for the element I<ptr>. In the
+case where no comparison function has been specified, the function
+performs a linear search for a pointer equal to I<ptr>. In the case
+where a comparison function has been specified, the function performs
+a search for a element that the comparison function indicates is a
+match. If the stack is sorted, a binary search is used, otherwise, a
+linear search is used. B<sk_I<TYPE>_find>() returns the index of a
+matching element or B<-1> if there is no match.
 
 B<sk_I<TYPE>_find_ex>() operates like B<sk_I<TYPE>_find>() except when a
 comparison function has been specified and no matching element is found.