manage hash search table
functions manage hash search tables.
function allocates and initializes the table. The nel
argument specifies an estimate of the maximum number of entries to be held
by the table. Unless further memory allocation fails, supplying an
insufficient nel value will not result in functional
harm, although a performance degradation may occur. Initialization using the
hcreate() function is mandatory prior to any access
function destroys a table previously created using
hcreate(). After a call to
hdestroy(), the data can no longer be accessed.
function is used to search the hash table. It returns a pointer into the
hash table indicating the address of an item. The item
argument is of type ENTRY, defined in the
<search.h> header. This is a
structure type that contains two pointers:
- char *key
- comparison key
- void *data
- pointer to data associated with key
The key comparison function used by
The action argument is of type ACTION, an enumeration type which defines the following values:
- Insert item into the hash table. If an existing item with the same key is found, it is not replaced. Note that the key and data elements of item are used directly by the new table entry. The storage for the key must not be modified during the lifetime of the hash table.
- Search the hash table without inserting item.
Note that the comparison key
must be allocated using malloc(3) or
if action is
will be called. This is because
hdestroy() will call
each comparison key (but not
data). Typically the comparison
key is allocated by using
If successful, the
returns a non-zero value. Otherwise, a value of 0 is returned and
errno is set to indicate the error.
If successful, the
returns a pointer to a hash table entry matching the provided key. If the
FIND and the item was not found, or if the
ENTER and the insertion failed,
NULL is returned and errno is
set to indicate the error. If the action is
and an entry already existed in the table matching the given key, the
existing entry is returned and is not replaced.
hsearch() functions will fail if:
- Insufficient memory is available.
bsearch(3), lsearch(3), malloc(3), strcmp(3)
functions conform to X/Open Portability Guide
Issue 4, Version 2 (“XPG4.2”).
functions first appeared in AT&T System V
At least the following limitations can be mentioned:
- The interface permits the use of only one hash table at a time.
- Individual hash table entries can be added, but not deleted.
- The standard is indecipherable about the internal memory usage of the
functions, mentioning only that “
hsearch() functions may use
malloc() to allocate space”. This limits the portability of the functions, given that other implementations may not free(3) the buffer pointed by key.