[src/trunk]: src/share/man/man9 add hash(9)

[lukem <lukem%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/dfd7dd341b0d
branches:  trunk
changeset: 518765:dfd7dd341b0d
user:      lukem <lukem%NetBSD.org@localhost>
date:      Wed Dec 05 07:31:24 2001 +0000

description:
add hash(9)

diffstat:

 share/man/man9/Makefile |    6 +-
 share/man/man9/hash.9   |  125 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 129 insertions(+), 2 deletions(-)

diffs (156 lines):

diff -r 889362ff2830 -r dfd7dd341b0d share/man/man9/Makefile
--- a/share/man/man9/Makefile   Wed Dec 05 06:57:35 2001 +0000
+++ b/share/man/man9/Makefile   Wed Dec 05 07:31:24 2001 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.99 2001/12/02 02:26:28 gmcgarry Exp $
+#       $NetBSD: Makefile,v 1.100 2001/12/05 07:31:24 lukem Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -8,7 +8,8 @@
        callout.9 cardbus.9 cnmagic.9 config.9 cons.9 copy.9 cpu_reboot.9 \
        ctxsw.9 disk.9 disklabel.9 \
        dopowerhooks.9 doshutdownhooks.9 driver.9 ethersubr.9 evcnt.9 \
-       extent.9 fetch.9 fork1.9 hardclock.9 humanize_number.9 hz.9 \
+       extent.9 fetch.9 fork1.9 \
+       hash.9 hardclock.9 humanize_number.9 hz.9 \
        in4_cksum.9 inittodr.9 intro.9 ioasic.9 ioctl.9 isa.9 isapnp.9 \
        itimerfix.9 \
        kprintf.9 kthread.9 linedisc.9 lock.9 log.9 malloc.9 mbuf.9 \
@@ -125,6 +126,7 @@
        extent.9 extent_print.9
 MLINKS+=fetch.9 fubyte.9 fetch.9 fuibyte.9 fetch.9 fusword.9 \
        fetch.9 fuswintr.9 fetch.9 fuword.9 fetch.9 fuiword.9
+MLINKS+=hash.9 hash32_buf.9 hash.9 hash32_str.9 hash.9 hash32_strn.9
 MLINKS+=humanize_number.9 format_bytes.9
 MLINKS+=in4_cksum.9 in_cksum.9 \
        in4_cksum.9 in6_cksum.9
diff -r 889362ff2830 -r dfd7dd341b0d share/man/man9/hash.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/hash.9     Wed Dec 05 07:31:24 2001 +0000
@@ -0,0 +1,125 @@
+.\"     $NetBSD: hash.9,v 1.1 2001/12/05 07:31:25 lukem Exp $
+.\"
+.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Luke Mewburn of Wasabi Systems, Inc.
+.\"
+.\" 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd December 5, 2001
+.Dt HASH 9
+.Os
+.Sh NAME
+.Nm hash ,
+.Nm hash32_buf ,
+.Nm hash32_str ,
+.Nm hash32_strn
+.Nd kernel hash functions
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/hash.h>
+.Ft uint32_t
+.Fn hash32_buf "const void *buf" "size_t len" "uint32_t ihash"
+.Ft uint32_t
+.Fn hash32_str "const void *buf" "uint32_t ihash"
+.Ft uint32_t
+.Fn hash32_strn "const void *buf" "size_t len" "uint32_t ihash"
+.Sh DESCRIPTION
+The
+.Nm
+functions returns a hash of the given buffer.
+.Pp
+The
+.Fn hash32_buf
+function returns a 32 bit hash of
+.Fa buf ,
+which is
+.Fa len
+bytes long,
+seeded with an initial hash of
+.Fa ihash
+(which is usually
+.Dv HASH32_BUF_INIT ) .
+This function may use a different algorithm to
+.Fn hash32_str
+and
+.Fn hash32_strn .
+.Pp
+The
+.Fn hash32_str
+function returns a 32 bit hash of
+.Fa buf ,
+which is
+a
+.Dv NUL
+terminated
+.Tn ASCII
+string,
+seeded with an initial hash of
+.Fa ihash
+(which is usually
+.Dv HASH32_STR_INIT ) .
+This function must use the same algorithm as
+.Fn hash32_strn ,
+so that the same data returns the same hash.
+.Pp
+The
+.Fn hash32_strn
+function returns a 32 bit hash of
+.Fa buf ,
+which is
+a
+.Dv NUL
+terminated
+.Tn ASCII
+string,
+up to a maximum of
+.Fa len
+bytes,
+seeded with an initial hash of
+.Fa ihash
+(which is usually
+.Dv HASH32_STR_INIT ) .
+This function must use the same algorithm as
+.Fn hash32_str ,
+so that the same data returns the same hash.
+.Pp
+The
+.Fa ihash
+parameter is provided to allow for incremental hashing by allowing
+successive calls to use a previous hash value.
+.Sh RETURN VALUES
+The
+.Fa hash32_*
+functions return a 32 bit hash of the provided buffer.
+.Sh HISTORY
+The kernel hashing API first appeared in
+.Nx 1.6 .