Debian Codegraph @

upstream/debian-unstable/man3/bsearch.3

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