February 13, 2001 HCREATE 3

### NAME

hcreate, hdestroy, hsearch - manage hash search table

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```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 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`, a structural type which contains the following members:

```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`.

### 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.

The hdestroy(``) functions returns 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.

### 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`.

### BUGS

The interface permits the use of only one hash table at a time.