| .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
| .\" |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" |
| .\" 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 2003-11-01 "" "Linux Programmer's Manual" |
| .SH NAME |
| bsearch \- binary search of a sorted array |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdlib.h> |
| .sp |
| .BI "void *bsearch(const void *" key ", const void *" base ", size_t " nmemb , |
| .RS |
| .BI "size_t " size ", int (*" compar ")(const void *, const void *));" |
| .RE |
| .fi |
| .SH DESCRIPTION |
| The \fBbsearch\fP() function searches an array of \fInmemb\fP objects, |
| the initial member of which is pointed to by \fIbase\fP, for a member |
| that matches the object pointed to by \fIkey\fP. The size of each member |
| of the array is specified by \fIsize\fP. |
| .PP |
| The contents of the array should be in ascending sorted order according |
| to the comparison function referenced by \fIcompar\fP. The \fIcompar\fP |
| routine is expected to have two arguments which point to the \fIkey\fP |
| object and to an array member, in that order, and should return an integer |
| less than, equal to, or greater than zero if the \fIkey\fP object is found, |
| respectively, to be less than, to match, or be greater than the array |
| member. |
| .SH "RETURN VALUE" |
| The \fBbsearch\fP() 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 EXAMPLE |
| The example below first sorts an array of structures using |
| .BR qsort (3), |
| then retrieves desired elements using |
| .BR bsearch (). |
| .sp |
| .nf |
| #include <stdio.h> |
| #include <stdlib.h> |
| #include <string.h> |
| |
| struct mi { |
| int nr; |
| char *name; |
| } 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" } |
| }; |
| |
| #define nr_of_months (sizeof(months)/sizeof(months[0])) |
| |
| static int compmi(const void *m1, const void *m2) { |
| struct mi *mi1 = (struct mi *) m1; |
| struct mi *mi2 = (struct mi *) m2; |
| return strcmp(mi1\->name, mi2\->name); |
| } |
| |
| int main(int argc, char **argv) { |
| int i; |
| |
| qsort(months, nr_of_months, sizeof(struct mi), compmi); |
| for (i = 1; i < argc; i++) { |
| struct mi key, *res; |
| key.name = argv[i]; |
| res = bsearch(&key, months, nr_of_months, |
| sizeof(struct mi), compmi); |
| if (res == NULL) |
| printf("'%s': unknown month\en", argv[i]); |
| else |
| printf("%s: month #%d\en", res->name, res->nr); |
| } |
| return 0; |
| } |
| .fi |
| .\" this example referred to in qsort.3 |
| .SH "CONFORMING TO" |
| SVID 3, 4.3BSD, ISO 9899 (C99) |
| .SH "SEE ALSO" |
| .BR hsearch (3), |
| .BR lsearch (3), |
| .BR qsort (3), |
| .BR tsearch (3) |