]>
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). | |
c466875e MK |
66 | .ad l |
67 | .nh | |
b345bfca ZL |
68 | .TS |
69 | allbox; | |
c466875e | 70 | lbx lb lb |
b345bfca ZL |
71 | l l l. |
72 | Interface Attribute Value | |
73 | T{ | |
74 | .BR bsearch () | |
75 | T} Thread safety MT-Safe | |
76 | .TE | |
c466875e MK |
77 | .hy |
78 | .ad | |
847e0d88 | 79 | .sp 1 |
3113c7f3 | 80 | .SH STANDARDS |
4131356c AC |
81 | C11, POSIX.1-2008. |
82 | .SH HISTORY | |
83 | POSIX.1-2001, C89, C99, SVr4, 4.3BSD. | |
a14af333 | 84 | .SH EXAMPLES |
fea681da MK |
85 | The example below first sorts an array of structures using |
86 | .BR qsort (3), | |
87 | then retrieves desired elements using | |
63aa9df0 | 88 | .BR bsearch (). |
ba39b288 | 89 | .PP |
b0b6ab4e | 90 | .\" SRC BEGIN (bsearch.c) |
ba39b288 | 91 | .EX |
fea681da MK |
92 | #include <stdio.h> |
93 | #include <stdlib.h> | |
94 | #include <string.h> | |
fe5dba13 | 95 | \& |
6a8012f1 | 96 | #define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0])) |
fe5dba13 | 97 | \& |
fea681da | 98 | struct mi { |
8e6b55a7 AC |
99 | int nr; |
100 | const char *name; | |
101 | }; | |
fe5dba13 | 102 | \& |
8e6b55a7 | 103 | static struct mi months[] = { |
b9f02710 MK |
104 | { 1, "jan" }, { 2, "feb" }, { 3, "mar" }, { 4, "apr" }, |
105 | { 5, "may" }, { 6, "jun" }, { 7, "jul" }, { 8, "aug" }, | |
106 | { 9, "sep" }, {10, "oct" }, {11, "nov" }, {12, "dec" } | |
fea681da | 107 | }; |
fe5dba13 | 108 | \& |
c13182ef MK |
109 | static int |
110 | compmi(const void *m1, const void *m2) | |
b9f02710 | 111 | { |
684130db AC |
112 | const struct mi *mi1 = m1; |
113 | const struct mi *mi2 = m2; | |
fe5dba13 | 114 | \& |
b9f02710 | 115 | return strcmp(mi1\->name, mi2\->name); |
fea681da | 116 | } |
fe5dba13 | 117 | \& |
c13182ef | 118 | int |
aa1f53cc | 119 | main(int argc, char *argv[]) |
b9f02710 | 120 | { |
6a8012f1 | 121 | qsort(months, ARRAY_SIZE(months), sizeof(months[0]), compmi); |
b42296e4 | 122 | for (size_t i = 1; i < argc; i++) { |
b33535f5 AC |
123 | struct mi key; |
124 | struct mi *res; | |
fe5dba13 | 125 | \& |
b9f02710 | 126 | key.name = argv[i]; |
6a8012f1 | 127 | res = bsearch(&key, months, ARRAY_SIZE(months), |
8ec19d12 | 128 | sizeof(months[0]), compmi); |
b9f02710 | 129 | if (res == NULL) |
b957f81f | 130 | printf("\[aq]%s\[aq]: unknown month\en", argv[i]); |
b9f02710 | 131 | else |
31a6818e | 132 | printf("%s: month #%d\en", res\->name, res\->nr); |
b9f02710 | 133 | } |
5bc8c34c | 134 | exit(EXIT_SUCCESS); |
fea681da | 135 | } |
ba39b288 | 136 | .EE |
b0b6ab4e | 137 | .\" SRC END |
47297adb | 138 | .SH SEE ALSO |
fea681da MK |
139 | .BR hsearch (3), |
140 | .BR lsearch (3), | |
141 | .BR qsort (3), | |
142 | .BR tsearch (3) |