[OpenBSD]

Manual Page Search Parameters

HCREATE(3) Library Functions Manual HCREATE(3)

NAME

hcreate, hdestroy, hsearchmanage 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 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.
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

bsearch(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.

CAVEATS

At least the following limitations can be mentioned:
January 30, 2018 OpenBSD-current