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. 47.Pp 48The 49.Fn hsearch 50function is a hash-table search routine. 51It returns a pointer into a hash table 52indicating the location at which an entry can be found. 53The 54.Fa item 55argument is a structure of type 56.Vt ENTRY 57(defined in the 58.Aq Pa search.h 59header) containing two pointers: 60.Fa item.key 61points to the comparison key (a 62.Vt "char *" ) , 63and 64.Fa item.data 65(a 66.Vt "void *" ) 67points to any other data to be associated with 68that key. 69The comparison function used by 70.Fn hsearch 71is 72.Xr strcmp 3 . 73The 74.Fa action 75argument is a 76member of an enumeration type 77.Vt ACTION 78indicating the disposition of the entry if it cannot be 79found in the table. 80.Dv ENTER 81indicates that the 82.Fa item 83should be inserted in the table at an 84appropriate point. 85.Dv FIND 86indicates that no entry should be made. 87Unsuccessful resolution is 88indicated by the return of a 89.Dv NULL 90pointer. 91.Sh RETURN VALUES 92The 93.Fn hcreate 94function returns 0 if it cannot allocate sufficient space for the table; 95otherwise, it returns non-zero. 96.Pp 97The 98.Fn hdestroy 99function does not return a value. 100.Pp 101The 102.Fn hsearch 103function returns a 104.Dv NULL 105pointer if either the 106.Fa action 107is 108.Dv FIND 109and the 110.Fa item 111could not be found or the 112.Fa action 113is 114.Dv ENTER 115and the table is full. 116.Sh ERRORS 117The 118.Fn hcreate 119and 120.Fn hsearch 121functions may fail if: 122.Bl -tag -width Er 123.It Bq Er ENOMEM 124Insufficient storage space is available. 125.El 126.Sh EXAMPLES 127The following example reads in strings followed by two numbers 128and stores them in a hash table, discarding duplicates. 129It then reads in strings and finds the matching entry in the hash 130table and prints it out. 131.Bd -literal 132#include <stdio.h> 133#include <search.h> 134#include <string.h> 135 136struct info { /* This is the info stored in the table */ 137 int age, room; /* other than the key. */ 138}; 139 140#define NUM_EMPL 5000 /* # of elements in search table. */ 141 142int 143main(void) 144{ 145 char string_space[NUM_EMPL*20]; /* Space to store strings. */ 146 struct info info_space[NUM_EMPL]; /* Space to store employee info. */ 147 char *str_ptr = string_space; /* Next space in string_space. */ 148 struct info *info_ptr = info_space; /* Next space in info_space. */ 149 ENTRY item; 150 ENTRY *found_item; /* Name to look for in table. */ 151 char name_to_find[30]; 152 int i = 0; 153 154 /* Create table; no error checking is performed. */ 155 (void) hcreate(NUM_EMPL); 156 157 while (scanf("%s%d%d", str_ptr, &info_ptr->age, 158 &info_ptr->room) != EOF && i++ < NUM_EMPL) { 159 /* Put information in structure, and structure in item. */ 160 item.key = str_ptr; 161 item.data = info_ptr; 162 str_ptr += strlen(str_ptr) + 1; 163 info_ptr++; 164 /* Put item into table. */ 165 (void) hsearch(item, ENTER); 166 } 167 168 /* Access table. */ 169 item.key = name_to_find; 170 while (scanf("%s", item.key) != EOF) { 171 if ((found_item = hsearch(item, FIND)) != NULL) { 172 /* If item is in the table. */ 173 (void)printf("found %s, age = %d, room = %d\n", 174 found_item->key, 175 ((struct info *)found_item->data)->age, 176 ((struct info *)found_item->data)->room); 177 } else 178 (void)printf("no such employee %s\n", name_to_find); 179 } 180 return 0; 181} 182.Ed 183.Sh SEE ALSO 184.Xr bsearch 3 , 185.Xr lsearch 3 , 186.Xr malloc 3 , 187.Xr strcmp 3 , 188.Xr tsearch 3 189.Sh STANDARDS 190The 191.Fn hcreate , 192.Fn hdestroy , 193and 194.Fn hsearch 195functions conform to 196.St -xpg4.2 . 197.Sh HISTORY 198The 199.Fn hcreate , 200.Fn hdestroy , 201and 202.Fn hsearch 203functions first appeared in 204.At V . 205.Sh BUGS 206The interface permits the use of only one hash table at a time. 207