share/man/man3c/bsearch.3c

   1 '\" te
   2 .\" Copyright 1989 AT&T.  Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH BSEARCH 3C "Dec 6, 2004"
   7 .SH NAME
   8 bsearch \- binary search a sorted table
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <stdlib.h>
  13
  14 \fBvoid *\fR\fBbsearch\fR(\fBconst void *\fR\fIkey\fR, \fBconst void *\fR\fIbase\fR, \fBsize_t\fR \fInel\fR, \fBsize_t\fR \fIsize\fR,
  15      \fBint (*\fR\fIcompar\fR)(const void *,const void *));
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBbsearch()\fR function is a binary search routine generalized from Knuth
  22 (6.2.1) Algorithm B. It returns a pointer into a table (an array) indicating
  23 where a datum may be found or a null pointer if the datum cannot be found. The
  24 table must be previously sorted in increasing order according to a comparison
  25 function pointed to by \fIcompar\fR.
  26 .sp
  27 .LP
  28 The \fIkey\fR argument points to a datum instance to be sought in the table.
  29 The \fIbase\fR argument points to the element at the base of the table.  The
  30 \fInel\fR argument is the number of elements in the table.  The \fBsize\fR
  31 argument is the number of bytes in each element.
  32 .sp
  33 .LP
  34 The comparison function pointed to by \fIcompar\fR is called with two arguments
  35 that point to the \fIkey\fR object and to an array element, in that order. The
  36 function must return an integer less than, equal to, or greater than 0 if the
  37 \fIkey\fR object is considered, respectively, to be less than, equal to, or
  38 greater than the array element.
  39 .SH RETURN VALUES
  40 .sp
  41 .LP
  42 The \fBbsearch()\fR function returns a pointer to a matching member of the
  43 array, or a null pointer if no match is found.  If two or more members compare
  44 equal, which member is returned is unspecified.
  45 .SH USAGE
  46 .sp
  47 .LP
  48 The pointers to the key and the element at the base of the table should be of
  49 type pointer-to-element.
  50 .sp
  51 .LP
  52 The comparison function need not compare every byte, so arbitrary data may be
  53 contained in the elements in addition to the values being compared.
  54 .sp
  55 .LP
  56 If the number of elements in the table is less than the size reserved for the
  57 table, \fInel\fR should be the lower number.
  58 .sp
  59 .LP
  60 The \fBbsearch()\fR function safely allows concurrent access by multiple
  61 threads to disjoint data, such as overlapping subtrees or tables.
  62 .SH EXAMPLES
  63 .LP
  64 \fBExample 1 \fRExamples for searching a table containing pointers to nodes.
  65 .sp
  66 .LP
  67 The example below searches a table containing pointers to nodes consisting of a
  68 string and its length. The table is ordered alphabetically on the string in the
  69 node pointed to by each entry.
  70
  71 .sp
  72 .LP
  73 This program reads in strings and either finds the corresponding node and
  74 prints out the string and its length, or prints an error message.
  75
  76 .sp
  77 .in +2
  78 .nf
  79 #include <stdio.h>
  80 #include <stdlib.h>
  81 #include <string.h>
  82 struct node {   /* these are stored in the table */
  83     char *string;
  84     int length;
  85 };
  86 static struct node table[] = {    /* table to be searched */
  87     { "asparagus", 10 },
  88     { "beans", 6 },
  89     { "tomato", 7 },
  90     { "watermelon", 11 },
  91 };
  92
  93 main()
  94 {
  95     struct node *node_ptr, node;
  96     /* routine to compare 2 nodes */
  97     static int node_compare(const void *, const void *);
  98     char str_space[20];   /* space to read string into */
  99
 100     node.string = str_space;
 101     while (scanf("%20s", node.string) != EOF) {
 102         node_ptr = bsearch( &node,
 103             table, sizeof(table)/sizeof(struct node),
 104             sizeof(struct node), node_compare);
 105         if (node_ptr != NULL) {
 106             (void) printf("string = %20s, length = %d\en",
 107                 node_ptr\(mi>string, node_ptr\(mi>length);
 108         } else {
 109             (void)printf("not found: %20s\en", node.string);
 110         }
 111     }
 112     return(0);
 113 }
 114
 115 /* routine to compare two nodes based on an  */
 116 /* alphabetical ordering of the string field */
 117 static int
 118 node_compare(const void *node1, const void *node2) {
 119     return (strcmp(
 120             ((const struct node *)node1)\(mi>string,
 121             ((const struct node *)node2)\(mi>string));
 122 }
 123 .fi
 124 .in -2
 125
 126 .SH ATTRIBUTES
 127 .sp
 128 .LP
 129 See \fBattributes\fR(5) for descriptions of the following attributes:
 130 .sp
 131
 132 .sp
 133 .TS
 134 box;
 135 c | c
 136 l | l .
 137 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 138 _
 139 Interface Stability     Standard
 140 _
 141 MT-Level        MT-Safe
 142 .TE
 143
 144 .SH SEE ALSO
 145 .sp
 146 .LP
 147 \fBhsearch\fR(3C), \fBlsearch\fR(3C), \fBqsort\fR(3C), \fBtsearch\fR(3C),
 148 \fBattributes\fR(5), \fBstandards\fR(5)