share/man/man9/hashinit.9

   1 .\"
   2 .\" Copyright (c) 2003, 2004 The DragonFly Project.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to The DragonFly Project
   5 .\" by Hiten Pandya <hmp@backplane.com>.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in
  15 .\"    the documentation and/or other materials provided with the
  16 .\"    distribution.
  17 .\" 3. Neither the name of The DragonFly Project nor the names of its
  18 .\"    contributors may be used to endorse or promote products derived
  19 .\"    from this software without specific, prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  24 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  25 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  26 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  27 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  28 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  29 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  30 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  31 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .Dd June 6, 2012
  35 .Dt HASHINIT 9
  36 .Os
  37 .Sh NAME
  38 .Nm hashinit ,
  39 .Nm hashinit_ext ,
  40 .Nm hashdestroy ,
  41 .Nm phashinit ,
  42 .Nm phashinit_ext
  43 .Nd generic hash table functions for the kernel
  44 .Sh SYNOPSIS
  45 .In sys/param.h
  46 .In sys/systm.h
  47 .In sys/malloc.h
  48 .Ft void *
  49 .Fn hashinit "int count" "struct malloc_type *type" "u_long *hashmask"
  50 .Ft void *
  51 .Fn hashinit_ext "int count" "size_t size" "struct malloc_type *type" "u_long *hashmask"
  52 .Ft void
  53 .Fn hashdestroy "void *hashtbl" "struct malloc_type *type" "u_long hashmask"
  54 .Ft void *
  55 .Fn phashinit "int count" "struct malloc_type *type" "u_long *nentries"
  56 .Ft void *
  57 .Fn phashinit_ext "int count" "size_t size" "struct malloc_type *type" "u_long *nentries"
  58 .Sh DESCRIPTION
  59 The kernel hash functions are used for creating a generic hash table.
  60 .Pp
  61 The
  62 .Fn hashinit
  63 function returns a pointer to a hash table which is sized a
  64 .Dq "power of two"
  65 greater or equal to the element
  66 .Fa count
  67 requested.
  68 The masking value is stored in
  69 .Fa hashmask .
  70 .Pp
  71 The
  72 .Fn phashinit
  73 function returns a pointer to a prime number sized hash table.
  74 The element
  75 .Fa count
  76 requested is used to dictate an upper-bound for the size of the
  77 hash table.
  78 The final size of the hash table is stored by the function in
  79 .Fa nentries .
  80 .Pp
  81 The
  82 .Fa type
  83 argument to both of the above functions is used for keeping track
  84 of memory allocated for the hash table.
  85 See the
  86 .Xr kmalloc 9
  87 manual page for more information on memory statistics.
  88 .Pp
  89 The
  90 .Fn hashinit_ext
  91 and
  92 .Fn phashinit_ext
  93 functions are extended versions of
  94 .Fn hashinit
  95 and
  96 .Fn phashinit
  97 which take the
  98 .Fa size
  99 of the structure as an additional argument and will zero the array instead
 100 of assuming that it is an array of
 101 .Dv LIST_HEAD Ns s .
 102 .Pp
 103 The
 104 .Fn hashdestroy
 105 function frees the space occupied by the hash table pointed to by argument
 106 .Fa hashtbl .
 107 Argument
 108 .Fa type
 109 determines the malloc arena to use when freeing space.
 110 The argument
 111 .Fa hashmask
 112 should be the bit mask returned by the call to
 113 .Fn hashinit
 114 that allocated the hash table.
 115 The argument
 116 .Fa flags
 117 must be used with one of the following values.
 118 .Sh SEE ALSO
 119 .Xr tcp 4 ,
 120 .Xr udp 4 ,
 121 .Xr kmalloc 9 ,
 122 .Xr nlookup 9
 123 .Sh AUTHORS
 124 This manual page was written by
 125 .An Hiten Pandya Aq hmp@backplane.com .
 126 .Sh BUGS
 127 There is no
 128 .Fn phashdestroy
 129 function, and using
 130 .Fn hashdestroy
 131 to free a hash table allocated by
 132 .Fn phashinit
 133 usually has grave consequences.