.\" 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 .TH HSEARCH 3 "September 30, 1995" "GNU" "Linux Programmer's Manual" .SH NAME hcreate, hdestroy, hsearch \- hash table management .SH SYNOPSIS .nf .B #include .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\fP(3) 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\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 #include 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), " lsearch "(3), " tsearch "(3), " malloc "(3)"