HCREATE(3)

HCREATE(3) | Library Functions Manual | HCREATE(3)

# NAME

`hcreate`, `hcreate_r`, `hdestroy`, `hdestroy1`, `hdestroy_r`, `hdestroy1_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
`hdestroy1`(void (*freekey)(void *), void (*freedata)(void *));

void
`hdestroy_r`(struct hsearch_data *table);

void
`hdestroy1_r`(struct hsearch_data *table, void (*freekey)(void *), void (*freedata)(void *));

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`() `hdestroy1`(), `hdestroy1_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.

The traditional `hdestroy`() and `hdestroy_r`() functions don't free(3) the data associated with the key and value of each entry, because they did not allocate them. Since there is no “iterator” function provided, the `hdestroy1`() and `hdestroy1_r`() allow controlling how the key or value will be freed using the provided functions in the freekey and freedata arguments. If they are `NULL`, then key and value are not freed.

The `hcreate_r`(), `hdestroy_r`(), `hdestroy1_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 `FIND` and the element is not found:

[`ESRCH`]
  The item given is not found.

# SEE ALSO

bsearch(3), free(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. The `hdestroy1`() and `hdestroy1_r`() are NetBSD extensions.

# CAVEATS

At least the following limitations can be mentioned:

- The original, non-GNU interface permits the use of only one hash table at a time.
- Individual hash table entries can be added, but not deleted.
- There is no iterator to scan for all entries in the table.

February 7, 2017 | NetBSD 9.0