Debian Codegraph @

upstream/debian-trixie/man3/bsearch.3

raw
1 '\" t
2 .\" Copyright 1993 David Metcalfe ([email protected])
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
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 ([email protected])
12 .TH bsearch 3 2024-06-15 "Linux man-pages 6.9.1"
13 .SH NAME
14 bsearch \- binary search of a sorted array
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <stdlib.h>
21 .P
22 .BI "void *bsearch(const void " key [. size "], \
23 const void " base [. size " * ." nmemb ],
24 .BI " size_t " nmemb ", size_t " size ,
25 .BI " int (*" compar ")(const void [." size "], \
26 const void [." size ]));
27 .fi
28 .SH DESCRIPTION
29 The
30 .BR bsearch ()
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 .
39 The size of each member
40 of the array is specified by
41 .IR size .
42 .P
43 The contents of the array should be in ascending sorted order according
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
50 object and to an array member, in that order, and should return an integer
51 less than, equal to, or greater than zero if the
52 .I key
53 object is found,
54 respectively, to be less than, to match, or be greater than the array
55 member.
56 .SH RETURN VALUE
57 The
58 .BR bsearch ()
59 function returns a pointer to a matching member of the
60 array, or NULL if no match is found.
61 If there are multiple elements that
62 match the key, the element returned is unspecified.
63 .SH ATTRIBUTES
64 For an explanation of the terms used in this section, see
65 .BR attributes (7).
66 .TS
67 allbox;
68 lbx lb lb
69 l l l.
70 Interface Attribute Value
71 T{
72 .na
73 .nh
74 .BR bsearch ()
75 T} Thread safety MT-Safe
76 .TE
77 .SH STANDARDS
78 C11, POSIX.1-2008.
79 .SH HISTORY
80 POSIX.1-2001, C89, C99, SVr4, 4.3BSD.
81 .SH EXAMPLES
82 The example below first sorts an array of structures using
83 .BR qsort (3),
84 then retrieves desired elements using
85 .BR bsearch ().
86 .P
87 .\" SRC BEGIN (bsearch.c)
88 .EX
89 #include <stdio.h>
90 #include <stdlib.h>
91 #include <string.h>
92 \&
93 #define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0]))
94 \&
95 struct mi {
96 int nr;
97 const char *name;
98 };
99 \&
100 static struct mi months[] = {
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" }
104 };
105 \&
106 static int
107 compmi(const void *m1, const void *m2)
108 {
109 const struct mi *mi1 = m1;
110 const struct mi *mi2 = m2;
111 \&
112 return strcmp(mi1\->name, mi2\->name);
113 }
114 \&
115 int
116 main(int argc, char *argv[])
117 {
118 qsort(months, ARRAY_SIZE(months), sizeof(months[0]), compmi);
119 for (size_t i = 1; i < argc; i++) {
120 struct mi key;
121 struct mi *res;
122 \&
123 key.name = argv[i];
124 res = bsearch(&key, months, ARRAY_SIZE(months),
125 sizeof(months[0]), compmi);
126 if (res == NULL)
127 printf("\[aq]%s\[aq]: unknown month\[rs]n", argv[i]);
128 else
129 printf("%s: month #%d\[rs]n", res\->name, res\->nr);
130 }
131 exit(EXIT_SUCCESS);
132 }
133 .EE
134 .\" SRC END
135 .SH SEE ALSO
136 .BR hsearch (3),
137 .BR lsearch (3),
138 .BR qsort (3),
139 .BR tsearch (3)