stdlib/hcreate.3

   1 .\" $FreeBSD: src/lib/libc/stdlib/hcreate.3,v 1.2 2001/07/09 15:54:36 ru Exp $
   2 .\"
   3 .Dd May 8, 2001
   4 .Os
   5 .Dt HCREATE 3
   6 .Sh NAME
   7 .Nm hcreate , hdestroy , hsearch
   8 .Nd manage hash search table
   9 .Sh LIBRARY
  10 .Lb libc
  11 .Sh SYNOPSIS
  12 .In search.h
  13 .Ft int
  14 .Fn hcreate "size_t nel"
  15 .Ft void
  16 .Fn hdestroy void
  17 .Ft ENTRY *
  18 .Fn hsearch "ENTRY item" "ACTION action"
  19 .Sh DESCRIPTION
  20 The
  21 .Fn hcreate ,
  22 .Fn hdestroy ,
  23 and
  24 .Fn hsearch
  25 functions manage hash search tables.
  26 .Pp
  27 The
  28 .Fn hcreate
  29 function allocates sufficient space for the table, and the application should
  30 ensure it is called before
  31 .Fn hsearch
  32 is used.
  33 The
  34 .Fa nel
  35 argument is an estimate of the maximum
  36 number of entries that the table should contain.
  37 This number may be adjusted upward by the
  38 algorithm in order to obtain certain mathematically favorable circumstances.
  39 .Pp
  40 The
  41 .Fn hdestroy
  42 function disposes of the search table, and may be followed by another call to
  43 .Fn hcreate .
  44 After the call to
  45 .Fn hdestroy ,
  46 the data can no longer be considered accessible.
  47 .Pp
  48 The
  49 .Fn hsearch
  50 function is a hash-table search routine.
  51 It returns a pointer into a hash table
  52 indicating the location at which an entry can be found.
  53 The
  54 .Fa item
  55 argument is a structure of type
  56 .Vt ENTRY
  57 (defined in the
  58 .Aq Pa search.h
  59 header) containing two pointers:
  60 .Fa item.key
  61 points to the comparison key (a
  62 .Vt "char *" ) ,
  63 and
  64 .Fa item.data
  65 (a
  66 .Vt "void *" )
  67 points to any other data to be associated with
  68 that key.
  69 The comparison function used by
  70 .Fn hsearch
  71 is
  72 .Xr strcmp 3 .
  73 The
  74 .Fa action
  75 argument is a
  76 member of an enumeration type
  77 .Vt ACTION
  78 indicating the disposition of the entry if it cannot be
  79 found in the table.
  80 .Dv ENTER
  81 indicates that the
  82 .Fa item
  83 should be inserted in the table at an
  84 appropriate point.
  85 .Dv FIND
  86 indicates that no entry should be made.
  87 Unsuccessful resolution is
  88 indicated by the return of a
  89 .Dv NULL
  90 pointer.
  91 .Sh RETURN VALUES
  92 The
  93 .Fn hcreate
  94 function returns 0 if it cannot allocate sufficient space for the table;
  95 otherwise, it returns non-zero.
  96 .Pp
  97 The
  98 .Fn hdestroy
  99 function does not return a value.
 100 .Pp
 101 The
 102 .Fn hsearch
 103 function returns a
 104 .Dv NULL
 105 pointer if either the
 106 .Fa action
 107 is
 108 .Dv FIND
 109 and the
 110 .Fa item
 111 could not be found or the
 112 .Fa action
 113 is
 114 .Dv ENTER
 115 and the table is full.
 116 .Sh ERRORS
 117 The
 118 .Fn hcreate
 119 and
 120 .Fn hsearch
 121 functions may fail if:
 122 .Bl -tag -width Er
 123 .It Bq Er ENOMEM
 124 Insufficient storage space is available.
 125 .El
 126 .Sh EXAMPLES
 127 The following example reads in strings followed by two numbers
 128 and stores them in a hash table, discarding duplicates.
 129 It then reads in strings and finds the matching entry in the hash
 130 table and prints it out.
 131 .Bd -literal
 132 #include <stdio.h>
 133 #include <search.h>
 134 #include <string.h>
 135
 136 struct info {                   /* This is the info stored in the table */
 137         int age, room;          /* other than the key. */
 138 };
 139
 140 #define NUM_EMPL        5000    /* # of elements in search table. */
 141
 142 int
 143 main(void)
 144 {
 145         char string_space[NUM_EMPL*20]; /* Space to store strings. */
 146         struct info info_space[NUM_EMPL]; /* Space to store employee info. */
 147         char *str_ptr = string_space; /* Next space in string_space. */
 148         struct info *info_ptr = info_space; /* Next space in info_space. */
 149         ENTRY item;
 150         ENTRY *found_item; /* Name to look for in table. */
 151         char name_to_find[30];
 152         int i = 0;
 153
 154         /* Create table; no error checking is performed. */
 155         (void) hcreate(NUM_EMPL);
 156
 157         while (scanf("%s%d%d", str_ptr, &info_ptr->age,
 158             &info_ptr->room) != EOF && i++ < NUM_EMPL) {
 159                 /* Put information in structure, and structure in item. */
 160                 item.key = str_ptr;
 161                 item.data = info_ptr;
 162                 str_ptr += strlen(str_ptr) + 1;
 163                 info_ptr++;
 164                 /* Put item into table. */
 165                 (void) hsearch(item, ENTER);
 166         }
 167
 168         /* Access table. */
 169         item.key = name_to_find;
 170         while (scanf("%s", item.key) != EOF) {
 171                 if ((found_item = hsearch(item, FIND)) != NULL) {
 172                         /* If item is in the table. */
 173                         (void)printf("found %s, age = %d, room = %d\en",
 174                             found_item->key,
 175                             ((struct info *)found_item->data)->age,
 176                             ((struct info *)found_item->data)->room);
 177                 } else
 178                         (void)printf("no such employee %s\en", name_to_find);
 179         }
 180         return 0;
 181 }
 182 .Ed
 183 .Sh SEE ALSO
 184 .Xr bsearch 3 ,
 185 .Xr lsearch 3 ,
 186 .Xr malloc 3 ,
 187 .Xr strcmp 3 ,
 188 .Xr tsearch 3
 189 .Sh STANDARDS
 190 The
 191 .Fn hcreate ,
 192 .Fn hdestroy ,
 193 and
 194 .Fn hsearch
 195 functions conform to
 196 .St -xpg4.2 .
 197 .Sh HISTORY
 198 The
 199 .Fn hcreate ,
 200 .Fn hdestroy ,
 201 and
 202 .Fn hsearch
 203 functions first appeared in
 204 .At V .
 205 .Sh BUGS
 206 The interface permits the use of only one hash table at a time.