From 05256f57229c45f01812129a025838641f5ee44b Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Mon, 4 Mar 2024 09:47:34 +0000
Subject: [PATCH] Remove docs for sk_find_ex()

---
 lib/libcrypto/man/OPENSSL_sk_new.3 | 50 ++----------------------------
 1 file changed, 3 insertions(+), 47 deletions(-)

diff --git a/lib/libcrypto/man/OPENSSL_sk_new.3 b/lib/libcrypto/man/OPENSSL_sk_new.3
index 5df45534f77..8f06bb4212b 100644
--- a/lib/libcrypto/man/OPENSSL_sk_new.3
+++ b/lib/libcrypto/man/OPENSSL_sk_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: OPENSSL_sk_new.3,v 1.12 2021/03/12 05:18:00 jsg Exp $
+.\" $OpenBSD: OPENSSL_sk_new.3,v 1.13 2024/03/04 09:47:34 tb Exp $
 .\"
 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: March 12 2021 $
+.Dd $Mdocdate: March 4 2024 $
 .Dt OPENSSL_SK_NEW 3
 .Os
 .Sh NAME
@@ -27,7 +27,6 @@
 .Nm sk_num ,
 .Nm sk_value ,
 .Nm sk_find ,
-.Nm sk_find_ex ,
 .Nm sk_sort ,
 .Nm sk_is_sorted ,
 .Nm sk_push ,
@@ -80,11 +79,6 @@
 .Fa "_STACK *stack"
 .Fa "void *wanted"
 .Fc
-.Ft int
-.Fo sk_find_ex
-.Fa "_STACK *stack"
-.Fa "void *wanted"
-.Fc
 .Ft void
 .Fo sk_sort
 .Fa "_STACK *stack"
@@ -245,16 +239,6 @@ first sorted with
 and instead of comparing pointers, two pointers are considered to match
 if the comparison function returns 0.
 .Pp
-.Fn sk_find_ex
-is identical to
-.Fn sk_find
-except that if the
-.Fa stack
-is not empty but no match is found,
-the index of some pointer considered closest to
-.Fa wanted
-is returned.
-.Pp
 .Fn sk_sort
 sorts the
 .Fa stack
@@ -285,9 +269,8 @@ or
 or changing the comparison function sets the state to unsorted.
 If a comparison function is installed, calling
 .Fn sk_sort ,
-.Fn sk_find ,
 or
-.Fn sk_find_ex
+.Fn sk_find
 sets the state to sorted.
 .Pp
 .Fn sk_push
@@ -456,13 +439,6 @@ is a
 .Dv NULL
 pointer or if no match is found.
 .Pp
-.Fn sk_find_ex
-returns some index or \-1 if
-.Fa stack
-is a
-.Dv NULL
-pointer or empty.
-.Pp
 .Fn sk_is_sorted
 returns 1 if the
 .Fa stack
@@ -562,10 +538,6 @@ Both functions have been available since
 .Fn sk_is_sorted
 first appeared in OpenSSL 0.9.7e and has been available since
 .Ox 3.8 .
-.Pp
-.Fn sk_find_ex
-first appeared in OpenSSL 0.9.8 and has been available since
-.Ox 4.5 .
 .Sh BUGS
 Even if a comparison function is installed, empty stacks and
 stacks containing a single pointer are sometimes considered
@@ -575,23 +547,7 @@ If a comparison function is installed, the concept of
 .Dq first match
 in
 .Fn sk_find
-and
-.Fn sk_find_ex
 is ill-defined because
 .Xr qsort 3
 is not a stable sorting function.
 It is probably best to only assume that they return an arbitrary match.
-.Pp
-The concept of
-.Dq closest
-for
-.Fn sk_find_ex
-is even less clearly defined.
-The match may sometimes be smaller and sometimes larger than
-.Fa wanted ,
-even if both smaller and larger pointers exist in the
-.Fa stack .
-Besides, it is again ill-defined
-which of several pointers that compare equal is selected.
-It is probably best to not assume anything about the selection
-for cases where there is no match.
-- 
2.20.1