1 .\" $FreeBSD: src/lib/libc/stdlib/hcreate.3,v 1.2.2.2 2003/04/05 13:53:05 dwmalone Exp $
2 .\" $DragonFly: src/lib/libc/stdlib/hcreate.3,v 1.2 2003/06/17 04:26:46 dillon Exp $
8 .Nm hcreate , hdestroy , hsearch
9 .Nd manage hash search table
15 .Fn hcreate "size_t nel"
19 .Fn hsearch "ENTRY item" "ACTION action"
26 functions manage hash search tables.
30 function allocates sufficient space for the table, and the application should
31 ensure it is called before
36 argument is an estimate of the maximum
37 number of entries that the table should contain.
38 This number may be adjusted upward by the
39 algorithm in order to obtain certain mathematically favorable circumstances.
43 function disposes of the search table, and may be followed by another call to
47 the data can no longer be considered accessible.
52 for each comparison key in the search table
53 but not the data item associated with the key.
57 function is a hash-table search routine.
58 It returns a pointer into a hash table
59 indicating the location at which an entry can be found.
62 argument is a structure of type
66 header) containing two pointers:
68 points to the comparison key (a
74 points to any other data to be associated with
76 The comparison function used by
83 member of an enumeration type
85 indicating the disposition of the entry if it cannot be
90 should be inserted in the table at an
93 indicates that no entry should be made.
94 Unsuccessful resolution is
95 indicated by the return of a
99 The comparison key (passed to
103 must be allocated using
115 function returns 0 if it cannot allocate sufficient space for the table;
116 otherwise, it returns non-zero.
120 function does not return a value.
126 pointer if either the
132 could not be found or the
136 and the table is full.
142 functions may fail if:
145 Insufficient storage space is available.
148 The following example reads in strings followed by two numbers
149 and stores them in a hash table, discarding duplicates.
150 It then reads in strings and finds the matching entry in the hash
151 table and prints it out.
158 struct info { /* This is the info stored in the table */
159 int age, room; /* other than the key. */
162 #define NUM_EMPL 5000 /* # of elements in search table. */
167 char str[BUFSIZ]; /* Space to read string */
168 struct info info_space[NUM_EMPL]; /* Space to store employee info. */
169 struct info *info_ptr = info_space; /* Next space in info_space. */
171 ENTRY *found_item; /* Name to look for in table. */
172 char name_to_find[30];
175 /* Create table; no error checking is performed. */
176 (void) hcreate(NUM_EMPL);
178 while (scanf("%s%d%d", str, &info_ptr->age,
179 &info_ptr->room) != EOF && i++ < NUM_EMPL) {
180 /* Put information in structure, and structure in item. */
181 item.key = strdup(str);
182 item.data = info_ptr;
184 /* Put item into table. */
185 (void) hsearch(item, ENTER);
189 item.key = name_to_find;
190 while (scanf("%s", item.key) != EOF) {
191 if ((found_item = hsearch(item, FIND)) != NULL) {
192 /* If item is in the table. */
193 (void)printf("found %s, age = %d, room = %d\en",
195 ((struct info *)found_item->data)->age,
196 ((struct info *)found_item->data)->room);
198 (void)printf("no such employee %s\en", name_to_find);
224 functions first appeared in
227 The interface permits the use of only one hash table at a time.