git.saurik.com Git - apple/libc.git/blob - stdlib/FreeBSD/bsearch.3

3 .\"

4 .\" This code is derived from software contributed to Berkeley by

5 .\" the American National Standards Committee X3, on Information

6 .\" Processing Systems.

7 .\"

8 .\" Redistribution and use in source and binary forms, with or without

9 .\" modification, are permitted provided that the following conditions

10 .\" are met:

11 .\" 1. Redistributions of source code must retain the above copyright

12 .\" notice, this list of conditions and the following disclaimer.

13 .\" 2. Redistributions in binary form must reproduce the above copyright

14 .\" notice, this list of conditions and the following disclaimer in the

15 .\" documentation and/or other materials provided with the distribution.

16 .\" 4. Neither the name of the University nor the names of its contributors

17 .\" may be used to endorse or promote products derived from this software

18 .\" without specific prior written permission.

19 .\"

20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

30 .\" SUCH DAMAGE.

31 .\"

32 .\" @(#)bsearch.3 8.3 (Berkeley) 4/19/94

33 .\" $FreeBSD: src/lib/libc/stdlib/bsearch.3,v 1.9 2007/01/09 00:28:09 imp Exp $

34 .\"

35 .Dd May 20, 2008

36 .Dt BSEARCH 3

37 .Os

38 .Sh NAME

39 #ifdef UNIFDEF_BLOCKS

40 .Nm bsearch ,

41 .Nm bsearch_b

42 #else

43 .Nm bsearch

44 #endif

45 .Nd binary search of a sorted table

46 .Sh SYNOPSIS

47 .In stdlib.h

48 .Ft void *

49 .Fn bsearch "const void *key" "const void *base" "size_t nel" "size_t width" "int (*compar) (const void *, const void *)"

50 #ifdef UNIFDEF_BLOCKS

51 .Ft void *

52 .Fn bsearch_b "const void *key" "const void *base" "size_t nel" "size_t width" "int (^compar) (const void *, const void *)"

53 #endif

54 .Sh DESCRIPTION

55 The

56 .Fn bsearch

57 function searches an array of

58 .Fa nel

59 objects, the initial member of which is

60 pointed to by

61 .Fa base ,

62 for a member that matches the object pointed to by

63 .Fa key .

64 The size (in bytes) of each member of the array is specified by

65 .Fa width .

66 .Pp

67 The contents of the array should be in ascending sorted order according

68 to the comparison function referenced by

69 .Fa compar .

70 The

71 .Fa compar

72 routine

73 is expected to have

74 two arguments which point to the

75 .Fa key

76 object and to an array member, in that order.

77 It should return an integer which is

78 less than, equal to, or greater than zero if the

79 .Fa key

80 object is found, respectively, to be less than, to match, or be

81 greater than the array member.

82 #ifdef UNIFDEF_BLOCKS

83 .Pp

84 The

85 .Fn bsearch_b

86 function is like

87 .Fn bsearch

88 except the callback

89 .Fa compar

90 is a block pointer instead of a function pointer.

91 #endif

92 .Sh RETURN VALUES

93 The

94 .Fn bsearch

95 #ifdef UNIFDEF_BLOCKS

96 and

97 .Fn bsearch_b

98 functions

99 #else

100 function

101 #endif

102 returns a pointer to a matching member of the array, or a null

103 pointer if no match is found.

104 If two members compare as equal, which member is matched is unspecified.

105 .Sh SEE ALSO

106 .Xr db 3 ,

107 .Xr lsearch 3 ,

108 .Xr qsort 3

109 .\" .Xr tsearch 3

110 .Sh STANDARDS

111 The

112 .Fn bsearch

113 function conforms to

114 .St -isoC .