NAME

     hash, hash32, hash32_buf, hash32_str, hash32_strn, hash32_stre, hash32_strne, jenkins_hash,
     jenkins_hash32, murmur3_32_hash, murmur3_32_hash32 — general kernel hashing functions

SYNOPSIS

     #include <sys/hash.h>

     uint32_t
     hash32_buf(const void *buf, size_t len, uint32_t hash);

     uint32_t
     hash32_str(const void *buf, uint32_t hash);

     uint32_t
     hash32_strn(const void *buf, size_t len, uint32_t hash);

     uint32_t
     hash32_stre(const void *buf, int end, const char **ep, uint32_t hash);

     uint32_t
     hash32_strne(const void *buf, size_t len, int end, const char **ep, uint32_t hash);

     uint32_t
     jenkins_hash(const void *buf, size_t len, uint32_t hash);

     uint32_t
     jenkins_hash32(const uint32_t *buf, size_t count, uint32_t hash);

     uint32_t
     murmur3_32_hash(const void *buf, size_t len, uint32_t hash);

     uint32_t
     murmur3_32_hash32(const uint32_t *buf, size_t count, uint32_t hash);

DESCRIPTION

     The hash32() functions are used to give a consistent and general interface to a decent
     hashing algorithm within the kernel.  These functions can be used to hash ASCII NUL
     terminated strings, as well as blocks of memory.

     A len argument is the length of the buffer in bytes.  A count argument is the length of the
     buffer in 32-bit words.

     The hash32_buf() function is used as a general buffer hashing function.  The argument buf is
     used to pass in the location, and len is the length of the buffer in bytes.  The argument
     hash is used to extend an existing hash, or is passed the initial value HASHINIT to start a
     new hash.

     The hash32_str() function is used to hash a NUL terminated string passed in buf with initial
     hash value given in hash.

     The hash32_strn() function is like the hash32_str() function, except it also takes a len
     argument, which is the maximal length of the expected string.

     The hash32_stre() and hash32_strne() functions are helper functions used by the kernel to
     hash pathname components.  These functions have the additional termination condition of
     terminating when they find a character given by end in the string to be hashed.  If the
     argument ep is not NULL, it is set to the point in the buffer at which the hash function
     terminated hashing.

     The jenkins_hash() function has same semantics as the hash32_buf(), but provides more
     advanced hashing algorithm with better distribution.

     The jenkins_hash32() uses same hashing algorithm as the jenkins_hash() function, but works
     only on uint32_t sized arrays, thus is simpler and faster.  It accepts an array of uint32_t
     values in its first argument and size of this array in the second argument.

     The murmur3_32_hash() and murmur3_32_hash32() functions are similar to jenkins_hash() and
     jenkins_hash32(), but implement the 32-bit version of MurmurHash3.

RETURN VALUES

     The hash32() functions return a 32 bit hash value of the buffer or string.

EXAMPLES

           LIST_HEAD(head, cache) *hashtbl = NULL;
           u_long mask = 0;

           void
           sample_init(void)
           {

                   hashtbl = hashinit(numwanted, type, flags, &mask);
           }

           void
           sample_use(char *str, int len)
           {
                   uint32_t hash;

                   hash = hash32_str(str, HASHINIT);
                   hash = hash32_buf(&len, sizeof(len), hash);
                   hashtbl[hash & mask] = len;
           }

SEE ALSO

     free(9), hashinit(9), malloc(9)

LIMITATIONS

     The hash32() functions are only 32 bit functions.  They will prove to give poor 64 bit
     performance, especially for the top 32 bits.  At the current time, this is not seen as a
     great limitation, as these hash values are usually used to index into an array.  Should
     these hash values be used for other means, this limitation should be revisited.

HISTORY

     The hash functions first appeared in NetBSD 1.6.  The current implementation of hash32
     functions was first committed to OpenBSD 3.2, and later imported to FreeBSD 6.1.  The
     jenkins_hash functions were added in FreeBSD 10.0.  The murmur3_32_hash functions were added
     in FreeBSD 10.1.

AUTHORS

     The hash32 functions were written by Tobias Weingartner.  The jenkins_hash functions were
     written by
     Bob Jenkins.  The murmur3_32_hash functions were written by
     Dag-Erling Smørgrav <des@FreeBSD.org>.