Content-type: text/html
hsearch, hcreate, hdestroy, hsearch_r, hcreate_r, hdestroy_r - Manage hash tables
Standard C Library (libc.so, libc.a)
#include <search.h>
ENTRY *hsearch(
ENTRY item,
ACTION action);
int hcreate(
size_t nel);
void hdestroy(void);
int hsearch_r(
ENTRY item,
ACTION action,
ENTRY **target,
struct hsearch_data *hsearch_data);
int hcreate_r(
size_t nel,
struct hsearch_data *hsearch_data);
void hdestroy_r(
struct hsearch_data *hsearch_data);
Interfaces documented on this reference page conform to industry standards as follows:
hsearch(), hcreate(), hdestroy(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about industry standards and associated tags.
Identifies a structure of the type ENTRY as defined in the search.h header file. It contains two pointers: Points to the comparison key string. Points to any other data associated with the char *key parameter.
The hsearch(), hcreate(), and hdestroy() functions are used to manage hash table operations: The hcreate() function initializes the hash table. You must call the hcreate() function before calling the hsearch() function. The hsearch() function searches a hash table. It returns a pointer into a hash table that indicates where a given entry can be found. The hsearch() function uses open addressing with a hash function. The hdestroy() function deletes the hash table. This allows you to start a new hash table because only one table may be active at a time. After the call to hdestroy(), the hash table data should no longer be considered accessible.
[Digital] The hsearch_r(), hcreate_r(), and hdestroy_r() functions are reentrant versions of hsearch(), hcreate(), and hdestroy(). Upon successful completion, the hsearch_r() function returns 0 (zero). Upon failure, it returns -1 and sets errno.
[Digital] Threads can share hash tables by using the hcreate_r, hsearch_r, and hdestroy_r functions with a common hsearch_data value. To prevent corruption of data when sharing a hash table, locks must be used around calls that use the common hsearch_data value.
The hsearch() function returns a null pointer when the action parameter is FIND and the key pointed to by item cannot be found or when the specified action is ENTER and the hash table is full.
Upon successful completion, the hcreate() function returns a nonzero value. Otherwise, when sufficient space for the table cannot be allocated, the hcreate() function returns a value of 0 (zero).
If any of the following conditions occur, the hsearch() function sets errno to the corresponding value: The table is full. [Digital] The search failed.
Functions: bsearch(3), lsearch(3), tsearch(3), qsort(3)
Standards: standards(5) delim off