diff options
Diffstat (limited to 'man/man3/bsearch.3')
| -rw-r--r-- | man/man3/bsearch.3 | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/man/man3/bsearch.3 b/man/man3/bsearch.3 new file mode 100644 index 000000000..56ba64486 --- /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 (date) "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) |