share/man/man9/hash.9

   1 .\"     $NetBSD: hash.9,v 1.3 2003/04/16 13:35:28 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Luke Mewburn of Wasabi Systems, Inc.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd December 5, 2001
  31 .Dt HASH 9
  32 .Os
  33 .Sh NAME
  34 .Nm hash ,
  35 .Nm hash32_buf ,
  36 .Nm hash32_str ,
  37 .Nm hash32_strn
  38 .Nd kernel hash functions
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In sys/hash.h
  42 .Ft uint32_t
  43 .Fn hash32_buf "const void *buf" "size_t len" "uint32_t ihash"
  44 .Ft uint32_t
  45 .Fn hash32_str "const void *buf" "uint32_t ihash"
  46 .Ft uint32_t
  47 .Fn hash32_strn "const void *buf" "size_t len" "uint32_t ihash"
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 functions returns a hash of the given buffer.
  52 .Pp
  53 The
  54 .Fn hash32_buf
  55 function returns a 32 bit hash of
  56 .Fa buf ,
  57 which is
  58 .Fa len
  59 bytes long,
  60 seeded with an initial hash of
  61 .Fa ihash
  62 (which is usually
  63 .Dv HASH32_BUF_INIT ) .
  64 This function may use a different algorithm to
  65 .Fn hash32_str
  66 and
  67 .Fn hash32_strn .
  68 .Pp
  69 The
  70 .Fn hash32_str
  71 function returns a 32 bit hash of
  72 .Fa buf ,
  73 which is
  74 a
  75 .Dv NUL
  76 terminated
  77 .Tn ASCII
  78 string,
  79 seeded with an initial hash of
  80 .Fa ihash
  81 (which is usually
  82 .Dv HASH32_STR_INIT ) .
  83 This function must use the same algorithm as
  84 .Fn hash32_strn ,
  85 so that the same data returns the same hash.
  86 .Pp
  87 The
  88 .Fn hash32_strn
  89 function returns a 32 bit hash of
  90 .Fa buf ,
  91 which is
  92 a
  93 .Dv NUL
  94 terminated
  95 .Tn ASCII
  96 string,
  97 up to a maximum of
  98 .Fa len
  99 bytes,
 100 seeded with an initial hash of
 101 .Fa ihash
 102 (which is usually
 103 .Dv HASH32_STR_INIT ) .
 104 This function must use the same algorithm as
 105 .Fn hash32_str ,
 106 so that the same data returns the same hash.
 107 .Pp
 108 The
 109 .Fa ihash
 110 parameter is provided to allow for incremental hashing by allowing
 111 successive calls to use a previous hash value.
 112 .Sh RETURN VALUES
 113 The
 114 .Fa hash32_*
 115 functions return a 32 bit hash of the provided buffer.
 116 .Sh HISTORY
 117 The kernel hashing API first appeared in
 118 .Nx 1.6 .