| .\" Copyright (c) 1990, 1993 |
| .\" The Regents of the University of California. All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" 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 University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University 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 REGENTS 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 REGENTS 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)hash.3 8.6 (Berkeley) 8/18/94 |
| .\" |
| .TH HASH 3 2012-04-23 "" "Linux Programmer's Manual" |
| .UC 7 |
| .SH NAME |
| hash \- hash database access method |
| .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 in glibc up until version 2.1. |
| Since version 2.2, glibc no longer provides these interfaces. |
| Probably, you are looking for the APIs provided by the |
| .I libdb |
| library instead. |
| |
| 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. |
| .PP |
| The hash data structure is an extensible, dynamic hashing scheme. |
| .PP |
| The access-method-specific data structure provided to |
| .BR dbopen (3) |
| is defined in the |
| .I <db.h> |
| include file as follows: |
| .in +4n |
| .nf |
| |
| typedef struct { |
| unsigned int bsize; |
| unsigned int ffactor; |
| unsigned int nelem; |
| unsigned int cachesize; |
| uint32_t (*hash)(const void *, size_t); |
| int lorder; |
| } HASHINFO; |
| .fi |
| .in |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| If a hash function is specified, |
| .I hash_open |
| will attempt to determine if the hash function specified is the same as |
| the one with which the database was created, and will fail if it is not. |
| .PP |
| 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) |
| |
| .IR "Dynamic Hash Tables" , |
| Per-Ake Larson, Communications of the ACM, April 1988. |
| |
| .IR "A New Hash Package for UNIX" , |
| Margo Seltzer, USENIX Proceedings, Winter 1991. |