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