HCREATE(3) | Library Functions Manual | HCREATE(3) |
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);
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:
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:
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.
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.
The hsearch() and hsearch_r() functions will also fail if the action is SEARCH and the element is not found:
September 14, 2011 | NetBSD 6.1 |