]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" References consulted: | |
7 | .\" Linux libc source code | |
8 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
9 | .\" 386BSD man pages | |
10 | .\" Modified Mon Mar 29 22:41:16 1993, David Metcalfe | |
11 | .\" Modified Sat Jul 24 21:35:16 1993, Rik Faith (faith@cs.unc.edu) | |
4c1c5274 | 12 | .TH bsearch 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
13 | .SH NAME |
14 | bsearch \- binary search of a sorted array | |
b813014f AC |
15 | .SH LIBRARY |
16 | Standard C library | |
17 | .RI ( libc ", " \-lc ) | |
fea681da MK |
18 | .SH SYNOPSIS |
19 | .nf | |
20 | .B #include <stdlib.h> | |
68e4db0a | 21 | .PP |
c64cd13e AC |
22 | .BI "void *bsearch(const void " key [. size "], \ |
23 | const void " base [. size " * ." nmemb ], | |
a6e2f128 | 24 | .BI " size_t " nmemb ", size_t " size , |
c64cd13e AC |
25 | .BI " int (*" compar ")(const void [." size "], \ |
26 | const void [." size ])); | |
fea681da MK |
27 | .fi |
28 | .SH DESCRIPTION | |
60a90ecd MK |
29 | The |
30 | .BR bsearch () | |
c6fa0841 MK |
31 | function searches an array of |
32 | .I nmemb | |
33 | objects, | |
34 | the initial member of which is pointed to by | |
35 | .IR base , | |
36 | for a member | |
37 | that matches the object pointed to by | |
38 | .IR key . | |
c13182ef | 39 | The size of each member |
c6fa0841 MK |
40 | of the array is specified by |
41 | .IR size . | |
fea681da MK |
42 | .PP |
43 | The contents of the array should be in ascending sorted order according | |
c6fa0841 MK |
44 | to the comparison function referenced by |
45 | .IR compar . | |
46 | The | |
47 | .I compar | |
48 | routine is expected to have two arguments which point to the | |
49 | .I key | |
fea681da | 50 | object and to an array member, in that order, and should return an integer |
c6fa0841 MK |
51 | less than, equal to, or greater than zero if the |
52 | .I key | |
53 | object is found, | |
fea681da MK |
54 | respectively, to be less than, to match, or be greater than the array |
55 | member. | |
47297adb | 56 | .SH RETURN VALUE |
60a90ecd MK |
57 | The |
58 | .BR bsearch () | |
59 | function returns a pointer to a matching member of the | |
c13182ef MK |
60 | array, or NULL if no match is found. |
61 | If there are multiple elements that | |
fea681da | 62 | match the key, the element returned is unspecified. |
b345bfca ZL |
63 | .SH ATTRIBUTES |
64 | For an explanation of the terms used in this section, see | |
65 | .BR attributes (7). | |
66 | .TS | |
67 | allbox; | |
c466875e | 68 | lbx lb lb |
b345bfca ZL |
69 | l l l. |
70 | Interface Attribute Value | |
71 | T{ | |
9e54434e BR |
72 | .na |
73 | .nh | |
b345bfca ZL |
74 | .BR bsearch () |
75 | T} Thread safety MT-Safe | |
76 | .TE | |
3113c7f3 | 77 | .SH STANDARDS |
4131356c AC |
78 | C11, POSIX.1-2008. |
79 | .SH HISTORY | |
80 | POSIX.1-2001, C89, C99, SVr4, 4.3BSD. | |
a14af333 | 81 | .SH EXAMPLES |
fea681da MK |
82 | The example below first sorts an array of structures using |
83 | .BR qsort (3), | |
84 | then retrieves desired elements using | |
63aa9df0 | 85 | .BR bsearch (). |
ba39b288 | 86 | .PP |
b0b6ab4e | 87 | .\" SRC BEGIN (bsearch.c) |
ba39b288 | 88 | .EX |
fea681da MK |
89 | #include <stdio.h> |
90 | #include <stdlib.h> | |
91 | #include <string.h> | |
fe5dba13 | 92 | \& |
6a8012f1 | 93 | #define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0])) |
fe5dba13 | 94 | \& |
fea681da | 95 | struct mi { |
8e6b55a7 AC |
96 | int nr; |
97 | const char *name; | |
98 | }; | |
fe5dba13 | 99 | \& |
8e6b55a7 | 100 | static struct mi months[] = { |
b9f02710 MK |
101 | { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" }, |
102 | { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" }, | |
103 | { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" } | |
fea681da | 104 | }; |
fe5dba13 | 105 | \& |
c13182ef MK |
106 | static int |
107 | compmi(const void *m1, const void *m2) | |
b9f02710 | 108 | { |
684130db AC |
109 | const struct mi *mi1 = m1; |
110 | const struct mi *mi2 = m2; | |
fe5dba13 | 111 | \& |
b9f02710 | 112 | return strcmp(mi1\->name, mi2\->name); |
fea681da | 113 | } |
fe5dba13 | 114 | \& |
c13182ef | 115 | int |
aa1f53cc | 116 | main(int argc, char *argv[]) |
b9f02710 | 117 | { |
6a8012f1 | 118 | qsort(months, ARRAY_SIZE(months), sizeof(months[0]), compmi); |
b42296e4 | 119 | for (size_t i = 1; i < argc; i++) { |
b33535f5 AC |
120 | struct mi key; |
121 | struct mi *res; | |
fe5dba13 | 122 | \& |
b9f02710 | 123 | key.name = argv[i]; |
6a8012f1 | 124 | res = bsearch(&key, months, ARRAY_SIZE(months), |
8ec19d12 | 125 | sizeof(months[0]), compmi); |
b9f02710 | 126 | if (res == NULL) |
b957f81f | 127 | printf("\[aq]%s\[aq]: unknown month\en", argv[i]); |
b9f02710 | 128 | else |
31a6818e | 129 | printf("%s: month #%d\en", res\->name, res\->nr); |
b9f02710 | 130 | } |
5bc8c34c | 131 | exit(EXIT_SUCCESS); |
fea681da | 132 | } |
ba39b288 | 133 | .EE |
b0b6ab4e | 134 | .\" SRC END |
47297adb | 135 | .SH SEE ALSO |
fea681da MK |
136 | .BR hsearch (3), |
137 | .BR lsearch (3), | |
138 | .BR qsort (3), | |
139 | .BR tsearch (3) |