bsearch

Purpose

     Performs a binary search.

Library

     Standard C Library (libc.a)

Syntax

     #include <search.h>

     char *bsearch ((char *)key, (char *)base, nel, sizeof (*key), compar)
     unsigned int nel;
     int (*compar) ( );

Description

     The bsearch subroutine is  a binary search routine gener-
     alized from  Donald E. Knuth's  The Art of  Computer Pro-
     gramming, 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  nel 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 param-
         eter, compar must return a value less than 0.
     o   If the first parameter is  equal to the second param-
         eter, 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 addi-
     tion to the values being compared.

     The pointers key  and base should be  of type pointer-to-
     element, and cast to type pointer-to-character.  Although

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

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

     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."