1 .\" $Id: sdbm.3,v 1.2 90/12/13 13:00:57 oz Exp $
2 .TH SDBM 3 "1 March 1990"
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
15 datum nullitem = { NULL, 0 };
17 \s-1DBM\s0 *sdbm_open(char *file, int flags, int mode)
19 \s-1DBM\s0 *sdbm_prep(char *dirname, char *pagname, int flags, int mode)
21 void sdbm_close(\s-1DBM\s0 *db)
23 datum sdbm_fetch(\s-1DBM\s0 *db, key)
25 int sdbm_store(\s-1DBM\s0 *db, datum key, datum val, int flags)
27 int sdbm_delete(\s-1DBM\s0 *db, datum key)
29 int sdbm_exists(\s-1DBM\s0 *db, datum key)
31 datum sdbm_firstkey(\s-1DBM\s0 *db)
33 datum sdbm_nextkey(\s-1DBM\s0 *db)
35 long sdbm_hash(char *string, int len)
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)
45 .IX "database library" sdbm "" "\fLsdbm\fR"
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"
52 .IX sdbm_exists "" "\fLsdbm_exists\fR \(em test \fLsdbm\fR key existence"
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
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
87 database is kept in two files usually given the extensions
93 file contains a bitmap representing a forest of binary hash trees, the leaves
94 of which indicate data pages in the
98 The application interface uses the
100 structure to describe both
106 specifies a byte sequence of
116 then you must decide whether or not to include the terminating
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
121 command applied to the data file.
123 In order to allow a process using this package to manipulate multiple
124 databases, the applications interface always requires a
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
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
137 will take a base file name and call
139 with the default extensions.
144 parameters are the same as for
147 To free the resources occupied while a database handle is active, call
150 Given a handle, one can retrieve data associated with a key by using the
152 routine, and associate data with a key by using the
156 will say whether a given key exists in the database.
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.
169 To delete a key and its associated value use the
173 To retrieve every key in the database, use a loop like:
177 for (key = sdbm_firstkey(db); key.dptr != NULL; key = sdbm_nextkey(db))
182 The order of retrieval is unspecified.
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
189 routine. Doing so will make the database unintelligable to any other
190 applications that do not use your specialized hash function.
193 The following macros are defined in the header file:
196 returns true if the database has been opened read\-only.
199 returns true if an I/O error has occurred.
201 .BR sdbm_clearerr (\|)
202 allows you to clear the error flag if you think you know what the error
203 was and insist on ignoring it.
206 returns the file descriptor associated with the bitmap file.
209 returns the file descriptor associated with the data file.
213 Functions that return a
217 to indicate an error.
218 Functions that return an
220 will use \-1 to indicate an error. The normal return value in that case is 0.
221 Functions that return a
225 to indicate an error.
229 if it is called with the
231 flag and the key already exists in the database, the return value will be 1.
233 In general, if a function parameter is invalid,
237 If a write operation is requested on a read-only database,
241 If a memory allocation (using
247 For I/O operation failures
249 will contain the value set by the relevant failed system call, either
255 .IP "Ozan S. Yigit" (oz@nexus.yorku.ca)
257 The sum of key and value data sizes must not exceed
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.
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.
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.
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
283 header file should be installed in
284 .BR /usr/include/ndbm.h .
291 .BR sdbm_rdonly (\|),
292 .BR sdbm_dirfno (\|),
295 functions are unique to this package.