BSEARCH(3,L)                AIX Technical Reference                BSEARCH(3,L)



-------------------------------------------------------------------------------
bsearch



PURPOSE

Performs a binary search.

LIBRARY

Standard C Library (libc.a)

SYNTAX

#include <stdlib.h>

void *bsearch(key, base, nmemb, size, compar)
void *key, *base;
int nmemb;
size_t size;
int (*compar) (void*, void*);

DESCRIPTION

The bsearch subroutine is a binary search routine generalized from Donald E.
Knuth's The Art of Computer Programming, Volume 3, 6.2.1, Algorithm B.(*) It
returns a pointer into a table indicating where a datum is found.

The table must already be sorted in increasing order according to the provided
comparison function compar.  The key parameter points to the datum to be sought
in the table.  The base parameter points to the element at the base of the
table.  The nmemb parameter is the number of elements in the table.  The compar
parameter is a pointer to the comparison function, which is called with two
parameters that point to the elements being compared.

The comparison function must compare its parameters and return a value as
follows:

  o If the first parameter is less than the second parameter, compar must
    return a value less than 0.
  o If the first parameter is equal to the second parameter, compar must return
    0.
  o If the first parameter is greater than the second parameter, compar must
    return a value greater than 0.

The comparison function need not compare every byte, so arbitrary data can be
contained in the elements in addition to the values being compared.

---------------

(*) Reading, Massachusetts:  Addison-Wesley, 1981.



Processed November 7, 1990       BSEARCH(3,L)                                 1

BSEARCH(3,L)                AIX Technical Reference                BSEARCH(3,L)




The pointers key and base should be of type pointer-to-element, and cast to
type pointer-to-character.  Although declared as type pointer-to-character, the
value returned should be cast into type pointer-to-element.

RETURN VALUE

If the key is found in the table, the bsearch returns a pointer to the element
found.  If the key cannot be found in the table, then bsearch returns the value
NULL.

RELATED INFORMATION

In this book:  "hsearch, hcreate, hdestroy,"  "lsearch, lfind," "qsort," and
"tsearch, tdelete, twalk."








































Processed November 7, 1990       BSEARCH(3,L)                                 2