| 1 |
.\" Copyright 1990-1993, The Regents of the University of California. |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: BSD-4-Clause-UC |
| 5 |
.\" |
| 6 |
.TH hash 3 2025-09-21 "Linux man-pages 6.18" |
| 7 |
.UC 7 |
| 8 |
.SH NAME |
| 9 |
hash \- hash database access method |
| 10 |
.SH LIBRARY |
| 11 |
Standard C library |
| 12 |
.RI ( libc ,\~ \-lc ) |
| 13 |
.SH SYNOPSIS |
| 14 |
.nf |
| 15 |
.ft B |
| 16 |
#include <sys/types.h> |
| 17 |
#include <db.h> |
| 18 |
.ft R |
| 19 |
.fi |
| 20 |
.SH DESCRIPTION |
| 21 |
.IR "Note well" : |
| 22 |
This page documents interfaces provided up until glibc 2.1. |
| 23 |
Since glibc 2.2, glibc no longer provides these interfaces. |
| 24 |
Probably, you are looking for the APIs provided by the |
| 25 |
.I libdb |
| 26 |
library instead. |
| 27 |
.P |
| 28 |
The routine |
| 29 |
.BR dbopen (3) |
| 30 |
is the library interface to database files. |
| 31 |
One of the supported file formats is hash files. |
| 32 |
The general description of the database access methods is in |
| 33 |
.BR dbopen (3), |
| 34 |
this manual page describes only the hash-specific information. |
| 35 |
.P |
| 36 |
The hash data structure is an extensible, dynamic hashing scheme. |
| 37 |
.P |
| 38 |
The access-method-specific data structure provided to |
| 39 |
.BR dbopen (3) |
| 40 |
is defined in the |
| 41 |
.I <db.h> |
| 42 |
include file as follows: |
| 43 |
.P |
| 44 |
.in +4n |
| 45 |
.EX |
| 46 |
typedef struct { |
| 47 |
unsigned int bsize; |
| 48 |
unsigned int ffactor; |
| 49 |
unsigned int nelem; |
| 50 |
unsigned int cachesize; |
| 51 |
uint32_t (*hash)(const void *, size_t); |
| 52 |
int lorder; |
| 53 |
} HASHINFO; |
| 54 |
.EE |
| 55 |
.in |
| 56 |
.P |
| 57 |
The elements of this structure are as follows: |
| 58 |
.TP 10 |
| 59 |
.I bsize |
| 60 |
defines the hash table bucket size, and is, by default, 256 bytes. |
| 61 |
It may be preferable to increase the page size for disk-resident tables |
| 62 |
and tables with large data items. |
| 63 |
.TP |
| 64 |
.I ffactor |
| 65 |
indicates a desired density within the hash table. |
| 66 |
It is an approximation of the number of keys allowed to accumulate in any |
| 67 |
one bucket, determining when the hash table grows or shrinks. |
| 68 |
The default value is 8. |
| 69 |
.TP |
| 70 |
.I nelem |
| 71 |
is an estimate of the final size of the hash table. |
| 72 |
If not set or set too low, hash tables will expand gracefully as keys |
| 73 |
are entered, although a slight performance degradation may be noticed. |
| 74 |
The default value is 1. |
| 75 |
.TP |
| 76 |
.I cachesize |
| 77 |
is the suggested maximum size, in bytes, of the memory cache. |
| 78 |
This value is |
| 79 |
.IR "only advisory" , |
| 80 |
and the access method will allocate more memory rather than fail. |
| 81 |
.TP |
| 82 |
.I hash |
| 83 |
is a user-defined hash function. |
| 84 |
Since no hash function performs equally well on all possible data, the |
| 85 |
user may find that the built-in hash function does poorly on a particular |
| 86 |
data set. |
| 87 |
A user-specified hash functions must take two arguments (a pointer to a byte |
| 88 |
string and a length) and return a 32-bit quantity to be used as the hash |
| 89 |
value. |
| 90 |
.TP |
| 91 |
.I lorder |
| 92 |
is the byte order for integers in the stored database metadata. |
| 93 |
The number should represent the order as an integer; |
| 94 |
for example, |
| 95 |
big endian order would be the number 4,321. |
| 96 |
If |
| 97 |
.I lorder |
| 98 |
is 0 (no order is specified), |
| 99 |
the current host order is used. |
| 100 |
If the file already exists, |
| 101 |
the specified value is ignored |
| 102 |
and the value specified when the tree was created is used. |
| 103 |
.P |
| 104 |
If the file already exists (and the |
| 105 |
.B O_TRUNC |
| 106 |
flag is not specified), the |
| 107 |
values specified for |
| 108 |
.IR bsize , |
| 109 |
.IR ffactor , |
| 110 |
.IR lorder , |
| 111 |
and |
| 112 |
.I nelem |
| 113 |
are |
| 114 |
ignored and the values specified when the tree was created are used. |
| 115 |
.P |
| 116 |
If a hash function is specified, |
| 117 |
.I hash_open |
| 118 |
attempts to determine if the hash function specified is the same as |
| 119 |
the one with which the database was created, and fails if it is not. |
| 120 |
.P |
| 121 |
Backward-compatible interfaces to the routines described in |
| 122 |
.BR dbm (3), |
| 123 |
and |
| 124 |
.BR ndbm (3) |
| 125 |
are provided, however these interfaces are not compatible with |
| 126 |
previous file formats. |
| 127 |
.SH ERRORS |
| 128 |
The |
| 129 |
.I hash |
| 130 |
access method routines may fail and set |
| 131 |
.I errno |
| 132 |
for any of the errors specified for the library routine |
| 133 |
.BR dbopen (3). |
| 134 |
.SH BUGS |
| 135 |
Only big and little endian byte order are supported. |
| 136 |
.SH SEE ALSO |
| 137 |
.BR btree (3), |
| 138 |
.BR dbopen (3), |
| 139 |
.BR mpool (3), |
| 140 |
.BR recno (3) |
| 141 |
.P |
| 142 |
.IR "Dynamic Hash Tables" , |
| 143 |
Per-Ake Larson, Communications of the ACM, April 1988. |
| 144 |
.P |
| 145 |
.IR "A New Hash Package for UNIX" , |
| 146 |
Margo Seltzer, USENIX Proceedings, Winter 1991. |