1 | This is gdbm.info, produced by makeinfo version 4.2 from
|
---|
2 | ../gdbm.texinfo.
|
---|
3 |
|
---|
4 | INFO-DIR-SECTION Programming & development tools
|
---|
5 | START-INFO-DIR-ENTRY
|
---|
6 | * GDBM: (gdbm). The GNU database manager.
|
---|
7 | END-INFO-DIR-ENTRY
|
---|
8 |
|
---|
9 | This file documents the GNU dbm utility.
|
---|
10 |
|
---|
11 | Copyright (C) 1989-1999 Free Software Foundation, Inc.
|
---|
12 |
|
---|
13 | Permission is granted to make and distribute verbatim copies of this
|
---|
14 | manual provided the copyright notice and this permission notice are
|
---|
15 | preserved on all copies.
|
---|
16 |
|
---|
17 | Permission is granted to copy and distribute modified versions of
|
---|
18 | this manual under the conditions for verbatim copying, provided also
|
---|
19 | that the entire resulting derived work is distributed under the terms
|
---|
20 | of a permission notice identical to this one.
|
---|
21 |
|
---|
22 | Permission is granted to copy and distribute translations of this
|
---|
23 | manual into another language, under the above conditions for modified
|
---|
24 | versions.
|
---|
25 |
|
---|
26 |
|
---|
27 | File: gdbm.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
|
---|
28 |
|
---|
29 | GNU `dbm' is a library of functions implementing a hashed database
|
---|
30 | on a disk file. This manual documents GNU `dbm' Version 1.8.3
|
---|
31 | (`gdbm'). The software was written by Philip A. Nelson. This document
|
---|
32 | was originally written by Pierre Gaumond from texts written by Phil.
|
---|
33 |
|
---|
34 | * Menu:
|
---|
35 |
|
---|
36 | Introduction:
|
---|
37 |
|
---|
38 | * Copying:: Your rights.
|
---|
39 | * Intro:: Introduction to GNU dbm.
|
---|
40 | * List:: List of functions.
|
---|
41 |
|
---|
42 | Functions:
|
---|
43 |
|
---|
44 | * Open:: Opening the database.
|
---|
45 | * Close:: Closing the database.
|
---|
46 | * Store:: Inserting and replacing records in the database.
|
---|
47 | * Fetch:: Searching records in the database.
|
---|
48 | * Delete:: Removing records from the database.
|
---|
49 | * Sequential:: Sequential access to records.
|
---|
50 | * Reorganization:: Database reorganization.
|
---|
51 | * Sync:: Insure all writes to disk have competed.
|
---|
52 | * Errors:: Convert internal error codes into English.
|
---|
53 | * Options:: Setting internal options.
|
---|
54 | * Locking:: File locking.
|
---|
55 |
|
---|
56 | Other topics:
|
---|
57 |
|
---|
58 | * Variables:: Two useful variables.
|
---|
59 | * Compatibility:: Compatibility with UNIX dbm and ndbm.
|
---|
60 | * Conversion:: Converting dbm files to gdbm format.
|
---|
61 | * Bugs:: Problems and bugs.
|
---|
62 |
|
---|
63 |
|
---|
64 | File: gdbm.info, Node: Copying, Next: Intro, Prev: Top, Up: Top
|
---|
65 |
|
---|
66 | Copying Conditions.
|
---|
67 | *******************
|
---|
68 |
|
---|
69 | This library is "free"; this means that everyone is free to use it
|
---|
70 | and free to redistribute it on a free basis. GNU `dbm' (`gdbm') is not
|
---|
71 | in the public domain; it is copyrighted and there are restrictions on
|
---|
72 | its distribution, but these restrictions are designed to permit
|
---|
73 | everything that a good cooperating citizen would want to do. What is
|
---|
74 | not allowed is to try to prevent others from further sharing any
|
---|
75 | version of `gdbm' that they might get from you.
|
---|
76 |
|
---|
77 | Specifically, we want to make sure that you have the right to give
|
---|
78 | away copies `gdbm', that you receive source code or else can get it if
|
---|
79 | you want it, that you can change these functions or use pieces of them
|
---|
80 | in new free programs, and that you know you can do these things.
|
---|
81 |
|
---|
82 | To make sure that everyone has such rights, we have to forbid you to
|
---|
83 | deprive anyone else of these rights. For example, if you distribute
|
---|
84 | copies `gdbm', you must give the recipients all the rights that you
|
---|
85 | have. You must make sure that they, too, receive or can get the source
|
---|
86 | code. And you must tell them their rights.
|
---|
87 |
|
---|
88 | Also, for our own protection, we must make certain that everyone
|
---|
89 | finds out that there is no warranty for anything in the `gdbm'
|
---|
90 | distribution. If these functions are modified by someone else and
|
---|
91 | passed on, we want their recipients to know that what they have is not
|
---|
92 | what we distributed, so that any problems introduced by others will not
|
---|
93 | reflect on our reputation.
|
---|
94 |
|
---|
95 | `gdbm' is currently distributed under the terms of the GNU General
|
---|
96 | Public License, Version 2. (_NOT_ under the GNU General Library Public
|
---|
97 | License.) A copy the GNU General Public License is included with the
|
---|
98 | distribution of `gdbm'.
|
---|
99 |
|
---|
100 |
|
---|
101 | File: gdbm.info, Node: Intro, Next: List, Prev: Copying, Up: Top
|
---|
102 |
|
---|
103 | Introduction to GNU `dbm'.
|
---|
104 | **************************
|
---|
105 |
|
---|
106 | GNU `dbm' (`gdbm')is a library of database functions that use
|
---|
107 | extendible hashing and works similar to the standard UNIX `dbm'
|
---|
108 | functions. These routines are provided to a programmer needing to
|
---|
109 | create and manipulate a hashed database. (`gdbm' is _NOT_ a complete
|
---|
110 | database package for an end user.)
|
---|
111 |
|
---|
112 | The basic use of `gdbm' is to store key/data pairs in a data file.
|
---|
113 | Each key must be unique and each key is paired with only one data item.
|
---|
114 | The keys can not be directly accessed in sorted order. The basic unit
|
---|
115 | of data in `gdbm' is the structure:
|
---|
116 |
|
---|
117 | typedef struct {
|
---|
118 | char *dptr;
|
---|
119 | int dsize;
|
---|
120 | } datum;
|
---|
121 |
|
---|
122 | This structure allows for arbitrary sized keys and data items.
|
---|
123 |
|
---|
124 | The key/data pairs are stored in a `gdbm' disk file, called a `gdbm'
|
---|
125 | database. An application must open a `gdbm' database to be able
|
---|
126 | manipulate the keys and data contained in the database. `gdbm' allows
|
---|
127 | an application to have multiple databases open at the same time. When
|
---|
128 | an application opens a `gdbm' database, it is designated as a `reader'
|
---|
129 | or a `writer'. A `gdbm' database opened by at most one writer at a
|
---|
130 | time. However, many readers may open the database open simultaneously.
|
---|
131 | Readers and writers can not open the `gdbm' database at the same time.
|
---|
132 |
|
---|
133 |
|
---|
134 | File: gdbm.info, Node: List, Next: Open, Prev: Intro, Up: Top
|
---|
135 |
|
---|
136 | List of functions.
|
---|
137 | ******************
|
---|
138 |
|
---|
139 | The following is a quick list of the functions contained in the
|
---|
140 | `gdbm' library. The include file `gdbm.h', that can be included by the
|
---|
141 | user, contains a definition of these functions.
|
---|
142 |
|
---|
143 | #include <gdbm.h>
|
---|
144 |
|
---|
145 | GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func);
|
---|
146 | void gdbm_close(dbf);
|
---|
147 | int gdbm_store(dbf, key, content, flag);
|
---|
148 | datum gdbm_fetch(dbf, key);
|
---|
149 | int gdbm_delete(dbf, key);
|
---|
150 | datum gdbm_firstkey(dbf);
|
---|
151 | datum gdbm_nextkey(dbf, key);
|
---|
152 | int gdbm_reorganize(dbf);
|
---|
153 | void gdbm_sync(dbf);
|
---|
154 | int gdbm_exists(dbf, key);
|
---|
155 | char *gdbm_strerror(errno);
|
---|
156 | int gdbm_setopt(dbf, option, value, size);
|
---|
157 | int gdbm_fdesc(dbf);
|
---|
158 |
|
---|
159 | The `gdbm.h' include file is often in the `/usr/local/include'
|
---|
160 | directory. (The actual location of `gdbm.h' depends on your local
|
---|
161 | installation of `gdbm'.)
|
---|
162 |
|
---|
163 |
|
---|
164 | File: gdbm.info, Node: Open, Next: Close, Prev: List, Up: Top
|
---|
165 |
|
---|
166 | Opening the database.
|
---|
167 | *********************
|
---|
168 |
|
---|
169 | Initialize `gdbm' system. If the file has a size of zero bytes, a
|
---|
170 | file initialization procedure is performed, setting up the initial
|
---|
171 | structure in the file.
|
---|
172 |
|
---|
173 | The procedure for opening a `gdbm' file is:
|
---|
174 |
|
---|
175 | GDBM_FILE dbf;
|
---|
176 |
|
---|
177 | dbf = gdbm_open(name, block_size, flags, mode, fatal_func);
|
---|
178 |
|
---|
179 | The parameters are:
|
---|
180 |
|
---|
181 | char *name
|
---|
182 | The name of the file (the complete name, `gdbm' does not append any
|
---|
183 | characters to this name).
|
---|
184 |
|
---|
185 | int block_size
|
---|
186 | It is used during initialization to determine the size of various
|
---|
187 | constructs. It is the size of a single transfer from disk to
|
---|
188 | memory. This parameter is ignored if the file has been previously
|
---|
189 | initialized. The minimum size is 512. If the value is less than
|
---|
190 | 512, the file system blocksize is used, otherwise the value of
|
---|
191 | `block_size' is used.
|
---|
192 |
|
---|
193 | int flags
|
---|
194 | If `flags' is set to GDBM_READER, the user wants to just read the
|
---|
195 | database and any call to `gdbm_store' or `gdbm_delete' will fail.
|
---|
196 | Many readers can access the database at the same time. If `flags'
|
---|
197 | is set to GDBM_WRITER, the user wants both read and write access
|
---|
198 | to the database and requires exclusive access. If `flags' is set
|
---|
199 | to GDBM_WRCREAT, the user wants both read and write access to the
|
---|
200 | database and if the database does not exist, create a new one. If
|
---|
201 | `flags' is set to GDBM_NEWDB, the user want a new database
|
---|
202 | created, regardless of whether one existed, and wants read and
|
---|
203 | write access to the new database. The following may also be
|
---|
204 | logically or'd into the database flags: GDBM_SYNC, which causes
|
---|
205 | all database operations to be synchronized to the disk, and
|
---|
206 | GDBM_NOLOCK, which prevents the library from performing any
|
---|
207 | locking on the database file. The option GDBM_FAST is now
|
---|
208 | obsolete, since `gdbm' defaults to no-sync mode. Any error
|
---|
209 | detected will cause a return value of NULL and an appropriate
|
---|
210 | value will be in `gdbm_errno' (see Variables). If no errors occur,
|
---|
211 | a pointer to the `gdbm' file descriptor will be returned.
|
---|
212 |
|
---|
213 | int mode
|
---|
214 | File mode (see chmod(2) and open(2) if the file is created).
|
---|
215 |
|
---|
216 | void (*fatal_func) ()
|
---|
217 | A function for `gdbm' to call if it detects a fatal error. The only
|
---|
218 | parameter of this function is a string. If the value of NULL is
|
---|
219 | provided, `gdbm' will use a default function.
|
---|
220 |
|
---|
221 | The return value, `dbf', is the pointer needed by all other
|
---|
222 | functions to access that `gdbm' file. If the return is the NULL pointer,
|
---|
223 | `gdbm_open' was not successful. The errors can be found in `gdbm_errno'
|
---|
224 | for `gdbm' errors and in `errno' for file system errors (for error
|
---|
225 | codes, see `gdbm.h').
|
---|
226 |
|
---|
227 | In all of the following calls, the parameter `dbf' refers to the
|
---|
228 | pointer returned from `gdbm_open'.
|
---|
229 |
|
---|
230 |
|
---|
231 | File: gdbm.info, Node: Close, Next: Store, Prev: Open, Up: Top
|
---|
232 |
|
---|
233 | Closing the database.
|
---|
234 | *********************
|
---|
235 |
|
---|
236 | It is important that every file opened is also closed. This is
|
---|
237 | needed to update the reader/writer count on the file. This is done by:
|
---|
238 |
|
---|
239 | gdbm_close(dbf);
|
---|
240 |
|
---|
241 | The parameter is:
|
---|
242 |
|
---|
243 | GDBM_FILE dbf
|
---|
244 | The pointer returned by `gdbm_open'.
|
---|
245 |
|
---|
246 | Closes the `gdbm' file and frees all memory associated with the file
|
---|
247 | `dbf'.
|
---|
248 |
|
---|
249 |
|
---|
250 | File: gdbm.info, Node: Store, Next: Fetch, Prev: Close, Up: Top
|
---|
251 |
|
---|
252 | Inserting and replacing records in the database.
|
---|
253 | ************************************************
|
---|
254 |
|
---|
255 | The function `gdbm_store' inserts or replaces records in the
|
---|
256 | database.
|
---|
257 |
|
---|
258 | ret = gdbm_store(dbf, key, content, flag);
|
---|
259 |
|
---|
260 | The parameters are:
|
---|
261 |
|
---|
262 | GDBM_FILE dbf
|
---|
263 | The pointer returned by `gdbm_open'.
|
---|
264 |
|
---|
265 | datum key
|
---|
266 | The `key' data.
|
---|
267 |
|
---|
268 | datum content
|
---|
269 | The data to be associated with the key.
|
---|
270 |
|
---|
271 | int flag
|
---|
272 | Defines the action to take when the key is already in the
|
---|
273 | database. The value GDBM_REPLACE (defined in `gdbm.h') asks that
|
---|
274 | the old data be replaced by the new `content'. The value
|
---|
275 | GDBM_INSERT asks that an error be returned and no action taken if
|
---|
276 | the `key' already exists.
|
---|
277 |
|
---|
278 | The values returned in `ret' are:
|
---|
279 |
|
---|
280 | -1
|
---|
281 | The item was not stored in the database because the caller was not
|
---|
282 | an official writer or either `key' or `content' have a NULL dptr
|
---|
283 | field. Both `key' and `content' must have the dptr field be a
|
---|
284 | non-NULL value. Since a NULL dptr field is used by other
|
---|
285 | functions to indicate an error, a NULL field cannot be valid data.
|
---|
286 |
|
---|
287 | +1
|
---|
288 | The item was not stored because the argument `flag' was
|
---|
289 | GDBM_INSERT and the `key' was already in the database.
|
---|
290 |
|
---|
291 | 0
|
---|
292 | No error. `content' is keyed by `key'. The file on disk is updated
|
---|
293 | to reflect the structure of the new database before returning from
|
---|
294 | this function.
|
---|
295 |
|
---|
296 | If you store data for a `key' that is already in the data base,
|
---|
297 | `gdbm' replaces the old data with the new data if called with
|
---|
298 | GDBM_REPLACE. You do not get two data items for the same `key' and you
|
---|
299 | do not get an error from `gdbm_store'.
|
---|
300 |
|
---|
301 | The size in `gdbm' is not restricted like `dbm' or `ndbm'. Your data
|
---|
302 | can be as large as you want.
|
---|
303 |
|
---|
304 |
|
---|
305 | File: gdbm.info, Node: Fetch, Next: Delete, Prev: Store, Up: Top
|
---|
306 |
|
---|
307 | Searching for records in the database.
|
---|
308 | **************************************
|
---|
309 |
|
---|
310 | Looks up a given `key' and returns the information associated with
|
---|
311 | that key. The pointer in the structure that is returned is a pointer
|
---|
312 | to dynamically allocated memory block. To search for some data:
|
---|
313 |
|
---|
314 | content = gdbm_fetch(dbf, key);
|
---|
315 |
|
---|
316 | The parameters are:
|
---|
317 |
|
---|
318 | GDBM_FILE dbf
|
---|
319 | The pointer returned by `gdbm_open'.
|
---|
320 |
|
---|
321 | datum key
|
---|
322 | The `key' data.
|
---|
323 |
|
---|
324 | The datum returned in `content' is a pointer to the data found. If
|
---|
325 | the dptr is NULL, no data was found. If dptr is not NULL, then it points
|
---|
326 | to data allocated by malloc. `gdbm' does not automatically free this
|
---|
327 | data. The user must free this storage when done using it. This
|
---|
328 | eliminates the need to copy the result to save it for later use (you
|
---|
329 | just save the pointer).
|
---|
330 |
|
---|
331 | You may also search for a particular key without retrieving it,
|
---|
332 | using:
|
---|
333 |
|
---|
334 | ret = gdbm_exists(dbf, key);
|
---|
335 |
|
---|
336 | The parameters are:
|
---|
337 |
|
---|
338 | GDBM_FILE dbf
|
---|
339 | The pointer returned by `gdbm_open'.
|
---|
340 |
|
---|
341 | datum key
|
---|
342 | The `key' data.
|
---|
343 |
|
---|
344 | Unlike `gdbm_fetch', this routine does not allocate any memory, and
|
---|
345 | simply returns true or false, depending on whether the `key' exists, or
|
---|
346 | not.
|
---|
347 |
|
---|
348 |
|
---|
349 | File: gdbm.info, Node: Delete, Next: Sequential, Prev: Fetch, Up: Top
|
---|
350 |
|
---|
351 | Removing records from the database.
|
---|
352 | ***********************************
|
---|
353 |
|
---|
354 | To remove some data from the database:
|
---|
355 |
|
---|
356 | ret = gdbm_delete(dbf, key);
|
---|
357 |
|
---|
358 | The parameters are:
|
---|
359 |
|
---|
360 | GDBM_FILE dbf
|
---|
361 | The pointer returned by `gdbm_open'.
|
---|
362 |
|
---|
363 | datum key
|
---|
364 | The `key' data.
|
---|
365 |
|
---|
366 | The ret value is -1 if the item is not present or the requester is a
|
---|
367 | reader. The ret value is 0 if there was a successful delete.
|
---|
368 |
|
---|
369 | `gdbm_delete' removes the keyed item and the `key' from the database
|
---|
370 | `dbf'. The file on disk is updated to reflect the structure of the new
|
---|
371 | database before returning from this function.
|
---|
372 |
|
---|
373 |
|
---|
374 | File: gdbm.info, Node: Sequential, Next: Reorganization, Prev: Delete, Up: Top
|
---|
375 |
|
---|
376 | Sequential access to records.
|
---|
377 | *****************************
|
---|
378 |
|
---|
379 | The next two functions allow for accessing all items in the
|
---|
380 | database. This access is not `key' sequential, but it is guaranteed to
|
---|
381 | visit every `key' in the database once. The order has to do with the
|
---|
382 | hash values. `gdbm_firstkey' starts the visit of all keys in the
|
---|
383 | database. `gdbm_nextkey' finds and reads the next entry in the hash
|
---|
384 | structure for `dbf'.
|
---|
385 |
|
---|
386 | key = gdbm_firstkey(dbf);
|
---|
387 |
|
---|
388 | nextkey = gdbm_nextkey(dbf, key);
|
---|
389 |
|
---|
390 | The parameters are:
|
---|
391 |
|
---|
392 | GDBM_FILE dbf
|
---|
393 | The pointer returned by `gdbm_open'.
|
---|
394 |
|
---|
395 | datum `key'
|
---|
396 |
|
---|
397 | datum nextkey
|
---|
398 | The `key' data.
|
---|
399 |
|
---|
400 | The return values are both datum. If `key'.dptr or nextkey.dptr is
|
---|
401 | NULL, there is no first `key' or next `key'. Again notice that dptr
|
---|
402 | points to data allocated by malloc and `gdbm' will not free it for you.
|
---|
403 |
|
---|
404 | These functions were intended to visit the database in read-only
|
---|
405 | algorithms, for instance, to validate the database or similar
|
---|
406 | operations.
|
---|
407 |
|
---|
408 | File `visiting' is based on a `hash table'. `gdbm_delete'
|
---|
409 | re-arranges the hash table to make sure that any collisions in the
|
---|
410 | table do not leave some item `un-findable'. The original key order is
|
---|
411 | NOT guaranteed to remain unchanged in ALL instances. It is possible
|
---|
412 | that some key will not be visited if a loop like the following is
|
---|
413 | executed:
|
---|
414 |
|
---|
415 | key = gdbm_firstkey ( dbf );
|
---|
416 | while ( key.dptr ) {
|
---|
417 | nextkey = gdbm_nextkey ( dbf, key );
|
---|
418 | if ( some condition ) {
|
---|
419 | gdbm_delete ( dbf, key );
|
---|
420 | free ( key.dptr );
|
---|
421 | }
|
---|
422 | key = nextkey;
|
---|
423 | }
|
---|
424 |
|
---|
425 |
|
---|
426 | File: gdbm.info, Node: Reorganization, Next: Sync, Prev: Sequential, Up: Top
|
---|
427 |
|
---|
428 | Database reorganization.
|
---|
429 | ************************
|
---|
430 |
|
---|
431 | The following function should be used very seldom.
|
---|
432 |
|
---|
433 | ret = gdbm_reorganize(dbf);
|
---|
434 |
|
---|
435 | The parameter is:
|
---|
436 |
|
---|
437 | GDBM_FILE dbf
|
---|
438 | The pointer returned by `gdbm_open'.
|
---|
439 |
|
---|
440 | If you have had a lot of deletions and would like to shrink the space
|
---|
441 | used by the `gdbm' file, this function will reorganize the database.
|
---|
442 | `gdbm' will not shorten the length of a `gdbm' file (deleted file space
|
---|
443 | will be reused) except by using this reorganization.
|
---|
444 |
|
---|
445 | This reorganization requires creating a new file and inserting all
|
---|
446 | the elements in the old file `dbf' into the new file. The new file is
|
---|
447 | then renamed to the same name as the old file and `dbf' is updated to
|
---|
448 | contain all the correct information about the new file. If an error is
|
---|
449 | detected, the return value is negative. The value zero is returned
|
---|
450 | after a successful reorganization.
|
---|
451 |
|
---|
452 |
|
---|
453 | File: gdbm.info, Node: Sync, Next: Errors, Prev: Reorganization, Up: Top
|
---|
454 |
|
---|
455 | Database Synchronization
|
---|
456 | ************************
|
---|
457 |
|
---|
458 | Unless your database was opened with the GDBM_SYNC flag, `gdbm' does
|
---|
459 | not wait for writes to be flushed to the disk before continuing. This
|
---|
460 | allows faster writing of databases at the risk of having a corrupted
|
---|
461 | database if the application terminates in an abnormal fashion. The
|
---|
462 | following function allows the programmer to make sure the disk version
|
---|
463 | of the database has been completely updated with all changes to the
|
---|
464 | current time.
|
---|
465 |
|
---|
466 | gdbm_sync(dbf);
|
---|
467 |
|
---|
468 | The parameter is:
|
---|
469 |
|
---|
470 | GDBM_FILE dbf
|
---|
471 | The pointer returned by `gdbm_open'.
|
---|
472 |
|
---|
473 | This would usually be called after a complete set of changes have
|
---|
474 | been made to the database and before some long waiting time.
|
---|
475 | `gdbm_close' automatically calls the equivalent of `gdbm_sync' so no
|
---|
476 | call is needed if the database is to be closed immediately after the
|
---|
477 | set of changes have been made.
|
---|
478 |
|
---|
479 |
|
---|
480 | File: gdbm.info, Node: Errors, Next: Options, Prev: Sync, Up: Top
|
---|
481 |
|
---|
482 | Error strings.
|
---|
483 | **************
|
---|
484 |
|
---|
485 | To convert a `gdbm' error code into English text, use this routine:
|
---|
486 |
|
---|
487 | ret = gdbm_strerror(errno)
|
---|
488 |
|
---|
489 | The parameter is:
|
---|
490 |
|
---|
491 | gdbm_error errno
|
---|
492 | The `gdbm' error code, usually `gdbm_errno'.
|
---|
493 |
|
---|
494 | The appropiate phrase for reading by humans is returned.
|
---|
495 |
|
---|
496 |
|
---|
497 | File: gdbm.info, Node: Options, Next: Locking, Prev: Errors, Up: Top
|
---|
498 |
|
---|
499 | Seting options.
|
---|
500 | ***************
|
---|
501 |
|
---|
502 | `Gdbm' supports the ability to set certain options on an already
|
---|
503 | open database.
|
---|
504 |
|
---|
505 | ret = gdbm_setopt(dbf, option, value, size);
|
---|
506 |
|
---|
507 | The parameters are:
|
---|
508 |
|
---|
509 | GDBM_FILE dbf
|
---|
510 | The pointer returned by `gdbm_open'.
|
---|
511 |
|
---|
512 | int option
|
---|
513 | The option to be set.
|
---|
514 |
|
---|
515 | int *value
|
---|
516 | A pointer to the value to which `option' will be set.
|
---|
517 |
|
---|
518 | int size
|
---|
519 | The length of the data pointed to by `value'.
|
---|
520 |
|
---|
521 | The valid options are:
|
---|
522 |
|
---|
523 | GDBM_CACHESIZE - Set the size of the internal bucket cache. This
|
---|
524 | option may only be set once on each GDBM_FILE descriptor, and is set
|
---|
525 | automatically to 100 upon the first access to the database.
|
---|
526 |
|
---|
527 | GDBM_FASTMODE - Set fast mode to either on or off. This allows
|
---|
528 | fast mode to be toggled on an already open and active database.
|
---|
529 | value (see below) should be set to either TRUE or FALSE. _This
|
---|
530 | option is now obsolete._
|
---|
531 |
|
---|
532 | GDBM_SYNCMODE - Turn on or off file system synchronization
|
---|
533 | operations. This setting defaults to off; value (see below) should
|
---|
534 | be set to either TRUE or FALSE.
|
---|
535 |
|
---|
536 | GDBM_CENTFREE - Set central free block pool to either on or off.
|
---|
537 | The default is off, which is how previous versions of `Gdbm' handled
|
---|
538 | free blocks. If set, this option causes all subsequent free blocks
|
---|
539 | to be placed in the _global_ pool, allowing (in theory) more file
|
---|
540 | space to be reused more quickly. value (see below) should be set to
|
---|
541 | either TRUE or FALSE. _NOTICE: This feature is still under study._
|
---|
542 |
|
---|
543 | GDBM_COALESCEBLKS - Set free block merging to either on or off.
|
---|
544 | The default is off, which is how previous versions of `Gdbm' handled
|
---|
545 | free blocks. If set, this option causes adjacent free blocks to be
|
---|
546 | merged. This can become a CPU expensive process with time, though,
|
---|
547 | especially if used in conjunction with GDBM_CENTFREE. value (see below)
|
---|
548 | should be set to either TRUE or FALSE. _NOTICE: This feature is
|
---|
549 | still under study._
|
---|
550 |
|
---|
551 | The return value will be -1 upon failure, or 0 upon success. The
|
---|
552 | global variable `gdbm_errno' will be set upon failure.
|
---|
553 |
|
---|
554 | For instance, to set a database to use a cache of 10, after opening
|
---|
555 | it with `gdbm_open', but prior to accessing it in any way, the following
|
---|
556 | code could be used:
|
---|
557 |
|
---|
558 | int value = 10;
|
---|
559 | ret = gdbm_setopt(dbf, GDBM_CACHESIZE, &value, sizeof(int));
|
---|
560 |
|
---|
561 |
|
---|
562 | File: gdbm.info, Node: Locking, Next: Variables, Prev: Options, Up: Top
|
---|
563 |
|
---|
564 | File Locking.
|
---|
565 | *************
|
---|
566 |
|
---|
567 | With locking disabled (if `gdbm_open' was called with GDBM_NOLOCK),
|
---|
568 | the user may want to perform their own file locking on the database file
|
---|
569 | in order to prevent multiple writers operating on the same file
|
---|
570 | simultaneously.
|
---|
571 |
|
---|
572 | In order to support this, the `gdbm_fdesc' routine is provided.
|
---|
573 |
|
---|
574 | ret = gdbm_fdesc(dbf);
|
---|
575 |
|
---|
576 | The single valid parameter is:
|
---|
577 |
|
---|
578 | GDBM_FILE dbf
|
---|
579 | The pointer returned by `gdbm_open'.
|
---|
580 |
|
---|
581 | The return value will be the file descriptor of the database.
|
---|
582 |
|
---|
583 |
|
---|
584 | File: gdbm.info, Node: Variables, Next: Compatibility, Prev: Locking, Up: Top
|
---|
585 |
|
---|
586 | Two useful variables.
|
---|
587 | *********************
|
---|
588 |
|
---|
589 | The following two variables are variables that may need to be used:
|
---|
590 |
|
---|
591 | gdbm_error gdbm_errno
|
---|
592 | The variable that contains more information about `gdbm' errors
|
---|
593 | (`gdbm.h' has the definitions of the error values).
|
---|
594 |
|
---|
595 | char * gdbm_version
|
---|
596 | The string containing the version information.
|
---|
597 |
|
---|
598 |
|
---|
599 | File: gdbm.info, Node: Compatibility, Next: Conversion, Prev: Variables, Up: Top
|
---|
600 |
|
---|
601 | Compatibility with standard `dbm' and `ndbm'.
|
---|
602 | *********************************************
|
---|
603 |
|
---|
604 | GNU `dbm' files are not `sparse'. You can copy them with the UNIX
|
---|
605 | `cp' command and they will not expand in the copying process.
|
---|
606 |
|
---|
607 | There is a compatibility mode for use with programs that already use
|
---|
608 | UNIX `dbm' and UNIX `ndbm'.
|
---|
609 |
|
---|
610 | GNU `dbm' has compatibility functions for `dbm'. For `dbm'
|
---|
611 | compatibility functions, you need the include file `dbm.h'.
|
---|
612 |
|
---|
613 | In this compatibility mode, no `gdbm' file pointer is required by
|
---|
614 | the user, and Only one file may be opened at a time. All users in
|
---|
615 | compatibility mode are assumed to be writers. If the `gdbm' file is a
|
---|
616 | read only, it will fail as a writer, but will also try to open it as a
|
---|
617 | reader. All returned pointers in datum structures point to data that
|
---|
618 | `gdbm' WILL free. They should be treated as static pointers (as
|
---|
619 | standard UNIX `dbm' does). The compatibility function names are the
|
---|
620 | same as the UNIX `dbm' function names. Their definitions follow:
|
---|
621 |
|
---|
622 | int dbminit(name);
|
---|
623 | int store(key, content);
|
---|
624 | datum fetch(key);
|
---|
625 | int delete(key);
|
---|
626 | datum firstkey();
|
---|
627 | datum nextkey(key);
|
---|
628 | int dbmclose();
|
---|
629 |
|
---|
630 | Standard UNIX `dbm' and GNU `dbm' do not have the same data format
|
---|
631 | in the file. You cannot access a standard UNIX `dbm' file with GNU
|
---|
632 | `dbm'! If you want to use an old database with GNU `dbm', you must use
|
---|
633 | the `conv2gdbm' program.
|
---|
634 |
|
---|
635 | Also, GNU `dbm' has compatibility functions for `ndbm'. For `ndbm'
|
---|
636 | compatibility functions, you need the include file `ndbm.h'.
|
---|
637 |
|
---|
638 | Again, just like `ndbm', any returned datum can be assumed to be
|
---|
639 | static storage. You do not have to free that memory, the `ndbm'
|
---|
640 | compatibility functions will do it for you.
|
---|
641 |
|
---|
642 | The functions are:
|
---|
643 |
|
---|
644 | DBM *dbm_open(name, flags, mode);
|
---|
645 | void dbm_close(file);
|
---|
646 | datum dbm_fetch(file, key);
|
---|
647 | int dbm_store(file, key, `content', flags);
|
---|
648 | int dbm_delete(file, key);
|
---|
649 | datum dbm_firstkey(file);
|
---|
650 | datum dbm_nextkey(file);
|
---|
651 | int dbm_error(file);
|
---|
652 | int dbm_clearerr(file);
|
---|
653 | int dbm_dirfno(file);
|
---|
654 | int dbm_pagfno(file);
|
---|
655 | int dbm_rdonly(file);
|
---|
656 |
|
---|
657 | If you want to compile an old C program that used UNIX `dbm' or
|
---|
658 | `ndbm' and want to use `gdbm' files, execute the following `cc' command:
|
---|
659 |
|
---|
660 | cc ... -L/usr/local/lib -lgdbm -lgdbm_compat
|
---|
661 |
|
---|
662 |
|
---|
663 | File: gdbm.info, Node: Conversion, Next: Bugs, Prev: Compatibility, Up: Top
|
---|
664 |
|
---|
665 | Converting `dbm' files to `gdbm' format.
|
---|
666 | ****************************************
|
---|
667 |
|
---|
668 | The program `conv2gdbm' has been provided to help you convert from
|
---|
669 | `dbm' databases to `gdbm'. The usage is:
|
---|
670 |
|
---|
671 | conv2gdbm [-q] [-b block_size] dbm_file [gdbm_file]
|
---|
672 |
|
---|
673 | The options are:
|
---|
674 |
|
---|
675 | -q
|
---|
676 | Causes `conv2gdbm' to work quietly.
|
---|
677 |
|
---|
678 | block_size
|
---|
679 | Is the same as in `gdbm_open'.
|
---|
680 |
|
---|
681 | dbm_file
|
---|
682 | Is the name of the `dbm' file without the `.pag' or `.dir'
|
---|
683 | extensions.
|
---|
684 |
|
---|
685 | gdbm_file
|
---|
686 | Is the complete file name. If not included, the `gdbm' file name
|
---|
687 | is the same as the `dbm' file name without any extensions. That is
|
---|
688 | `conv2gdbm' `dbmfile' converts the files `dbmfile.pag' and
|
---|
689 | `dbmfile.dir' into a `gdbm' file called `dbmfile'.
|
---|
690 |
|
---|
691 |
|
---|
692 | File: gdbm.info, Node: Bugs, Prev: Conversion, Up: Top
|
---|
693 |
|
---|
694 | Problems and bugs.
|
---|
695 | ******************
|
---|
696 |
|
---|
697 | If you have problems with GNU `dbm' or think you've found a bug,
|
---|
698 | please report it. Before reporting a bug, make sure you've actually
|
---|
699 | found a real bug. Carefully reread the documentation and see if it
|
---|
700 | really says you can do what you're trying to do. If it's not clear
|
---|
701 | whether you should be able to do something or not, report that too; it's
|
---|
702 | a bug in the documentation!
|
---|
703 |
|
---|
704 | Before reporting a bug or trying to fix it yourself, try to isolate
|
---|
705 | it to the smallest possible input file that reproduces the problem. Then
|
---|
706 | send us the input file and the exact results `gdbm' gave you. Also say
|
---|
707 | what you expected to occur; this will help us decide whether the
|
---|
708 | problem was really in the documentation.
|
---|
709 |
|
---|
710 | Once you've got a precise problem, send e-mail to:
|
---|
711 |
|
---|
712 | Internet: `[email protected]'.
|
---|
713 | UUCP: `mit-eddie!prep.ai.mit.edu!bug-gnu-utils'.
|
---|
714 |
|
---|
715 | Please include the version number of GNU `dbm' you are using. You
|
---|
716 | can get this information by printing the variable `gdbm_version' (see
|
---|
717 | Variables).
|
---|
718 |
|
---|
719 | Non-bug suggestions are always welcome as well. If you have questions
|
---|
720 | about things that are unclear in the documentation or are just obscure
|
---|
721 | features, please report them too.
|
---|
722 |
|
---|
723 | You may contact the author by:
|
---|
724 | e-mail: [email protected]
|
---|
725 | us-mail: Philip A. Nelson
|
---|
726 | Computer Science Department
|
---|
727 | Western Washington University
|
---|
728 | Bellingham, WA 98226
|
---|
729 |
|
---|
730 | You may contact the current maintainer by:
|
---|
731 | e-mail: [email protected]
|
---|
732 |
|
---|
733 |
|
---|
734 |
|
---|
735 | Tag Table:
|
---|
736 | Node: Top884
|
---|
737 | Node: Copying2359
|
---|
738 | Node: Intro4141
|
---|
739 | Node: List5557
|
---|
740 | Node: Open6509
|
---|
741 | Node: Close9380
|
---|
742 | Node: Store9815
|
---|
743 | Node: Fetch11610
|
---|
744 | Node: Delete12859
|
---|
745 | Node: Sequential13525
|
---|
746 | Node: Reorganization15208
|
---|
747 | Node: Sync16163
|
---|
748 | Node: Errors17129
|
---|
749 | Node: Options17489
|
---|
750 | Node: Locking19838
|
---|
751 | Node: Variables20426
|
---|
752 | Node: Compatibility20850
|
---|
753 | Node: Conversion23237
|
---|
754 | Node: Bugs24051
|
---|
755 |
|
---|
756 | End Tag Table
|
---|