|HCREATE(3)||Library Functions Manual||HCREATE(3)|
hsearch() functions manage hash search tables.
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
hdestroy() function destroys a table
previously created using
hcreate(). After a call to
hdestroy(), the data can no longer be accessed.
hsearch() function is used to search
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:
The key comparison function used by
The action argument is of type ACTION, an enumeration type which defines the following values:
Note that the comparison key must be
allocated using malloc(3) or
calloc(3) if action is
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
hcreate() function returns a non-zero value. Otherwise, a value of 0 is returned and errno is set to indicate the error.
If successful, the
returns a pointer to a hash table entry matching the provided key. If the
FIND and the item was not found, or if the
ENTER and the insertion failed,
NULL is returned and errno is
set to indicate the error. If the action is
and an entry already existed in the table matching the given key, the
existing entry is returned and is not replaced.
hsearch() functions will fail if:
hsearch() functions conform to X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”).
hsearch() functions first appeared in AT&T System V UNIX.
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.
|January 30, 2018||OpenBSD-current|