diff options
Diffstat (limited to 'man/man3/hash.3')
| -rw-r--r-- | man/man3/hash.3 | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/man/man3/hash.3 b/man/man3/hash.3 new file mode 100644 index 000000000..b40623a47 --- /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 (date) "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. |