'\" te
.\" Copyright 1989 AT&T.  Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
.TH bsearch 3C "6 Dec 2004" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
bsearch \- binary search a sorted table
.SH SYNOPSIS
.LP
.nf
#include <stdlib.h>

\fBvoid *\fR\fBbsearch\fR(\fBconst void *\fR\fIkey\fR, \fBconst void *\fR\fIbase\fR, \fBsize_t\fR \fInel\fR, \fBsize_t\fR \fIsize\fR,
     \fBint (*\fR\fIcompar\fR)(const void *,const void *));
.fi

.SH DESCRIPTION
.sp
.LP
The \fBbsearch()\fR function is a binary search routine generalized 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 according to a comparison function pointed to by \fIcompar\fR.
.sp
.LP
The \fIkey\fR argument points to a datum instance to be sought in the table.  The \fIbase\fR argument points to the element at the base of the table.  The \fInel\fR argument is the number of elements in the table.  The \fBsize\fR argument is the number of bytes in each element.
.sp
.LP
The comparison function pointed to by \fIcompar\fR is called with two arguments that point to the \fIkey\fR 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 \fIkey\fR object is considered, respectively, to be less than, equal to, or greater than the array element.
.SH RETURN VALUES
.sp
.LP
The \fBbsearch()\fR 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.
.SH USAGE
.sp
.LP
The pointers to the key and the element at the base of the table should be of type pointer-to-element.
.sp
.LP
The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared.
.sp
.LP
If the number of elements in the table is less than the size reserved for the table, \fInel\fR should be the lower number.
.sp
.LP
The \fBbsearch()\fR function safely allows concurrent access by multiple threads to disjoint data, such as overlapping subtrees or tables.
.SH EXAMPLES
.LP
\fBExample 1 \fRExamples for searching a table containing pointers to nodes.
.sp
.LP
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.

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

.sp
.in +2
.nf
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
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 *node_ptr, node;
    /* routine to compare 2 nodes */
    static int node_compare(const void *, const void *);
    char str_space[20];   /* space to read string into */

    node.string = str_space;
    while (scanf("%20s", node.string) != EOF) {
        node_ptr = bsearch( &node,
            table, sizeof(table)/sizeof(struct node),
            sizeof(struct node), node_compare);
        if (node_ptr != NULL) {
            (void) printf("string = %20s, length = %d\en",
                node_ptr\(mi>string, node_ptr\(mi>length);
        } else {
            (void)printf("not found: %20s\en", node.string);
        }
    }
    return(0);
}

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

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe
_
StandardSee \fBstandards\fR(5).
.TE

.SH SEE ALSO
.sp
.LP
\fBhsearch\fR(3C), \fBlsearch\fR(3C), \fBqsort\fR(3C), \fBtsearch\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)