NAME
hcreate, hdestroy,
hsearch —
manage hash search table
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, 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
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).
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 a 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.
ERRORS
The hcreate() and
hsearch() functions will fail if:
- [
ENOMEM] - Insufficient memory is available.
SEE ALSO
STANDARDS
The hcreate(),
hdestroy() and hsearch()
functions conform to X/Open Portability Guide
Issue 4, Version 2 (“XPG4.2”).
HISTORY
The hcreate(),
hdestroy() and hsearch()
functions first appeared in AT&T System V
UNIX.
CAVEATS
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 “
hcreate() andhsearch() functions may usemalloc() to allocate space”. This limits the portability of the functions, given that other implementations may not free(3) the buffer pointed by key.