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
hcreate() function is mandatory prior to any access operations using
hsearch().
The
hdestroy() function destroys a table previously created using
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, defined in the
<search.h> header. This is a structure type that contains two pointers:
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 which defines 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.
Note that the comparison
key must be allocated using
malloc(3) or
calloc(3) if action is
ENTER and
hdestroy() will be called. This is because
hdestroy() will call
free(3) for each comparison
key (but not
data). Typically the comparison
key is allocated by using
strdup(3).