1.\"- 2.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 3.\" All rights reserved. 4.\" 5.\" This code is derived from software contributed to The NetBSD Foundation 6.\" by Klaus Klein. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd June 9, 2026 30.Dt HCREATE 3 31.Os 32.Sh NAME 33.Nm hcreate , 34.Nm hcreate_r , 35.Nm hdestroy , 36.Nm hdestroy_r , 37.Nm hsearch , 38.Nm hsearch_r 39.Nd manage hash search table 40.Sh LIBRARY 41.Lb libc 42.Sh SYNOPSIS 43.In search.h 44.Ft int 45.Fn hcreate "size_t nel" 46.Ft int 47.Fn hcreate_r "size_t nel" "struct hsearch_data *table" 48.Ft void 49.Fn hdestroy "void" 50.Ft void 51.Fn hdestroy_r "struct hsearch_data *table" 52.Ft ENTRY * 53.Fn hsearch "ENTRY item" "ACTION action" 54.Ft int 55.Fn hsearch_r "ENTRY item" "ACTION action" "ENTRY ** itemp" "struct hsearch_data *table" 56.Sh DESCRIPTION 57The 58.Fn hcreate , 59.Fn hcreate_r , 60.Fn hdestroy , 61.Fn hdestroy_r 62.Fn hsearch , 63and 64.Fn hsearch_r 65functions manage hash search tables. 66.Pp 67The 68.Fn hcreate 69function allocates sufficient space for the table, and the application should 70ensure it is called before 71.Fn hsearch 72is used. 73The 74.Fa nel 75argument is an estimate of the maximum 76number of entries that the table should contain. 77As this implementation resizes the hash table dynamically, 78this argument is ignored. 79.Pp 80The 81.Fn hdestroy 82function disposes of the search table, and may be followed by another call to 83.Fn hcreate . 84After the call to 85.Fn hdestroy , 86the data can no longer be considered accessible. 87The 88.Fn hdestroy 89function disposes of the search table but does not free 90the comparison keys or data items stored in it. 91The caller is responsible for freeing any memory associated 92with table entries before calling 93.Fn hdestroy . 94.Pp 95The 96.Fn hsearch 97function is a hash-table search routine. 98It returns a pointer into a hash table 99indicating the location at which an entry can be found. 100The 101.Fa item 102argument is a structure of type 103.Vt ENTRY 104(defined in the 105.In search.h 106header) that contains two pointers: 107.Fa item.key 108points to the comparison key (a 109.Vt "char *" ) , 110and 111.Fa item.data 112(a 113.Vt "void *" ) 114points to any other data to be associated with 115that key. 116The comparison function used by 117.Fn hsearch 118is 119.Xr strcmp 3 . 120The 121.Fa action 122argument is a 123member of an enumeration type 124.Vt ACTION 125indicating the disposition of the entry if it cannot be 126found in the table. 127.Dv ENTER 128indicates that the 129.Fa item 130should be inserted in the table at an 131appropriate point. 132.Dv FIND 133indicates that no entry should be made. 134Unsuccessful resolution is 135indicated by the return of a 136.Dv NULL 137pointer. 138.Pp 139The comparison key (passed to 140.Fn hsearch 141as 142.Fa item.key ) 143must be allocated using 144.Xr malloc 3 145if 146.Fa action 147is 148.Dv ENTER 149and 150.Fn hdestroy 151is called. 152.Pp 153The 154.Fn hcreate_r , 155.Fn hdestroy_r , 156and 157.Fn hsearch_r 158functions are re-entrant versions of the above functions that can 159operate on a table supplied by the user. 160The 161.Fn hsearch_r 162function returns 163.Dv 0 164if the action is 165.Dv ENTER 166and the element cannot be created, 167.Dv 1 168otherwise. 169If the element exists or can be created, it will be placed in 170.Fa itemp , 171otherwise 172.Fa itemp 173will be set to 174.Dv NULL . 175.Sh RETURN VALUES 176The 177.Fn hcreate 178and 179.Fn hcreate_r 180functions return 0 if the table creation failed and the global variable 181.Va errno 182is set to indicate the error; 183otherwise, a non-zero value is returned. 184.Pp 185The 186.Fn hdestroy 187and 188.Fn hdestroy_r 189functions return no value. 190.Pp 191The 192.Fn hsearch 193and 194.Fn hsearch_r 195functions return a 196.Dv NULL 197pointer if either the 198.Fa action 199is 200.Dv FIND 201and the 202.Fa item 203could not be found or the 204.Fa action 205is 206.Dv ENTER 207and the table is full. 208.Sh EXAMPLES 209The following example reads in strings followed by two numbers 210and stores them in a hash table, discarding duplicates. 211It then reads in strings and finds the matching entry in the hash 212table and prints it out. 213.Bd -literal 214#include <stdio.h> 215#include <search.h> 216#include <string.h> 217#include <stdlib.h> 218 219struct info { /* This is the info stored in the table */ 220 int age, room; /* other than the key. */ 221}; 222 223#define NUM_EMPL 5000 /* # of elements in search table. */ 224 225int 226main(void) 227{ 228 char str[BUFSIZ]; /* Space to read string */ 229 struct info info_space[NUM_EMPL]; /* Space to store employee info. */ 230 struct info *info_ptr = info_space; /* Next space in info_space. */ 231 ENTRY item; 232 ENTRY *found_item; /* Name to look for in table. */ 233 char name_to_find[30]; 234 int i = 0; 235 236 /* Create table; no error checking is performed. */ 237 (void) hcreate(NUM_EMPL); 238 239 while (scanf("%s%d%d", str, &info_ptr->age, 240 &info_ptr->room) != EOF && i++ < NUM_EMPL) { 241 /* Put information in structure, and structure in item. */ 242 item.key = strdup(str); 243 item.data = info_ptr; 244 info_ptr++; 245 /* Put item into table. */ 246 (void) hsearch(item, ENTER); 247 } 248 249 /* Access table. */ 250 item.key = name_to_find; 251 while (scanf("%s", item.key) != EOF) { 252 if ((found_item = hsearch(item, FIND)) != NULL) { 253 /* If item is in the table. */ 254 (void)printf("found %s, age = %d, room = %d\en", 255 found_item->key, 256 ((struct info *)found_item->data)->age, 257 ((struct info *)found_item->data)->room); 258 } else 259 (void)printf("no such employee %s\en", name_to_find); 260 } 261 hdestroy(); 262 return 0; 263} 264.Ed 265.Sh ERRORS 266The 267.Fn hcreate , 268.Fn hcreate_r , 269.Fn hsearch , 270and 271.Fn hsearch_r 272functions will fail if: 273.Bl -tag -width Er 274.It Bq Er ENOMEM 275Insufficient memory is available. 276.El 277.Pp 278The 279.Fn hsearch 280and 281.Fn hsearch_r 282functions will also fail if the action is 283.Dv FIND 284and the element is not found: 285.Bl -tag -width Er 286.It Bq Er ESRCH 287The 288.Fa item 289given is not found. 290.El 291.Sh SEE ALSO 292.Xr bsearch 3 , 293.Xr lsearch 3 , 294.Xr malloc 3 , 295.Xr strcmp 3 , 296.Xr tsearch 3 297.Sh STANDARDS 298The 299.Fn hcreate , 300.Fn hdestroy , 301and 302.Fn hsearch 303functions conform to 304.St -xpg4.2 . 305.Sh HISTORY 306The 307.Fn hcreate , 308.Fn hdestroy , 309and 310.Fn hsearch 311functions first appeared in 312.At V . 313The 314.Fn hcreate_r , 315.Fn hdestroy_r 316and 317.Fn hsearch_r 318functions are 319.Tn GNU 320extensions. 321.Sh BUGS 322The original, 323.Pf non- Tn GNU 324interface permits the use of only one hash table at a time. 325