1.\"
2.\" Copyright (c) 1991, 1993, 1994
3.\" The Regents of the University of California.  All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\" 3. Neither the name of the University nor the names of its contributors
14.\" may be used to endorse or promote products derived from this software
15.\" without specific prior written permission.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
29.\" $FreeBSD: src/lib/libc/stdlib/hcreate.3,v 1.2 2001/07/09 15:54:36 ru Exp $
30.\"
31.Dd May 8, 2001
32.Os
33.Dt HCREATE 3
34.Sh NAME
35.Nm hcreate , hdestroy , hsearch
36.Nd manage hash search table
37.Sh LIBRARY
38.Lb libc
39.Sh SYNOPSIS
40.In search.h
41.Ft int
42.Fn hcreate "size_t nel"
43.Ft void
44.Fn hdestroy void
45.Ft ENTRY *
46.Fn hsearch "ENTRY item" "ACTION action"
47.Sh DESCRIPTION
48The
49.Fn hcreate ,
50.Fn hdestroy ,
51and
52.Fn hsearch
53functions manage hash search tables.
54.Pp
55The
56.Fn hcreate
57function allocates sufficient space for the table, and the application should
58ensure it is called before
59.Fn hsearch
60is used.
61The
62.Fa nel
63argument is an estimate of the maximum
64number of entries that the table should contain.
65This number may be adjusted upward by the
66algorithm in order to obtain certain mathematically favorable circumstances.
67.Pp
68The
69.Fn hdestroy
70function disposes of the search table, and may be followed by another call to
71.Fn hcreate .
72After the call to
73.Fn hdestroy ,
74the data can no longer be considered accessible.
75.Pp
76The
77.Fn hsearch
78function is a hash-table search routine.
79It returns a pointer into a hash table
80indicating the location at which an entry can be found.
81The
82.Fa item
83argument is a structure of type
84.Vt ENTRY
85(defined in the
86.Aq Pa search.h
87header) containing two pointers:
88.Fa item.key
89points to the comparison key (a
90.Vt "char *" ) ,
91and
92.Fa item.data
93(a
94.Vt "void *" )
95points to any other data to be associated with
96that key.
97The comparison function used by
98.Fn hsearch
99is
100.Xr strcmp 3 .
101The
102.Fa action
103argument is a
104member of an enumeration type
105.Vt ACTION
106indicating the disposition of the entry if it cannot be
107found in the table.
108.Dv ENTER
109indicates that the
110.Fa item
111should be inserted in the table at an
112appropriate point.
113.Dv FIND
114indicates that no entry should be made.
115Unsuccessful resolution is
116indicated by the return of a
117.Dv NULL
118pointer.
119.Sh RETURN VALUES
120The
121.Fn hcreate
122function returns 0 if it cannot allocate sufficient space for the table;
123otherwise, it returns non-zero.
124.Pp
125The
126.Fn hdestroy
127function does not return a value.
128.Pp
129The
130.Fn hsearch
131function returns a
132.Dv NULL
133pointer if either the
134.Fa action
135is
136.Dv FIND
137and the
138.Fa item
139could not be found or the
140.Fa action
141is
142.Dv ENTER
143and the table is full.
144.Sh ERRORS
145The
146.Fn hcreate
147and
148.Fn hsearch
149functions may fail if:
150.Bl -tag -width Er
151.It Bq Er ENOMEM
152Insufficient storage space is available.
153.El
154.Sh EXAMPLES
155The following example reads in strings followed by two numbers
156and stores them in a hash table, discarding duplicates.
157It then reads in strings and finds the matching entry in the hash
158table and prints it out.
159.Bd -literal
160#include <stdio.h>
161#include <search.h>
162#include <string.h>
163
164struct info {			/* This is the info stored in the table */
165	int age, room;		/* other than the key. */
166};
167
168#define NUM_EMPL	5000	/* # of elements in search table. */
169
170int
171main(void)
172{
173	char string_space[NUM_EMPL*20]; /* Space to store strings. */
174	struct info info_space[NUM_EMPL]; /* Space to store employee info. */
175	char *str_ptr = string_space; /* Next space in string_space. */
176	struct info *info_ptr = info_space; /* Next space in info_space. */
177	ENTRY item;
178	ENTRY *found_item; /* Name to look for in table. */
179	char name_to_find[30];
180	int i = 0;
181
182	/* Create table; no error checking is performed. */
183	(void) hcreate(NUM_EMPL);
184
185	while (scanf("%s%d%d", str_ptr, &info_ptr->age,
186	    &info_ptr->room) != EOF && i++ < NUM_EMPL) {
187		/* Put information in structure, and structure in item. */
188		item.key = str_ptr;
189		item.data = info_ptr;
190		str_ptr += strlen(str_ptr) + 1;
191		info_ptr++;
192		/* Put item into table. */
193		(void) hsearch(item, ENTER);
194	}
195
196	/* Access table. */
197	item.key = name_to_find;
198	while (scanf("%s", item.key) != EOF) {
199		if ((found_item = hsearch(item, FIND)) != NULL) {
200			/* If item is in the table. */
201			(void)printf("found %s, age = %d, room = %d\en",
202			    found_item->key,
203			    ((struct info *)found_item->data)->age,
204			    ((struct info *)found_item->data)->room);
205		} else
206			(void)printf("no such employee %s\en", name_to_find);
207	}
208	return 0;
209}
210.Ed
211.Sh SEE ALSO
212.Xr bsearch 3 ,
213.Xr lsearch 3 ,
214.Xr malloc 3 ,
215.Xr strcmp 3 ,
216.Xr tsearch 3
217.Sh STANDARDS
218The
219.Fn hcreate ,
220.Fn hdestroy ,
221and
222.Fn hsearch
223functions conform to
224.St -xpg4.2 .
225.Sh HISTORY
226The
227.Fn hcreate ,
228.Fn hdestroy ,
229and
230.Fn hsearch
231functions first appeared in
232.At V .
233.Sh BUGS
234The interface permits the use of only one hash table at a time.
235