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