1 .\" $Id: sdbm.3,v 1.2 90/12/13 13:00:57 oz Exp $
2 .TH SDBM 3 "1 March 1990"
4 sdbm, dbm_open, dbm_prep, dbm_close, dbm_fetch, dbm_store, dbm_delete, dbm_firstkey, dbm_nextkey, dbm_hash, dbm_rdonly, dbm_error, dbm_clearerr, dbm_dirfno, dbm_pagfno \- data base subroutines
15 datum nullitem = { NULL, 0 };
17 \s-1DBM\s0 *dbm_open(char *file, int flags, int mode)
19 \s-1DBM\s0 *dbm_prep(char *dirname, char *pagname, int flags, int mode)
21 void dbm_close(\s-1DBM\s0 *db)
23 datum dbm_fetch(\s-1DBM\s0 *db, key)
25 int dbm_store(\s-1DBM\s0 *db, datum key, datum val, int flags)
27 int dbm_delete(\s-1DBM\s0 *db, datum key)
29 datum dbm_firstkey(\s-1DBM\s0 *db)
31 datum dbm_nextkey(\s-1DBM\s0 *db)
33 long dbm_hash(char *string, int len)
35 int dbm_rdonly(\s-1DBM\s0 *db)
36 int dbm_error(\s-1DBM\s0 *db)
37 dbm_clearerr(\s-1DBM\s0 *db)
38 int dbm_dirfno(\s-1DBM\s0 *db)
39 int dbm_pagfno(\s-1DBM\s0 *db)
43 .IX "database library" sdbm "" "\fLsdbm\fR"
44 .IX dbm_open "" "\fLdbm_open\fR \(em open \fLsdbm\fR database"
45 .IX dbm_prep "" "\fLdbm_prep\fR \(em prepare \fLsdbm\fR database"
46 .IX dbm_close "" "\fLdbm_close\fR \(em close \fLsdbm\fR routine"
47 .IX dbm_fetch "" "\fLdbm_fetch\fR \(em fetch \fLsdbm\fR database data"
48 .IX dbm_store "" "\fLdbm_store\fR \(em add data to \fLsdbm\fR database"
49 .IX dbm_delete "" "\fLdbm_delete\fR \(em remove data from \fLsdbm\fR database"
50 .IX dbm_firstkey "" "\fLdbm_firstkey\fR \(em access \fLsdbm\fR database"
51 .IX dbm_nextkey "" "\fLdbm_nextkey\fR \(em access \fLsdbm\fR database"
52 .IX dbm_hash "" "\fLdbm_hash\fR \(em string hash for \fLsdbm\fR database"
53 .IX dbm_rdonly "" "\fLdbm_rdonly\fR \(em return \fLsdbm\fR database read-only mode"
54 .IX dbm_error "" "\fLdbm_error\fR \(em return \fLsdbm\fR database error condition"
55 .IX dbm_clearerr "" "\fLdbm_clearerr\fR \(em clear \fLsdbm\fR database error condition"
56 .IX dbm_dirfno "" "\fLdbm_dirfno\fR \(em return \fLsdbm\fR database bitmap file descriptor"
57 .IX dbm_pagfno "" "\fLdbm_pagfno\fR \(em return \fLsdbm\fR database data file descriptor"
58 .IX "database functions \(em \fLsdbm\fR" dbm_open "" \fLdbm_open\fP
59 .IX "database functions \(em \fLsdbm\fR" dbm_prep "" \fLdbm_prep\fP
60 .IX "database functions \(em \fLsdbm\fR" dbm_close "" \fLdbm_close\fP
61 .IX "database functions \(em \fLsdbm\fR" dbm_fetch "" \fLdbm_fetch\fP
62 .IX "database functions \(em \fLsdbm\fR" dbm_store "" \fLdbm_store\fP
63 .IX "database functions \(em \fLsdbm\fR" dbm_delete "" \fLdbm_delete\fP
64 .IX "database functions \(em \fLsdbm\fR" dbm_firstkey "" \fLdbm_firstkey\fP
65 .IX "database functions \(em \fLsdbm\fR" dbm_nextkey "" \fLdbm_nextkey\fP
66 .IX "database functions \(em \fLsdbm\fR" dbm_rdonly "" \fLdbm_rdonly\fP
67 .IX "database functions \(em \fLsdbm\fR" dbm_error "" \fLdbm_error\fP
68 .IX "database functions \(em \fLsdbm\fR" dbm_clearerr "" \fLdbm_clearerr\fP
69 .IX "database functions \(em \fLsdbm\fR" dbm_dirfno "" \fLdbm_dirfno\fP
70 .IX "database functions \(em \fLsdbm\fR" dbm_pagfno "" \fLdbm_pagfno\fP
72 This package allows an application to maintain a mapping of <key,value> pairs
73 in disk files. This is not to be considered a real database system, but is
74 still useful in many simple applications built around fast retrieval of a data
75 value from a key. This implementation uses an external hashing scheme,
76 called Dynamic Hashing, as described by Per-Aake Larson in BIT 18 (1978) pp.
77 184-201. Retrieval of any item usually requires a single disk access.
78 The application interface is compatible with the
84 database is kept in two files usually given the extensions
90 file contains a bitmap representing a forest of binary hash trees, the leaves
91 of which indicate data pages in the
95 The application interface uses the
97 structure to describe both
103 specifies a byte sequence of
113 then you must decide whether or not to include the terminating
115 byte which sometimes defines strings. Including it will require larger
116 database files, but it will be possible to get sensible output from a
118 command applied to the data file.
120 In order to allow a process using this package to manipulate multiple
121 databases, the applications interface always requires a
125 to identify the database to be manipulated. Such a handle can be obtained
126 from the only routines that do not require it, namely
130 Either of these will open or create the two necessary files. The
131 difference is that the latter allows explicitly naming the bitmap and data
134 will take a base file name and call
136 with the default extensions.
141 parameters are the same as for
144 To free the resources occupied while a database handle is active, call
147 Given a handle, one can retrieve data associated with a key by using the
149 routine, and associate data with a key by using the
158 .BR \s-1DBM_INSERT\s0 ,
159 which will not change an existing entry with the same key, or
160 .BR \s-1DBM_REPLACE\s0 ,
161 which will replace an existing entry with the same key.
162 Keys are unique within the database.
164 To delete a key and its associated value use the
168 To retrieve every key in the database, use a loop like:
172 for (key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))
177 The order of retrieval is unspecified.
179 If you determine that the performance of the database is inadequate or
180 you notice clustering or other effects that may be due to the hashing
181 algorithm used by this package, you can override it by supplying your
184 routine. Doing so will make the database unintelligable to any other
185 applications that do not use your specialized hash function.
188 The following macros are defined in the header file:
191 returns true if the database has been opened read\-only.
194 returns true if an I/O error has occurred.
196 .BR dbm_clearerr (\|)
197 allows you to clear the error flag if you think you know what the error
198 was and insist on ignoring it.
201 returns the file descriptor associated with the bitmap file.
204 returns the file descriptor associated with the data file.
208 Functions that return a
212 to indicate an error.
213 Functions that return an
215 will use \-1 to indicate an error. The normal return value in that case is 0.
216 Functions that return a
220 to indicate an error.
224 if it is called with the
226 flag and the key already exists in the database, the return value will be 1.
228 In general, if a function parameter is invalid,
232 If a write operation is requested on a read-only database,
236 If a memory allocation (using
242 For I/O operation failures
244 will contain the value set by the relevant failed system call, either
250 .IP "Ozan S. Yigit" (oz@nexus.yorku.ca)
252 The sum of key and value data sizes must not exceed
256 The sum of the key and value data sizes where several keys hash to the
257 same value must fit within one bitmap page.
261 file will contain holes, so its apparent size is larger than its contents.
262 When copied through the filesystem the holes will be filled.
266 values returned are in volatile storage. If you want to retain the values
267 pointed to, you must copy them immediately before another call to this package.
269 The only safe way for multiple processes to (read and) update a database at
270 the same time, is to implement a private locking scheme outside this package
271 and open and close the database between lock acquisitions. It is safe for
272 multiple processes to concurrently access a database read-only.
273 .SH APPLICATIONS PORTABILITY
274 For complete source code compatibility with the Berkeley Unix
278 header file should be installed in
279 .BR /usr/include/ndbm.h .
290 functions are unique to this package.