HCREATE(3)

NAME
hcreate, hdestroy, hsearch - manage hash search table

LIBRARY
libc

SYNOPSIS
#include <search.h>
int
hcreate(size_t nel);
void
hdestroy(void);
ENTRY *
hsearch(ENTRY item, ACTION action);

DESCRIPTION
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, a structural type which contains the following members:
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 which defines the following values:
ENTER
    insert item into the hash table, possibly replacing an existing item.
FIND
    search the hash table without inserting item. Unsuccessful resolution is indicated by the return of a NULL pointer.

RETURN VALUES
If successful, the hcreate() function returns a non-zero value. Otherwise, a value of 0 is returned and errno is set to indicate the error.

The hdestroy() functions returns no value.

If successful, the hsearch() function returns a pointer to the item. 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.

ERRORS
The hcreate() and hsearch() functions will fail if:

[ENOMEM]
    Insufficient memory is available.

SEE ALSO
bsearch(3), lsearch(3), malloc(3), strcmp(3)

STANDARDS
The hcreate(), hdestroy() and hsearch() functions conform to xpg4.2.

BUGS
The hsearch() function currently returns a pointer into a static buffer area; subsequent calls to hsearch() may overwrite this buffer.

The interface permits the use of only one hash table at a time.

HISTORY
The hcreate(), hdestroy() and hsearch() functions first appeared in AT&T UNIX.