hcreate, hdestroy, hsearch - manage hash search table
hsearch(ENTRY item, ACTION action);
The hcreate(), hdestroy() and hsearch() functions manage
hash search tables.
The hcreate() 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
is mandatory prior to any access operations using
The hdestroy() function destroys a table previously created
hcreate(). After a call to hdestroy(), the data can no
longer be accessed.
The hsearch() function is used to search to the hash table.
It returns a
pointer into the hash table indicating the address of an
item. The item
argument is of type ENTRY, a structural type which contains
char *key comparison key.
void *data pointer to data associated with key.
The key comparison function used by hsearch() is strcmp(3).
The action argument is of type ACTION, an enumeration type
the following values:
ENTER 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.
FIND Search the hash table without inserting item.
If successful, the hcreate() function returns a non-zero
a value of 0 is returned and errno is set to indicate
The hdestroy() functions returns no value.
If successful, the hsearch() function returns a pointer to
hash table entry
matching the provided key. If the action is FIND and
the item was
not found, or if the action is ENTER and the insertion
failed, NULL is
returned and errno is set to indicate the error. If the action is ENTER
and an entry already existed in the table matching the given
key, the existing
entry is returned and is not replaced.
The hcreate() and hsearch() functions will fail if:
[ENOMEM] Insufficient memory is available.
bsearch(3), lsearch(3), malloc(3), strcmp(3)
The hcreate(), hdestroy() and hsearch() functions conform to
Portability Guide Issue 4.2 (``XPG4.2'').
The hcreate(), hdestroy() and hsearch() functions first appeared in AT&T
System V UNIX.
The interface permits the use of only one hash table at a
OpenBSD 3.6 February 13, 2001
[ Back ]