July 1, 2008 HASHINIT 9

### NAME

hashinit, hashdone - kernel hash table construction and destruction

### SYNOPSIS

```void *` hashinit(`` ```u_int chains` ```enum hashtype htype` ```bool waitok` ```u_long *hashmask` )
```void` hashdone(```void *hashtbl``, enum hashtype htype``, u_long hashmask`)

### DESCRIPTION

The hashinit(``) function allocates and initializes space for a simple chaining hash table. The number of slots will be the least power of two not smaller than ```chains`. The customary choice for ```chains` is the maximum number of elements you intend to store divided by your intended load factor. The ```LIST...` or ```TAILQ...` macros of queue(3) can be used to manipulate the chains; pass ```HASH_LIST` or ```HASH_TAILQ` as ```htype` to indicate which. Each slot will be initialized as the head of an empty chain of the proper type. Because different data structures from queue(3) can define head structures of different sizes, the total size of the allocated table can vary with the choice of ```htype`.

If ```waitok` is true, ```hashinit` can wait until enough memory is available. Otherwise, it immediately fails if there is not enough memory is available.

A value will be stored into ```*hashmask` suitable for masking any computed hash, to obtain the index of a chain head in the allocated table.

The hashdone(``) function deallocates the storage allocated by hashinit(``) and pointed to by ```hashtbl`, given the same ```htype` and ```hashmask` that were passed to and returned from hashinit(``). If the table contains any nonempty chain when hashdone(``) is called, the result is undefined.

### RETURN VALUES

The value returned by hashinit(``) should be cast as pointer to an array of ```LIST_HEAD` or ```TAILQ_HEAD` as appropriate. hashinit(``) returns ```NULL` on failure.

### SEE ALSO

queue(3), hash(9), malloc(9)

### CODE REFERENCES

These functions are implemented in ```sys/kern/subr_hash.c`.

### HISTORY

A hashinit(``) function was present, without the ```htype` or ```mflags` arguments, in 4.4BSDalpha. It was independent of queue(3) and simply allocated and nulled a table of pointer-sized slots. It sized the table to the largest power of two not greater than ```chains`; that is, it built in a load factor between 1 and 2.

NetBSD1.0 was the first NetBSD release to have a hashinit(``) function. It resembled that from 4.4BSD but made each slot a ```LIST_HEAD` from queue(3). For NetBSD1.3.3 it had been changed to size the table to the least power of two not less than or equal to ```chains`. By NetBSD1.4 it had the ```mflags` argument and the current sizing rule.

NetBSD1.5 had the hashdone(``) function. By NetBSD1.6 hashinit(``) supported ```LIST` or ```TAILQ` chains selected with ```htype`.

FreeBSD has a hashinit(``) with behavior equivalent (as of FreeBSD6.1) to that in NetBSD1.0, and a hashdestroy(``) that behaves as hashdone(``) but checks that all chains are empty first. OpenBSD has a hashinit(``) comparable (as of OpenBSD3.9) to that of NetBSD1.4. This manual page was added for NetBSD4.0.

### BUGS

The only part of the work of implementing a hash table that these functions relieve is the part that isn't much work.