Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 145 insertions, 0 deletions

diff --git a/man/man3/hash.3 b/man/man3/hash.3
new file mode 100644
index 0000000..4ccbaca
--- /dev/null
+++ b/man/man3/hash.3
@@ -0,0 +1,145 @@
+.\" Copyright (c) 1990, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\"	@(#)hash.3	8.6 (Berkeley) 8/18/94
+.\"
+.TH hash 3 2024-05-02 "Linux man-pages (unreleased)"
+.UC 7
+.SH NAME
+hash \- hash database access method
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.ft B
+#include <sys/types.h>
+#include <db.h>
+.ft R
+.fi
+.SH DESCRIPTION
+.IR "Note well" :
+This page documents interfaces provided up until glibc 2.1.
+Since glibc 2.2, glibc no longer provides these interfaces.
+Probably, you are looking for the APIs provided by the
+.I libdb
+library instead.
+.P
+The routine
+.BR dbopen (3)
+is the library interface to database files.
+One of the supported file formats is hash files.
+The general description of the database access methods is in
+.BR dbopen (3),
+this manual page describes only the hash-specific information.
+.P
+The hash data structure is an extensible, dynamic hashing scheme.
+.P
+The access-method-specific data structure provided to
+.BR dbopen (3)
+is defined in the
+.I <db.h>
+include file as follows:
+.P
+.in +4n
+.EX
+typedef struct {
+    unsigned int       bsize;
+    unsigned int       ffactor;
+    unsigned int       nelem;
+    unsigned int       cachesize;
+    uint32_t         (*hash)(const void *, size_t);
+    int         lorder;
+} HASHINFO;
+.EE
+.in
+.P
+The elements of this structure are as follows:
+.TP 10
+.I bsize
+defines the hash table bucket size, and is, by default, 256 bytes.
+It may be preferable to increase the page size for disk-resident tables
+and tables with large data items.
+.TP
+.I ffactor
+indicates a desired density within the hash table.
+It is an approximation of the number of keys allowed to accumulate in any
+one bucket, determining when the hash table grows or shrinks.
+The default value is 8.
+.TP
+.I nelem
+is an estimate of the final size of the hash table.
+If not set or set too low, hash tables will expand gracefully as keys
+are entered, although a slight performance degradation may be noticed.
+The default value is 1.
+.TP
+.I cachesize
+is the suggested maximum size, in bytes, of the memory cache.
+This value is
+.IR "only advisory" ,
+and the access method will allocate more memory rather than fail.
+.TP
+.I hash
+is a user-defined hash function.
+Since no hash function performs equally well on all possible data, the
+user may find that the built-in hash function does poorly on a particular
+data set.
+A user-specified hash functions must take two arguments (a pointer to a byte
+string and a length) and return a 32-bit quantity to be used as the hash
+value.
+.TP
+.I lorder
+is the byte order for integers in the stored database metadata.
+The number should represent the order as an integer; for example,
+big endian order would be the number 4,321.
+If
+.I lorder
+is 0 (no order is specified), the current host order is used.
+If the file already exists, the specified value is ignored and the
+value specified when the tree was created is used.
+.P
+If the file already exists (and the
+.B O_TRUNC
+flag is not specified), the
+values specified for
+.IR bsize ,
+.IR ffactor ,
+.IR lorder ,
+and
+.I nelem
+are
+ignored and the values specified when the tree was created are used.
+.P
+If a hash function is specified,
+.I hash_open
+attempts to determine if the hash function specified is the same as
+the one with which the database was created, and fails if it is not.
+.P
+Backward-compatible interfaces to the routines described in
+.BR dbm (3),
+and
+.BR ndbm (3)
+are provided, however these interfaces are not compatible with
+previous file formats.
+.SH ERRORS
+The
+.I hash
+access method routines may fail and set
+.I errno
+for any of the errors specified for the library routine
+.BR dbopen (3).
+.SH BUGS
+Only big and little endian byte order are supported.
+.SH SEE ALSO
+.BR btree (3),
+.BR dbopen (3),
+.BR mpool (3),
+.BR recno (3)
+.P
+.IR "Dynamic Hash Tables" ,
+Per-Ake Larson, Communications of the ACM, April 1988.
+.P
+.IR "A New Hash Package for UNIX" ,
+Margo Seltzer, USENIX Proceedings, Winter 1991.