Commit | Line | Data |
---|---|---|
463ee0b2 LW |
1 | .\" $Id: sdbm.3,v 1.2 90/12/13 13:00:57 oz Exp $ |
2 | .TH SDBM 3 "1 March 1990" | |
3 | .SH NAME | |
f4b9d880 | 4 | sdbm, sdbm_open, sdbm_prep, sdbm_close, sdbm_fetch, sdbm_store, sdbm_delete, sdbm_exists, sdbm_firstkey, sdbm_nextkey, sdbm_hash, sdbm_rdonly, sdbm_error, sdbm_clearerr, sdbm_dirfno, sdbm_pagfno \- data base subroutines |
463ee0b2 LW |
5 | .SH SYNOPSIS |
6 | .nf | |
7 | .ft B | |
8 | #include <sdbm.h> | |
9 | .sp | |
10 | typedef struct { | |
11 | char *dptr; | |
12 | int dsize; | |
13 | } datum; | |
14 | .sp | |
15 | datum nullitem = { NULL, 0 }; | |
16 | .sp | |
275cf23a | 17 | \s-1DBM\s0 *sdbm_open(char *file, int flags, int mode) |
463ee0b2 | 18 | .sp |
275cf23a | 19 | \s-1DBM\s0 *sdbm_prep(char *dirname, char *pagname, int flags, int mode) |
463ee0b2 | 20 | .sp |
275cf23a | 21 | void sdbm_close(\s-1DBM\s0 *db) |
463ee0b2 | 22 | .sp |
275cf23a | 23 | datum sdbm_fetch(\s-1DBM\s0 *db, key) |
463ee0b2 | 24 | .sp |
275cf23a | 25 | int sdbm_store(\s-1DBM\s0 *db, datum key, datum val, int flags) |
463ee0b2 | 26 | .sp |
275cf23a | 27 | int sdbm_delete(\s-1DBM\s0 *db, datum key) |
463ee0b2 | 28 | .sp |
f4b9d880 RA |
29 | int sdbm_exists(\s-1DBM\s0 *db, datum key) |
30 | .sp | |
275cf23a | 31 | datum sdbm_firstkey(\s-1DBM\s0 *db) |
463ee0b2 | 32 | .sp |
275cf23a | 33 | datum sdbm_nextkey(\s-1DBM\s0 *db) |
463ee0b2 | 34 | .sp |
275cf23a | 35 | long sdbm_hash(char *string, int len) |
463ee0b2 | 36 | .sp |
275cf23a HF |
37 | int sdbm_rdonly(\s-1DBM\s0 *db) |
38 | int sdbm_error(\s-1DBM\s0 *db) | |
39 | sdbm_clearerr(\s-1DBM\s0 *db) | |
40 | int sdbm_dirfno(\s-1DBM\s0 *db) | |
41 | int sdbm_pagfno(\s-1DBM\s0 *db) | |
463ee0b2 LW |
42 | .ft R |
43 | .fi | |
44 | .SH DESCRIPTION | |
45 | .IX "database library" sdbm "" "\fLsdbm\fR" | |
275cf23a HF |
46 | .IX sdbm_open "" "\fLsdbm_open\fR \(em open \fLsdbm\fR database" |
47 | .IX sdbm_prep "" "\fLsdbm_prep\fR \(em prepare \fLsdbm\fR database" | |
48 | .IX sdbm_close "" "\fLsdbm_close\fR \(em close \fLsdbm\fR routine" | |
49 | .IX sdbm_fetch "" "\fLsdbm_fetch\fR \(em fetch \fLsdbm\fR database data" | |
50 | .IX sdbm_store "" "\fLsdbm_store\fR \(em add data to \fLsdbm\fR database" | |
51 | .IX sdbm_delete "" "\fLsdbm_delete\fR \(em remove data from \fLsdbm\fR database" | |
f4b9d880 | 52 | .IX sdbm_exists "" "\fLsdbm_exists\fR \(em test \fLsdbm\fR key existence" |
275cf23a HF |
53 | .IX sdbm_firstkey "" "\fLsdbm_firstkey\fR \(em access \fLsdbm\fR database" |
54 | .IX sdbm_nextkey "" "\fLsdbm_nextkey\fR \(em access \fLsdbm\fR database" | |
55 | .IX sdbm_hash "" "\fLsdbm_hash\fR \(em string hash for \fLsdbm\fR database" | |
56 | .IX sdbm_rdonly "" "\fLsdbm_rdonly\fR \(em return \fLsdbm\fR database read-only mode" | |
57 | .IX sdbm_error "" "\fLsdbm_error\fR \(em return \fLsdbm\fR database error condition" | |
58 | .IX sdbm_clearerr "" "\fLsdbm_clearerr\fR \(em clear \fLsdbm\fR database error condition" | |
59 | .IX sdbm_dirfno "" "\fLsdbm_dirfno\fR \(em return \fLsdbm\fR database bitmap file descriptor" | |
60 | .IX sdbm_pagfno "" "\fLsdbm_pagfno\fR \(em return \fLsdbm\fR database data file descriptor" | |
61 | .IX "database functions \(em \fLsdbm\fR" sdbm_open "" \fLsdbm_open\fP | |
62 | .IX "database functions \(em \fLsdbm\fR" sdbm_prep "" \fLsdbm_prep\fP | |
63 | .IX "database functions \(em \fLsdbm\fR" sdbm_close "" \fLsdbm_close\fP | |
64 | .IX "database functions \(em \fLsdbm\fR" sdbm_fetch "" \fLsdbm_fetch\fP | |
65 | .IX "database functions \(em \fLsdbm\fR" sdbm_store "" \fLsdbm_store\fP | |
66 | .IX "database functions \(em \fLsdbm\fR" sdbm_delete "" \fLsdbm_delete\fP | |
67 | .IX "database functions \(em \fLsdbm\fR" sdbm_firstkey "" \fLsdbm_firstkey\fP | |
68 | .IX "database functions \(em \fLsdbm\fR" sdbm_nextkey "" \fLsdbm_nextkey\fP | |
69 | .IX "database functions \(em \fLsdbm\fR" sdbm_rdonly "" \fLsdbm_rdonly\fP | |
70 | .IX "database functions \(em \fLsdbm\fR" sdbm_error "" \fLsdbm_error\fP | |
71 | .IX "database functions \(em \fLsdbm\fR" sdbm_clearerr "" \fLsdbm_clearerr\fP | |
72 | .IX "database functions \(em \fLsdbm\fR" sdbm_dirfno "" \fLsdbm_dirfno\fP | |
73 | .IX "database functions \(em \fLsdbm\fR" sdbm_pagfno "" \fLsdbm_pagfno\fP | |
463ee0b2 LW |
74 | .LP |
75 | This package allows an application to maintain a mapping of <key,value> pairs | |
76 | in disk files. This is not to be considered a real database system, but is | |
77 | still useful in many simple applications built around fast retrieval of a data | |
78 | value from a key. This implementation uses an external hashing scheme, | |
79 | called Dynamic Hashing, as described by Per-Aake Larson in BIT 18 (1978) pp. | |
80 | 184-201. Retrieval of any item usually requires a single disk access. | |
81 | The application interface is compatible with the | |
82 | .IR ndbm (3) | |
83 | library. | |
84 | .LP | |
85 | An | |
86 | .B sdbm | |
87 | database is kept in two files usually given the extensions | |
88 | .B \.dir | |
89 | and | |
90 | .BR \.pag . | |
91 | The | |
92 | .B \.dir | |
93 | file contains a bitmap representing a forest of binary hash trees, the leaves | |
94 | of which indicate data pages in the | |
95 | .B \.pag | |
96 | file. | |
97 | .LP | |
98 | The application interface uses the | |
99 | .B datum | |
100 | structure to describe both | |
101 | .I keys | |
102 | and | |
103 | .IR value s. | |
104 | A | |
105 | .B datum | |
106 | specifies a byte sequence of | |
107 | .I dsize | |
108 | size pointed to by | |
109 | .IR dptr . | |
110 | If you use | |
111 | .SM ASCII | |
112 | strings as | |
113 | .IR key s | |
114 | or | |
115 | .IR value s, | |
116 | then you must decide whether or not to include the terminating | |
117 | .SM NUL | |
118 | byte which sometimes defines strings. Including it will require larger | |
119 | database files, but it will be possible to get sensible output from a | |
120 | .IR strings (1) | |
121 | command applied to the data file. | |
122 | .LP | |
123 | In order to allow a process using this package to manipulate multiple | |
124 | databases, the applications interface always requires a | |
125 | .IR handle , | |
126 | a | |
127 | .BR "DBM *" , | |
128 | to identify the database to be manipulated. Such a handle can be obtained | |
129 | from the only routines that do not require it, namely | |
275cf23a | 130 | .BR sdbm_open (\|) |
463ee0b2 | 131 | or |
275cf23a | 132 | .BR sdbm_prep (\|). |
463ee0b2 LW |
133 | Either of these will open or create the two necessary files. The |
134 | difference is that the latter allows explicitly naming the bitmap and data | |
135 | files whereas | |
275cf23a | 136 | .BR sdbm_open (\|) |
463ee0b2 | 137 | will take a base file name and call |
275cf23a | 138 | .BR sdbm_prep (\|) |
463ee0b2 LW |
139 | with the default extensions. |
140 | The | |
141 | .I flags | |
142 | and | |
143 | .I mode | |
144 | parameters are the same as for | |
145 | .BR open (2). | |
146 | .LP | |
147 | To free the resources occupied while a database handle is active, call | |
275cf23a | 148 | .BR sdbm_close (\|). |
463ee0b2 LW |
149 | .LP |
150 | Given a handle, one can retrieve data associated with a key by using the | |
275cf23a | 151 | .BR sdbm_fetch (\|) |
463ee0b2 | 152 | routine, and associate data with a key by using the |
275cf23a | 153 | .BR sdbm_store (\|) |
463ee0b2 | 154 | routine. |
f4b9d880 RA |
155 | .BR sdbm_exists (\|) |
156 | will say whether a given key exists in the database. | |
463ee0b2 LW |
157 | .LP |
158 | The values of the | |
159 | .I flags | |
160 | parameter for | |
275cf23a | 161 | .BR sdbm_store (\|) |
463ee0b2 LW |
162 | can be either |
163 | .BR \s-1DBM_INSERT\s0 , | |
164 | which will not change an existing entry with the same key, or | |
165 | .BR \s-1DBM_REPLACE\s0 , | |
166 | which will replace an existing entry with the same key. | |
167 | Keys are unique within the database. | |
168 | .LP | |
169 | To delete a key and its associated value use the | |
275cf23a | 170 | .BR sdbm_delete (\|) |
463ee0b2 LW |
171 | routine. |
172 | .LP | |
173 | To retrieve every key in the database, use a loop like: | |
174 | .sp | |
175 | .nf | |
176 | .ft B | |
275cf23a | 177 | for (key = sdbm_firstkey(db); key.dptr != NULL; key = sdbm_nextkey(db)) |
463ee0b2 LW |
178 | ; |
179 | .ft R | |
180 | .fi | |
181 | .LP | |
182 | The order of retrieval is unspecified. | |
183 | .LP | |
184 | If you determine that the performance of the database is inadequate or | |
185 | you notice clustering or other effects that may be due to the hashing | |
186 | algorithm used by this package, you can override it by supplying your | |
187 | own | |
275cf23a | 188 | .BR sdbm_hash (\|) |
b7b1e41b | 189 | routine. Doing so will make the database unintelligible to any other |
463ee0b2 LW |
190 | applications that do not use your specialized hash function. |
191 | .sp | |
192 | .LP | |
193 | The following macros are defined in the header file: | |
194 | .IP | |
275cf23a | 195 | .BR sdbm_rdonly (\|) |
463ee0b2 LW |
196 | returns true if the database has been opened read\-only. |
197 | .IP | |
275cf23a | 198 | .BR sdbm_error (\|) |
463ee0b2 LW |
199 | returns true if an I/O error has occurred. |
200 | .IP | |
275cf23a | 201 | .BR sdbm_clearerr (\|) |
463ee0b2 LW |
202 | allows you to clear the error flag if you think you know what the error |
203 | was and insist on ignoring it. | |
204 | .IP | |
275cf23a | 205 | .BR sdbm_dirfno (\|) |
463ee0b2 LW |
206 | returns the file descriptor associated with the bitmap file. |
207 | .IP | |
275cf23a | 208 | .BR sdbm_pagfno (\|) |
463ee0b2 LW |
209 | returns the file descriptor associated with the data file. |
210 | .SH SEE ALSO | |
211 | .IR open (2). | |
212 | .SH DIAGNOSTICS | |
213 | Functions that return a | |
214 | .B "DBM *" | |
215 | handle will use | |
216 | .SM NULL | |
217 | to indicate an error. | |
218 | Functions that return an | |
219 | .B int | |
220 | will use \-1 to indicate an error. The normal return value in that case is 0. | |
221 | Functions that return a | |
222 | .B datum | |
223 | will return | |
224 | .B nullitem | |
225 | to indicate an error. | |
226 | .LP | |
227 | As a special case of | |
275cf23a | 228 | .BR sdbm_store (\|), |
463ee0b2 LW |
229 | if it is called with the |
230 | .B \s-1DBM_INSERT\s0 | |
231 | flag and the key already exists in the database, the return value will be 1. | |
232 | .LP | |
233 | In general, if a function parameter is invalid, | |
234 | .B errno | |
235 | will be set to | |
236 | .BR \s-1EINVAL\s0 . | |
237 | If a write operation is requested on a read-only database, | |
238 | .B errno | |
239 | will be set to | |
240 | .BR \s-1ENOPERM\s0 . | |
241 | If a memory allocation (using | |
242 | .IR malloc (3)) | |
243 | failed, | |
244 | .B errno | |
245 | will be set to | |
246 | .BR \s-1ENOMEM\s0 . | |
247 | For I/O operation failures | |
248 | .B errno | |
249 | will contain the value set by the relevant failed system call, either | |
250 | .IR read (2), | |
251 | .IR write (2), | |
252 | or | |
253 | .IR lseek (2). | |
254 | .SH AUTHOR | |
255 | .IP "Ozan S. Yigit" (oz@nexus.yorku.ca) | |
256 | .SH BUGS | |
257 | The sum of key and value data sizes must not exceed | |
258 | .B \s-1PAIRMAX\s0 | |
259 | (1008 bytes). | |
260 | .LP | |
261 | The sum of the key and value data sizes where several keys hash to the | |
262 | same value must fit within one bitmap page. | |
263 | .LP | |
264 | The | |
265 | .B \.pag | |
266 | file will contain holes, so its apparent size is larger than its contents. | |
267 | When copied through the filesystem the holes will be filled. | |
268 | .LP | |
269 | The contents of | |
270 | .B datum | |
271 | values returned are in volatile storage. If you want to retain the values | |
272 | pointed to, you must copy them immediately before another call to this package. | |
273 | .LP | |
274 | The only safe way for multiple processes to (read and) update a database at | |
275 | the same time, is to implement a private locking scheme outside this package | |
276 | and open and close the database between lock acquisitions. It is safe for | |
277 | multiple processes to concurrently access a database read-only. | |
278 | .SH APPLICATIONS PORTABILITY | |
279 | For complete source code compatibility with the Berkeley Unix | |
280 | .IR ndbm (3) | |
281 | library, the | |
282 | .B sdbm.h | |
283 | header file should be installed in | |
284 | .BR /usr/include/ndbm.h . | |
285 | .LP | |
286 | The | |
287 | .B nullitem | |
288 | data item, and the | |
275cf23a HF |
289 | .BR sdbm_prep (\|), |
290 | .BR sdbm_hash (\|), | |
291 | .BR sdbm_rdonly (\|), | |
292 | .BR sdbm_dirfno (\|), | |
463ee0b2 | 293 | and |
275cf23a | 294 | .BR sdbm_pagfno (\|) |
463ee0b2 | 295 | functions are unique to this package. |