Commit | Line | Data |
463ee0b2 |
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 |
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 |
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 |
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 |
42 | .ft R |
43 | .fi |
44 | .SH DESCRIPTION |
45 | .IX "database library" sdbm "" "\fLsdbm\fR" |
275cf23a |
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 |
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 |
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 |
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 |
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 |
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 |
155 | .BR sdbm_exists (\|) |
156 | will say whether a given key exists in the database. |
463ee0b2 |
157 | .LP |
158 | The values of the |
159 | .I flags |
160 | parameter for |
275cf23a |
161 | .BR sdbm_store (\|) |
463ee0b2 |
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 |
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 |
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 (\|) |
463ee0b2 |
189 | routine. Doing so will make the database unintelligable to any other |
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 |
196 | returns true if the database has been opened read\-only. |
197 | .IP |
275cf23a |
198 | .BR sdbm_error (\|) |
463ee0b2 |
199 | returns true if an I/O error has occurred. |
200 | .IP |
275cf23a |
201 | .BR sdbm_clearerr (\|) |
463ee0b2 |
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 |
206 | returns the file descriptor associated with the bitmap file. |
207 | .IP |
275cf23a |
208 | .BR sdbm_pagfno (\|) |
463ee0b2 |
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 |
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 |
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. |