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