]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
3 | .\" | |
a9cd9cb7 | 4 | .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
fea681da MK |
5 | .\" Redistribution and use in source and binary forms, with or without |
6 | .\" modification, are permitted provided that the following conditions | |
7 | .\" are met: | |
8 | .\" 1. Redistributions of source code must retain the above copyright | |
9 | .\" notice, this list of conditions and the following disclaimer. | |
10 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer in the | |
12 | .\" documentation and/or other materials provided with the distribution. | |
13 | .\" 3. All advertising materials mentioning features or use of this software | |
14 | .\" must display the following acknowledgement: | |
15 | .\" This product includes software developed by the University of | |
16 | .\" California, Berkeley and its contributors. | |
17 | .\" 4. Neither the name of the University nor the names of its contributors | |
18 | .\" may be used to endorse or promote products derived from this software | |
19 | .\" without specific prior written permission. | |
20 | .\" | |
21 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
31 | .\" SUCH DAMAGE. | |
8c9302dc | 32 | .\" %%%LICENSE_END |
fea681da MK |
33 | .\" |
34 | .\" @(#)hash.3 8.6 (Berkeley) 8/18/94 | |
35 | .\" | |
4b8c67d9 | 36 | .TH HASH 3 2017-09-15 "" "Linux Programmer's Manual" |
fea681da MK |
37 | .UC 7 |
38 | .SH NAME | |
39 | hash \- hash database access method | |
40 | .SH SYNOPSIS | |
41 | .nf | |
42 | .ft B | |
43 | #include <sys/types.h> | |
44 | #include <db.h> | |
45 | .ft R | |
46 | .fi | |
47 | .SH DESCRIPTION | |
df21098d MK |
48 | .IR "Note well" : |
49 | This page documents interfaces provided in glibc up until version 2.1. | |
50 | Since version 2.2, glibc no longer provides these interfaces. | |
51 | Probably, you are looking for the APIs provided by the | |
52 | .I libdb | |
53 | library instead. | |
847e0d88 | 54 | .PP |
fea681da | 55 | The routine |
50963b36 | 56 | .BR dbopen (3) |
fea681da MK |
57 | is the library interface to database files. |
58 | One of the supported file formats is hash files. | |
59 | The general description of the database access methods is in | |
31e9a9ec | 60 | .BR dbopen (3), |
76c637e1 | 61 | this manual page describes only the hash-specific information. |
fea681da MK |
62 | .PP |
63 | The hash data structure is an extensible, dynamic hashing scheme. | |
64 | .PP | |
76c637e1 | 65 | The access-method-specific data structure provided to |
50963b36 | 66 | .BR dbopen (3) |
1082a910 MK |
67 | is defined in the |
68 | .I <db.h> | |
69 | include file as follows: | |
e646a1ba | 70 | .PP |
088a639b | 71 | .in +4n |
e646a1ba | 72 | .EX |
fea681da | 73 | typedef struct { |
aeb4b1fc MK |
74 | unsigned int bsize; |
75 | unsigned int ffactor; | |
76 | unsigned int nelem; | |
77 | unsigned int cachesize; | |
78 | uint32_t (*hash)(const void *, size_t); | |
4db2a2ab | 79 | int lorder; |
fea681da | 80 | } HASHINFO; |
b8302363 | 81 | .EE |
4db2a2ab | 82 | .in |
fea681da MK |
83 | .PP |
84 | The elements of this structure are as follows: | |
fe4d4c41 MK |
85 | .TP 10 |
86 | .I bsize | |
fea681da MK |
87 | defines the hash table bucket size, and is, by default, 256 bytes. |
88 | It may be preferable to increase the page size for disk-resident tables | |
89 | and tables with large data items. | |
90 | .TP | |
fe4d4c41 | 91 | .I ffactor |
fea681da MK |
92 | indicates a desired density within the hash table. |
93 | It is an approximation of the number of keys allowed to accumulate in any | |
94 | one bucket, determining when the hash table grows or shrinks. | |
95 | The default value is 8. | |
96 | .TP | |
fe4d4c41 | 97 | .I nelem |
fea681da MK |
98 | is an estimate of the final size of the hash table. |
99 | If not set or set too low, hash tables will expand gracefully as keys | |
100 | are entered, although a slight performance degradation may be noticed. | |
101 | The default value is 1. | |
102 | .TP | |
fe4d4c41 MK |
103 | .I cachesize |
104 | is the suggested maximum size, in bytes, of the memory cache. | |
fea681da | 105 | This value is |
fe4d4c41 MK |
106 | .IR "only advisory" , |
107 | and the access method will allocate more memory rather than fail. | |
fea681da | 108 | .TP |
fe4d4c41 | 109 | .I hash |
df3e4d6d | 110 | is a user-defined hash function. |
fea681da MK |
111 | Since no hash function performs equally well on all possible data, the |
112 | user may find that the built-in hash function does poorly on a particular | |
113 | data set. | |
fe4d4c41 | 114 | A user-specified hash functions must take two arguments (a pointer to a byte |
fea681da MK |
115 | string and a length) and return a 32-bit quantity to be used as the hash |
116 | value. | |
117 | .TP | |
fe4d4c41 MK |
118 | .I lorder |
119 | is the byte order for integers in the stored database metadata. | |
c13182ef | 120 | The number should represent the order as an integer; for example, |
fea681da MK |
121 | big endian order would be the number 4,321. |
122 | If | |
123 | .I lorder | |
16fe1737 | 124 | is 0 (no order is specified), the current host order is used. |
cfadad46 | 125 | If the file already exists, the specified value is ignored and the |
fea681da MK |
126 | value specified when the tree was created is used. |
127 | .PP | |
c8fe3fa2 MK |
128 | If the file already exists (and the |
129 | .B O_TRUNC | |
130 | flag is not specified), the | |
91163456 | 131 | values specified for |
fe4d4c41 MK |
132 | .IR bsize , |
133 | .IR ffactor , | |
134 | .IR lorder , | |
135 | and | |
136 | .I nelem | |
137 | are | |
fea681da MK |
138 | ignored and the values specified when the tree was created are used. |
139 | .PP | |
140 | If a hash function is specified, | |
141 | .I hash_open | |
a23d8efa MK |
142 | attempts to determine if the hash function specified is the same as |
143 | the one with which the database was created, and fails if it is not. | |
fea681da | 144 | .PP |
66d3a13b | 145 | Backward-compatible interfaces to the routines described in |
31e9a9ec | 146 | .BR dbm (3), |
fea681da | 147 | and |
31e9a9ec | 148 | .BR ndbm (3) |
fea681da MK |
149 | are provided, however these interfaces are not compatible with |
150 | previous file formats. | |
151 | .SH ERRORS | |
152 | The | |
153 | .I hash | |
154 | access method routines may fail and set | |
155 | .I errno | |
156 | for any of the errors specified for the library routine | |
31e9a9ec | 157 | .BR dbopen (3). |
e37e3282 | 158 | .SH BUGS |
fe4d4c41 | 159 | Only big and little endian byte order are supported. |
47297adb | 160 | .SH SEE ALSO |
31e9a9ec MK |
161 | .BR btree (3), |
162 | .BR dbopen (3), | |
163 | .BR mpool (3), | |
164 | .BR recno (3) | |
847e0d88 | 165 | .PP |
fea681da MK |
166 | .IR "Dynamic Hash Tables" , |
167 | Per-Ake Larson, Communications of the ACM, April 1988. | |
847e0d88 | 168 | .PP |
fea681da MK |
169 | .IR "A New Hash Package for UNIX" , |
170 | Margo Seltzer, USENIX Proceedings, Winter 1991. |