Import OpenBSD's manual page to the sys/sys/hash.c functions imported two
days earlier. Obtained from: OpenBSD
This commit is contained in:
andre
parent
b0ee391aa7
commit
4cc825f6d4
160
share/man/man9/hash.9
Normal file
160
share/man/man9/hash.9
Normal file
@ -0,0 +1,160 @@
|
||||
.\" Copyright (c) 2001 Tobias Weingartner
|
||||
.\" 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.
|
||||
.\" 3. The name of the author may not be used to endorse or promote products
|
||||
.\" derived from this software without specific prior written permission.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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.
|
||||
.\"
|
||||
.\" $OpenBSD: hash.9,v 1.5 2003/04/17 05:08:39 jmc Exp $
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd December 8, 2001
|
||||
.Dt HASH 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm hash
|
||||
.\" XXX - Should all these be .Nm as well?
|
||||
.\" .Nm hash32 ,
|
||||
.\" .Nm hash32_buf ,
|
||||
.\" .Nm hash32_str ,
|
||||
.\" .Nm hash32_strn ,
|
||||
.\" .Nm hash32_stre ,
|
||||
.\" .Nm hash32_strne
|
||||
.Nd general kernel hashing functions
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <sys/hash.h>
|
||||
.Ft uint32_t
|
||||
.Fn hash32_buf "void *buf" "size_t len" "uint32_t hash"
|
||||
.Ft uint32_t
|
||||
.Fn hash32_str "void *buf" "uint32_t hash"
|
||||
.Ft uint32_t
|
||||
.Fn hash32_strn "void *buf" "size_t len" "uint32_t hash"
|
||||
.Ft uint32_t
|
||||
.Fn hash32_stre "void *buf" "int end" "char **ep" "uint32_t hash"
|
||||
.Ft uint32_t
|
||||
.Fn hash32_strne "void *buf" "size_t len" "int end" "char **ep" "uint32_t hash"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn 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
|
||||
.Dv NUL
|
||||
terminated strings, as well as blocks of memory.
|
||||
.Pp
|
||||
The
|
||||
.Fn hash32_buf
|
||||
function is used as a general buffer hashing function.
|
||||
The argument
|
||||
.Fa buf
|
||||
is used to pass in the location, and
|
||||
.Fa len
|
||||
is the length of the buffer.
|
||||
The argument
|
||||
.Fa hash
|
||||
is used to extend an existing hash, or is passed the initial value
|
||||
.Dv HASHINIT
|
||||
to start a new hash.
|
||||
.Pp
|
||||
The
|
||||
.Fn hash32_str
|
||||
function is used to hash a
|
||||
.Dv NUL
|
||||
terminated string passed in
|
||||
.Fa buf
|
||||
with initial hash value given in
|
||||
.Fa hash .
|
||||
.Pp
|
||||
The
|
||||
.Fn hash32_strn
|
||||
function is like the
|
||||
.Fn hash32_str
|
||||
function, except it also takes a
|
||||
.Fa len
|
||||
argument, which is the maximal length of the expected string.
|
||||
.Pp
|
||||
The
|
||||
.Fn hash32_stre
|
||||
and
|
||||
.Fn 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
|
||||
.Fa end
|
||||
in the string to be hashed.
|
||||
If the argument
|
||||
.Fa ep
|
||||
is not
|
||||
.Dv NULL ,
|
||||
it is set to the point in the buffer at which the hash function
|
||||
terminated hashing.
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn hash32
|
||||
functions return a 32 bit hash value of the buffer or string.
|
||||
.Sh EXAMPLES
|
||||
.Bd -literal -offset indent
|
||||
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;
|
||||
}
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr free 9 ,
|
||||
.Xr hashinit 9 ,
|
||||
.Xr malloc 9
|
||||
.Sh LIMITATIONS
|
||||
The
|
||||
.Fn 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.
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm
|
||||
functions were first committed to
|
||||
.Nx 1.6 .
|
||||
The
|
||||
.Ox
|
||||
versions were written and massaged for
|
||||
.Ox 2.3
|
||||
by Tobias Weingartner,
|
||||
and finally committed for
|
||||
.Ox 3.2 .
|
||||
Loading…
Reference in New Issue
Block a user