Add a manual page for hashinit(9), hashdestroy(9) and phashinit(9).
Reviewed by: ru
This commit is contained in:
jkoshy
parent
50bf852114
commit
9b22f35761
@ -103,6 +103,7 @@ MAN= accept_filter.9 \
|
||||
g_provider_by_name.9 \
|
||||
groupmember.9 \
|
||||
g_wither_geom.9 \
|
||||
hashinit.9 \
|
||||
hexdump.9 \
|
||||
ieee80211.9 \
|
||||
ieee80211_crypto.9 \
|
||||
@ -467,6 +468,8 @@ MLINKS+=g_geom.9 g_destroy_geom.9 \
|
||||
MLINKS+=g_provider.9 g_destroy_provider.9 \
|
||||
g_provider.9 g_error_provider.9 \
|
||||
g_provider.9 g_new_providerf.9
|
||||
MLINKS+=hashinit.9 hashdestroy.9 \
|
||||
hashinit.9 phashinit.9
|
||||
MLINKS+=ieee80211.9 ieee80211_attach.9 \
|
||||
ieee80211.9 ieee80211_chan2ieee.9 \
|
||||
ieee80211.9 ieee80211_chan2mode.9 \
|
||||
|
||||
150
share/man/man9/hashinit.9
Normal file
150
share/man/man9/hashinit.9
Normal file
@ -0,0 +1,150 @@
|
||||
.\"
|
||||
.\" Copyright (c) 2004 Joseph Koshy
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
|
||||
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
||||
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE
|
||||
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||||
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||||
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||||
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||||
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
.\" POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd October 10, 2004
|
||||
.Dt HASHINIT 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm hashinit , hashdestroy , phashinit
|
||||
.Nd manage kernel hash tables
|
||||
.Sh SYNOPSIS
|
||||
.In sys/malloc.h
|
||||
.In sys/systm.h
|
||||
.In sys/queue.h
|
||||
.Ft "void *"
|
||||
.Fn hashinit "int nelements" "struct malloc_type *type" "u_long *hashmask"
|
||||
.Ft void
|
||||
.Fn hashdestroy "void *hashtbl" "struct malloc_type *type" "u_long hashmask"
|
||||
.Ft "void *"
|
||||
.Fn phashinit "int nelements" "struct malloc_type *type" "u_long *nentries"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn hashinit
|
||||
and
|
||||
.Fn phashinit
|
||||
functions allocate space for hash tables of size given by the argument
|
||||
.Fa nelements .
|
||||
.Pp
|
||||
The
|
||||
.Fn hashinit
|
||||
function allocates hash tables that are sized to largest power of two
|
||||
less than or equal to argument
|
||||
.Fa nelements .
|
||||
The
|
||||
.Fn phashinit
|
||||
function allocates hash tables that are sized to the largest prime
|
||||
number less than or equal to argument
|
||||
.Fa nelements .
|
||||
Allocated hash tables are contiguous arrays of
|
||||
.Xr LIST_HEAD 3
|
||||
entries, allocated using
|
||||
.Xr malloc 9 ,
|
||||
and initialized using
|
||||
.Xr LIST_INIT 3 .
|
||||
The malloc arena to be used for allocation is pointed to by argument
|
||||
.Fa type .
|
||||
.Pp
|
||||
The
|
||||
.Fn hashdestroy
|
||||
function frees the space occupied by the hash table pointed to by argument
|
||||
.Fa hashtbl .
|
||||
Argument
|
||||
.Fa type
|
||||
determines the malloc arena to use when freeing space.
|
||||
The argument
|
||||
.Fa hashmask
|
||||
should be the bit mask returned by the call to
|
||||
.Fn hashinit
|
||||
that allocated the hash table.
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn hashinit
|
||||
function returns a pointer to an allocated hash table and sets the
|
||||
location pointed to by
|
||||
.Fa hashmask
|
||||
to the bit mask to be used for computing the correct slot in the
|
||||
hash table.
|
||||
.Pp
|
||||
The
|
||||
.Fn phashinit
|
||||
function returns a pointer to an allocated hash table and sets the
|
||||
location pointed to by
|
||||
.Fa nentries
|
||||
to the number of rows in the hash table.
|
||||
.Sh IMPLEMENTATION NOTES
|
||||
The largest prime hash value chosen by
|
||||
.Fn phashinit
|
||||
is 32749.
|
||||
.Sh EXAMPLES
|
||||
A typical example is shown below:
|
||||
.Bd -literal -offset indent
|
||||
\&...
|
||||
static LIST_HEAD(foo, foo) *footable;
|
||||
static u_long foomask;
|
||||
\&...
|
||||
footable = hashinit(32, M_FOO, &foomask);
|
||||
.Ed
|
||||
.Pp
|
||||
Here we allocate a hash table with 32 entries from the malloc arena
|
||||
pointed to by
|
||||
.Dv M_FOO .
|
||||
The mask for the allocated hash table is returned in
|
||||
.Va foomask .
|
||||
A subsequent call to
|
||||
.Fn hashdestroy
|
||||
uses the value in
|
||||
.Va foomask :
|
||||
.Bd -literal -offset indent
|
||||
\&...
|
||||
hashdestroy(footable, M_FOO, foomask);
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr LIST_HEAD 3 ,
|
||||
.Xr malloc 9
|
||||
.Sh DIAGNOSTICS
|
||||
The
|
||||
.Fn hashinit
|
||||
and
|
||||
.Fn phashinit
|
||||
functions will panic if argument
|
||||
.Fa nelements
|
||||
is less than or equal to zero.
|
||||
.Pp
|
||||
The
|
||||
.Fn hashdestroy
|
||||
function will panic if the hash table
|
||||
pointed to by
|
||||
.Fa hashtbl
|
||||
is not empty.
|
||||
.Sh BUGS
|
||||
There is no
|
||||
.Fn phashdestroy
|
||||
function, and using
|
||||
.Fn hashdestroy
|
||||
to free a hash table allocated by
|
||||
.Fn phashinit
|
||||
usually has grave consequences.
|
||||
Loading…
x
Reference in New Issue
Block a user