---
name: "hash"
section: "3pub"
platform: "linux"
package: "publib-dev"
version: "0.40-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/hash/3pub"
---

# hash(3pub)

generic hash tables

## NAME

hash\_create, hash\_destroy, hash\_install, hash\_lookup, hash\_uninstall, hash\_iter - generic hash tables

## SYNOPSIS

```
#include <publib.h>

Hashtab *hash_create(unsigned long (*fun)(void *),
         int (*cmp)(const void *, const void *));
void hash_destroy(Hashtab *ht);
void *hash_install(Hashtab *ht, void *data, size_t size);
void *hash_lookup(Hashtab *ht, void *data);
int hash_uninstall(Hashtab *ht, void *data);
int hash_iter(Hashtab *ht, int (*doit)(void *, void *), void *param);
```

## DESCRIPTION

These functions implement generic hash tables. The table is created by *hash\_create* and destroyed by *hash\_destroy*. The *fun* argument is a pointer to the hashing function, which must convert a datum to an unsigned long, which is then converted to an index into the hashing table. *cmp* is a [*qsort*(3)](/qsort/3.md)-like comparison functions, used to compare to (wannabe) hash table elements.

*hash\_install* installs a new datum into the table. A pointer to the data and the size of the data are given as the arguments. If the size is 0, only the pointer value is copied to the table. Otherwise a copy of the data is made into dynamically allocated memory.

*hash\_lookup* attempts to find a datum in the hash table. A pointer to another datum is given as the argument. The comparison function should compare equal (return 0) the desired datum and this datum (but the argument needn't be a fully initialized datum, although that is up to the writer of the comparison function). There cannot be two elements in the hash table that are equal (the comparison function returns 0 for them). It is up to the user to handle collisions.

*hash\_uninstall* removes an element from a table. The argument is a pointer to a datum that identifies the element.

*hash\_iter* goes through every element in the hash table and calls the *doit* function for each. The first argument it provides to *doit* is the element in question, the second is whatever was given to *hash\_iter* as *param*. If *doit* returns -1 or 0 for any element in the hash table, *hash\_iter* immediately returns without going through the remaining elements in the hash table. Any other return value from *doit* is ignored.

## RETURNS

*hash\_create* returns a pointer to the new hash table, or NULL if it fails.

*hash\_install* returns a pointer to an element in the table (either the installed one, or one that was already installed, if one tries to install the same datum twice).

*hash\_uninstall* returns 0 if it found the element in the array, or -1 if it didn't.

*hash\_lookup* return a pointer to the element it finds, or NULL if it doesn't find anything beautiful.

*hash\_iter* returns -1, 0, or 1.  If *hash\_iter* receives a return value of -1 or 0 for some element from *doit*, *hash\_iter* immediately returns -1 or 0, respectively. In all other cases *hash\_iter* returns 1.

## SEE ALSO

publib(3), [qsort(3)](/qsort/3.md), [bsearch(3)](/bsearch/3.md)

## AUTHOR

Lars Wirzenius (lars.wirzenius@helsinki.fi)