1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
.\" Hey Emacs! This file is -*- nroff -*- source.
.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de)
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.\" References consulted:
.\" SunOS 4.1.1 man pages
.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
.TH HSEARCH 3 "September 30, 1995" "GNU" "Linux Programmer's Manual"
.SH NAME
hcreate, hdestroy, hsearch \- hash table management
.SH SYNOPSIS
.nf
.B #include <search.h>
.sp
.BI "ENTRY *hsearch(ENTRY " item ", ACTION " action ");"
.sp
.BI "int hcreate(unsigned " nel ");"
.sp
.B "void hdestroy(void);"
.RE
.fi
.SH DESCRIPTION
These three functions allow the user to create a hash table which
associates a key with any data.
.PP
First the table must be created with the function \fBhcreate()\fP.
\fInel\fP is an estimate of the number of entries in the table.
\fBhcreate()\fP may adjust this value upward to improve the
performance of the resulting hash table. The GNU implementation of
\fBhsearch()\fP will also enlarge the table if it gets nearly full.
\fBmalloc(3)\fP is used to allocate space for the table.
.PP
The corresponding function \fBhdestroy()\fP frees the memory occupied by
the hash table so that a new table can be constructed.
.PP
\fIitem\fP is of type \fBENTRY\fP, which is a typedef defined in
\fI<search.h>\fP and includes these elements:
.sp
.nf
typedef struct entry
{
char *\fIkey\fP;
char *\fIdata\fP;
} ENTRY;
.fi
.sp
\fIkey\fP points to the zero-terminated ASCII string which is the
search key. \fIdata\fP points to the data associated with that key.
(A pointer to a type other than character should be cast to
pointer-to-character.) \fBhsearch()\fP searches the hash table for an
item with the same key as \fIitem\fP, and if successful returns a
pointer to it. \fIaction\fP determines what \fBhsearch()\fP does
after an unsuccessful search. A value of \fBENTER\fP instructs it to
insert the new item, while a value of \fBFIND\fP means to return
\fBNULL\fP.
.SH "RETURN VALUE"
\fBhcreate()\fP returns \fBNULL\fP if the hash table cannot be
successfully installed.
.PP
\fBhsearch()\fP returns \fBNULL\fP if \fIaction\fP is \fBENTER\fP and
there is insufficient memory to expand the hash table, or \fIaction\fP
is \fBFIND\fP and \fIitem\fP cannot be found in the hash table.
.SH "CONFORMS TO"
.TP
SVID, except that in SysV, the hash table cannot grow.
.SH BUGS
The implementation can manage only one hash table at a time.
Individual hash table entries can be added, but not deleted.
.SH EXAMPLE
.PP
The following program inserts 24 items in to a hash table, then prints
some of them.
.nf
#include <stdio.h>
#include <search.h>
char *data[]={ "alpha", "bravo", "charley", "delta",
"echo", "foxtrot", "golf", "hotel", "india", "juliette",
"kilo", "lima", "mike", "november", "oscar", "papa",
"quebec", "romeo", "sierra", "tango", "uniform",
"victor", "whiskey", "x-ray", "yankee", "zulu"
};
int main()
{
ENTRY e, *ep;
int i;
/* start with small table, and let it grow */
hcreate(3);
for (i = 0; i < 24; i++)
{
e.key = data[i];
/* data is just an integer, instead of a pointer
to something */
e.data = (char *)i;
ep = hsearch(e, ENTER);
/* there should be no failures */
if(ep == NULL) {fprintf(stderr, "entry failed\\n"); exit(1);}
}
for (i = 22; i < 26; i++)
/* print two entries from the table, and show that
two are not in the table */
{
e.key = data[i];
ep = hsearch(e, FIND);
printf("%9.9s -> %9.9s:%d\\n", e.key, ep?ep->key:"NULL",
ep?(int)(ep->data):0);
}
return 0;
}
.fi
.SH "SEE ALSO"
.BR bsearch (3),
.\" .BR lsearch (3),
.BR tsearch (3),
.BR malloc "(3).
|
