hsearch(3)hsearch(3)NAME
hsearch, hcreate, hdestroy, hsearch_r, hcreate_r, hdestroy_r - Manage
hash tables
SYNOPSIS
#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 );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
hsearch(), hcreate(), hdestroy(): XSH4.2
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
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 parame‐
ter.
Pointers to types other than char should be cast as char *.
Specifies a value for an ACTION enum type, which indicates what
is to be done with an item key when it cannot be found in the
hash table. The following two actions can be specified for this
parameter: Enter the key specified by the item parameter into
the hash table at the appropriate place. When the table is full,
a null pointer is returned. Do not enter the item key into the
table, but return a null pointer when an item key cannot be
found in the hash table. Specifies an estimate of the maximum
number of entries that the hash table will contain. Under some
circumstances, the hcreate() function may make the hash table
larger than specified to obtain mathematically favorable condi‐
tions for access to the hash table. Points at the hash table.
This table is kept in the thread's address space. Points at the
size of the hash table. Points at the log base 2 version of the
hash table length. Points at the number of entries in the hash
table. Specifies the length of the hash table. Specifies the
log base 2 version of the hash table length. Points to the item
actually found. Consists of data for the hash table.
DESCRIPTION
The hsearch(), hcreate(), and hdestroy() functions are used to manage
hash table operations: The hcreate() function initializes the hash ta‐
ble. 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 func‐
tion. 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.
[Tru64 UNIX] 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.
[Tru64 UNIX] 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.
RETURN VALUES
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 allo‐
cated, the hcreate() function returns a value of 0 (zero).
ERRORS
If any of the following conditions occur, the hsearch() function sets
errno to the corresponding value: The table is full. [Tru64 UNIX] The
search failed.
SEE ALSO
Functions: bsearch(3), lsearch(3), tsearch(3), qsort(3)
Standards: standards(5)hsearch(3)