Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 139 insertions, 0 deletions

diff --git a/man/man3/bsearch.3 b/man/man3/bsearch.3
new file mode 100644
index 0000000..3e6bff4
--- /dev/null
+++ b/man/man3/bsearch.3
@@ -0,0 +1,139 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\"     Linux libc source code
+.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\"     386BSD man pages
+.\" Modified Mon Mar 29 22:41:16 1993, David Metcalfe
+.\" Modified Sat Jul 24 21:35:16 1993, Rik Faith (faith@cs.unc.edu)
+.TH bsearch 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+bsearch \- binary search of a sorted array
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.P
+.BI "void *bsearch(const void " key [. size "], \
+const void " base [. size " * ." nmemb ],
+.BI "              size_t " nmemb ", size_t " size ,
+.BI "              int (*" compar ")(const void [." size "], \
+const void [." size ]));
+.fi
+.SH DESCRIPTION
+The
+.BR bsearch ()
+function searches an array of
+.I nmemb
+objects,
+the initial member of which is pointed to by
+.IR base ,
+for a member
+that matches the object pointed to by
+.IR key .
+The size of each member
+of the array is specified by
+.IR size .
+.P
+The contents of the array should be in ascending sorted order according
+to the comparison function referenced by
+.IR compar .
+The
+.I compar
+routine is expected to have two arguments which point to the
+.I key
+object and to an array member, in that order, and should return an integer
+less than, equal to, or greater than zero if the
+.I key
+object is found,
+respectively, to be less than, to match, or be greater than the array
+member.
+.SH RETURN VALUE
+The
+.BR bsearch ()
+function returns a pointer to a matching member of the
+array, or NULL if no match is found.
+If there are multiple elements that
+match the key, the element returned is unspecified.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR bsearch ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, C89, C99, SVr4, 4.3BSD.
+.SH EXAMPLES
+The example below first sorts an array of structures using
+.BR qsort (3),
+then retrieves desired elements using
+.BR bsearch ().
+.P
+.\" SRC BEGIN (bsearch.c)
+.EX
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+\&
+#define ARRAY_SIZE(arr)  (sizeof((arr)) / sizeof((arr)[0]))
+\&
+struct mi {
+    int         nr;
+    const char  *name;
+};
+\&
+static struct mi  months[] = {
+    { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" },
+    { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" },
+    { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" }
+};
+\&
+static int
+compmi(const void *m1, const void *m2)
+{
+    const struct mi *mi1 = m1;
+    const struct mi *mi2 = m2;
+\&
+    return strcmp(mi1\->name, mi2\->name);
+}
+\&
+int
+main(int argc, char *argv[])
+{
+    qsort(months, ARRAY_SIZE(months), sizeof(months[0]), compmi);
+    for (size_t i = 1; i < argc; i++) {
+        struct mi key;
+        struct mi *res;
+\&
+        key.name = argv[i];
+        res = bsearch(&key, months, ARRAY_SIZE(months),
+                      sizeof(months[0]), compmi);
+        if (res == NULL)
+            printf("\[aq]%s\[aq]: unknown month\en", argv[i]);
+        else
+            printf("%s: month #%d\en", res\->name, res\->nr);
+    }
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR hsearch (3),
+.BR lsearch (3),
+.BR qsort (3),
+.BR tsearch (3)