HCREATE(3) BSD Library Functions Manual HCREATE(3)NAME
hcreate, hcreate_r, hdestroy, hdestroy_r, hsearch, hsearch_r — manage
hash search table
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <search.h>
int
hcreate(size_t nel);
int
hcreate_r(size_t nel, struct hsearch_data *table);
void
hdestroy(void);
void
hdestroy_r(struct hsearch_data *table);
ENTRY *
hsearch(ENTRY item, ACTION action);
int
hsearch_r(ENTRY item, ACTION action, ENTRY ** itemp,
struct hsearch_data *table);
DESCRIPTION
The hcreate(), hcreate_r(), hdestroy(), hdestroy_r()hsearch(), and
hsearch_r() 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).
The hcreate_r(), hdestroy_r(), and hsearch_r() functions are re-entrant
versions of the above functions that can operate on a table supplied by
the user. The hsearch_r() function returns 0 if the action is ENTER and
the element cannot be created, 1 otherwise. If the element exists or can
be created, it will be placed in itemp, otherwise itemp will be set to
NULL.
RETURN VALUES
If successful, the hcreate() and hcreate_r() functions return a non-zero
value. Otherwise, a value of 0 is returned and errno is set to indicate
the error.
The hdestroy() and hdestroy_r() functions return 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 hsearch_r() function returns 1 unless the table is full, when it
returns 0. If hsearch() returns 0 or the element is not found, errno is
set to indicate the error.
ERRORS
The hcreate(), hcreate_r(), hsearch() and hsearch_r() functions will fail
if:
[ENOMEM] Insufficient memory is available.
The hsearch() and hsearch_r() functions will also fail if the action is
SEARCH and the element is not found:
[ESRCH] The item given is not found.
SEE ALSObsearch(3), lsearch(3), malloc(3), strcmp(3)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. The hcreate_r(), hdestroy_r() and hsearch_r() functions
are GNU extensions.
CAVEATS
At least the following limitations can be mentioned:
· The original, non-GNU interface permits the use of only one hash ta‐
ble 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() and 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.
BSD September 14, 2011 BSD