share/man/man9/hash.9

   1 .\" Copyright (c) 2001 Tobias Weingartner
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. The name of the author may not be used to endorse or promote products
  13 .\"    derived from this software without specific prior written permission.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\"     $OpenBSD: hash.9,v 1.5 2003/04/17 05:08:39 jmc Exp $
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd October 18, 2014
  30 .Dt HASH 9
  31 .Os
  32 .Sh NAME
  33 .Nm hash ,
  34 .Nm hash32 ,
  35 .Nm hash32_buf ,
  36 .Nm hash32_str ,
  37 .Nm hash32_strn ,
  38 .Nm hash32_stre ,
  39 .Nm hash32_strne ,
  40 .Nm jenkins_hash ,
  41 .Nm jenkins_hash32 ,
  42 .Nm murmur3_32_hash ,
  43 .Nm murmur3_32_hash32
  44 .Nd general kernel hashing functions
  45 .Sh SYNOPSIS
  46 .In sys/hash.h
  47 .Ft uint32_t
  48 .Fn hash32_buf "const void *buf" "size_t len" "uint32_t hash"
  49 .Ft uint32_t
  50 .Fn hash32_str "const void *buf" "uint32_t hash"
  51 .Ft uint32_t
  52 .Fn hash32_strn "const void *buf" "size_t len" "uint32_t hash"
  53 .Ft uint32_t
  54 .Fn hash32_stre "const void *buf" "int end" "const char **ep" "uint32_t hash"
  55 .Ft uint32_t
  56 .Fn hash32_strne "const void *buf" "size_t len" "int end" "const char **ep" "uint32_t hash"
  57 .Ft uint32_t
  58 .Fn jenkins_hash "const void *buf" "size_t len" "uint32_t hash"
  59 .Ft uint32_t
  60 .Fn jenkins_hash32 "const uint32_t *buf" "size_t count" "uint32_t hash"
  61 .Ft uint32_t
  62 .Fn murmur3_32_hash "const void *buf" "size_t len" "uint32_t hash"
  63 .Ft uint32_t
  64 .Fn murmur3_32_hash32 "const uint32_t *buf" "size_t count" "uint32_t hash"
  65 .Sh DESCRIPTION
  66 The
  67 .Fn hash32
  68 functions are used to give a consistent and general interface to
  69 a decent hashing algorithm within the kernel.
  70 These functions can be used to hash
  71 .Tn ASCII
  72 .Dv NUL
  73 terminated strings, as well as blocks of memory.
  74 .Pp
  75 The
  76 .Fn hash32_buf
  77 function is used as a general buffer hashing function.
  78 The argument
  79 .Fa buf
  80 is used to pass in the location, and
  81 .Fa len
  82 is the length of the buffer.
  83 The argument
  84 .Fa hash
  85 is used to extend an existing hash, or is passed the initial value
  86 .Dv HASHINIT
  87 to start a new hash.
  88 .Pp
  89 The
  90 .Fn hash32_str
  91 function is used to hash a
  92 .Dv NUL
  93 terminated string passed in
  94 .Fa buf
  95 with initial hash value given in
  96 .Fa hash .
  97 .Pp
  98 The
  99 .Fn hash32_strn
 100 function is like the
 101 .Fn hash32_str
 102 function, except it also takes a
 103 .Fa len
 104 argument, which is the maximal length of the expected string.
 105 .Pp
 106 The
 107 .Fn hash32_stre
 108 and
 109 .Fn hash32_strne
 110 functions are helper functions used by the kernel to hash pathname
 111 components.
 112 These functions have the additional termination condition
 113 of terminating when they find a character given by
 114 .Fa end
 115 in the string to be hashed.
 116 If the argument
 117 .Fa ep
 118 is not
 119 .Dv NULL ,
 120 it is set to the point in the buffer at which the hash function
 121 terminated hashing.
 122 .Pp
 123 The
 124 .Fn jenkins_hash
 125 function has same semantics as the
 126 .Fn hash32_buf ,
 127 but provides more advanced hashing algorithm with better distribution.
 128 .Pp
 129 The
 130 .Fn jenkins_hash32
 131 uses same hashing algorithm as the
 132 .Fn jenkins_hash
 133 function, but works only on
 134 .Ft uint32_t
 135 sized arrays, thus is simplier and faster.
 136 It accepts an array of
 137 .Ft uint32_t
 138 values in its first argument and size of this array in the second argument.
 139 .Pp
 140 The
 141 .Fn murmur3_32_hash
 142 and
 143 .Fn murmur3_32_hash32
 144 functions are similar to
 145 .Fn jenkins_hash
 146 and
 147 .Fn jenkins_hash32 ,
 148 but implement the 32-bit version of MurmurHash3.
 149 .Sh RETURN VALUES
 150 The
 151 .Fn hash32
 152 functions return a 32 bit hash value of the buffer or string.
 153 .Sh EXAMPLES
 154 .Bd -literal -offset indent
 155 LIST_HEAD(head, cache) *hashtbl = NULL;
 156 u_long mask = 0;
 157
 158 void
 159 sample_init(void)
 160 {
 161
 162         hashtbl = hashinit(numwanted, type, flags, &mask);
 163 }
 164
 165 void
 166 sample_use(char *str, int len)
 167 {
 168         uint32_t hash;
 169
 170         hash = hash32_str(str, HASHINIT);
 171         hash = hash32_buf(&len, sizeof(len), hash);
 172         hashtbl[hash & mask] = len;
 173 }
 174 .Ed
 175 .Sh SEE ALSO
 176 .Xr free 9 ,
 177 .Xr hashinit 9 ,
 178 .Xr malloc 9
 179 .Sh LIMITATIONS
 180 The
 181 .Fn hash32
 182 functions are only 32 bit functions.
 183 They will prove to give poor 64 bit performance, especially for the
 184 top 32 bits.
 185 At the current time, this is not seen as a great limitation, as these
 186 hash values are usually used to index into an array.
 187 Should these hash values be used for other means, this limitation should
 188 be revisited.
 189 .Sh HISTORY
 190 The
 191 .Nm
 192 functions first appeared in
 193 .Nx 1.6 .
 194 The current implementation of
 195 .Nm hash32
 196 functions was first committed to
 197 .Ox 3.2 ,
 198 and later imported to
 199 .Fx 6.1 .
 200 The
 201 .Nm jenkins_hash
 202 functions were added in
 203 .Fx 10.0 .
 204 The
 205 .Nm murmur3_32_hash
 206 functions were added in
 207 .Fx 10.1 .
 208 .Sh AUTHORS
 209 The
 210 .Nm hash32
 211 functions were written by
 212 .An Tobias Weingartner .
 213 The
 214 .Nm jenkins_hash
 215 functions were written by
 216 .An Bob Jenkins .
 217 The
 218 .Nm murmur3_32_hash
 219 functions were written by
 220 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .