2 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
3 .\" All rights reserved.
5 .\" This code is derived from software contributed to The NetBSD Foundation
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\" $FreeBSD: src/lib/libc/stdlib/hcreate.3,v 1.7 2008/07/06 17:03:37 danger Exp $
38 .Nd manage hash search table
44 .Fn hcreate "size_t nel"
48 .Fn hsearch "ENTRY item" "ACTION action"
55 functions manage hash search tables.
59 function allocates sufficient space for the table, and the application should
60 ensure it is called before
65 argument is an estimate of the maximum
66 number of entries that the table should contain.
67 This number may be adjusted upward by the
68 algorithm in order to obtain certain mathematically favorable circumstances.
72 function disposes of the search table, and may be followed by another call to
76 the data can no longer be considered accessible.
81 for each comparison key in the search table
82 but not the data item associated with the key.
86 function is a hash-table search routine.
87 It returns a pointer into a hash table
88 indicating the location at which an entry can be found.
91 argument is a structure of type
95 header) containing two pointers:
97 points to the comparison key (a
103 points to any other data to be associated with
105 The comparison function used by
112 member of an enumeration type
114 indicating the disposition of the entry if it cannot be
119 should be inserted in the table at an
122 indicates that no entry should be made.
123 Unsuccessful resolution is
124 indicated by the return of a
128 The comparison key (passed to
132 must be allocated using
144 function returns 0 if the table creation failed and the global variable
146 is set to indicate the error;
147 otherwise, a non-zero value is returned.
151 function does not return a value.
157 pointer if either the
163 could not be found or the
167 and the table is full.
169 The following example reads in strings followed by two numbers
170 and stores them in a hash table, discarding duplicates.
171 It then reads in strings and finds the matching entry in the hash
172 table and prints it out.
179 struct info { /* This is the info stored in the table */
180 int age, room; /* other than the key. */
183 #define NUM_EMPL 5000 /* # of elements in search table. */
188 char str[BUFSIZ]; /* Space to read string */
189 struct info info_space[NUM_EMPL]; /* Space to store employee info. */
190 struct info *info_ptr = info_space; /* Next space in info_space. */
192 ENTRY *found_item; /* Name to look for in table. */
193 char name_to_find[30];
196 /* Create table; no error checking is performed. */
197 (void) hcreate(NUM_EMPL);
199 while (scanf("%s%d%d", str, &info_ptr->age,
200 &info_ptr->room) != EOF && i++ < NUM_EMPL) {
201 /* Put information in structure, and structure in item. */
202 item.key = strdup(str);
203 item.data = info_ptr;
205 /* Put item into table. */
206 (void) hsearch(item, ENTER);
210 item.key = name_to_find;
211 while (scanf("%s", item.key) != EOF) {
212 if ((found_item = hsearch(item, FIND)) != NULL) {
213 /* If item is in the table. */
214 (void)printf("found %s, age = %d, room = %d\en",
216 ((struct info *)found_item->data)->age,
217 ((struct info *)found_item->data)->room);
219 (void)printf("no such employee %s\en", name_to_find);
230 functions may fail if:
233 Insufficient storage space is available.
235 A table already exists.
257 functions first appeared in
260 The interface permits the use of only one hash table at a time.