Standard C Library Functions                          bsearch(3C)



NAME
     bsearch - binary search a sorted table

SYNOPSIS
     #include 

     void *bsearch(const void *key, const void *base, sizet nel, sizet size,
          int (*compar)(const void *,const void *));


DESCRIPTION
     The bsearch() function is a binary search  routine  general-
     ized  from  Knuth  (6.2.1) Algorithm B. It returns a pointer
     into a table (an array) indicating  where  a  datum  may  be
     found  or  a  null pointer if the datum cannot be found. The
     table must be previously sorted in increasing order  accord-
     ing to a comparison function pointed to by compar.


     The key argument points to a datum instance to be sought  in
     the  table.   The base argument points to the element at the
     base of the table.  The nel argument is the number  of  ele-
     ments  in  the  table.   The  size argument is the number of
     bytes in each element.


     The comparison function pointed to by compar is called  with
     two  arguments  that point to the key object and to an array
     element, in that order. The function must return an  integer
     less  than, equal to, or greater than 0 if the key object is
     considered, respectively, to be  less  than,  equal  to,  or
     greater than the array element.

RETURN VALUES
     The bsearch() function  returns  a  pointer  to  a  matching
     member of the array, or a null pointer if no match is found.
     If two or  more  members  compare  equal,  which  member  is
     returned is unspecified.

USAGE
     The pointers to the key and the element at the base  of  the
     table should be of type pointer-to-element.


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


     If the number of elements in the table is less than the size
     reserved for the table, nel should be the lower number.




SunOS 5.11           Last change: 6 Dec 2004                    1






Standard C Library Functions                          bsearch(3C)



     The bsearch() function safely allows  concurrent  access  by
     multiple  threads to disjoint data, such as overlapping sub-
     trees or tables.

EXAMPLES
     Example 1 Examples for searching a table containing pointers
     to nodes.


     The example below searches a table  containing  pointers  to
     nodes  consisting  of  a string and its length. The table is
     ordered alphabetically on the string in the node pointed  to
     by each entry.



     This  program  reads  in  strings  and  either   finds   the
     corresponding node and prints out the string and its length,
     or prints an error message.


       #include 
       #include 
       #include 
       struct node {  /* these are stored in the table */
           char *string;
           int length;
       };
       static struct node table[] = {    /* table to be searched */
           { "asparagus", 10 },
           { "beans", 6 },
           { "tomato", 7 },
           { "watermelon", 11 },
       };

       main()
       {
           struct node *nodeptr, node;
           /* routine to compare 2 nodes */
           static int nodecompare(const void *, const void *);
           char strspace[20];   /* space to read string into */

           node.string = strspace;
           while (scanf("%20s", node.string) != EOF) {
               nodeptr = bsearch( &node,
                   table, sizeof(table)/sizeof(struct node),
                   sizeof(struct node), nodecompare);
               if (nodeptr != NUL) {
                   (void) printf("string = %20s, length = %d\n",
                       nodeptr->string, nodeptr->length);
               } else {
                   (void)printf("not found: %20s\n", node.string);



SunOS 5.11           Last change: 6 Dec 2004                    2






Standard C Library Functions                          bsearch(3C)



               }
           }
           return(0);
       }

       /* routine to compare two nodes based on an  */
       /* alphabetical ordering of the string field */
       static int
       nodecompare(const void *node1, const void *node2) {
           return (strcmp(
                   ((const struct node *)node1)->string,
                   ((const struct node *)node2)->string));
       }


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     hsearch(3C),  lsearch(3C),  qsort(3C),  tsearch(3C),  attri-
     butes(5), standards(5)






















SunOS 5.11           Last change: 6 Dec 2004                    3