1 \input texinfo @c -*- Texinfo -*-
2 @comment $Id: gdbm.texinfo,v 1.21 2011/11/12 22:40:14 gray Exp $
3 @comment %**start of header (This is for running Texinfo on a region.)
9 @dircategory Programming & development tools
11 * GDBM: (gdbm). The GNU database manager.
15 @c @setchapternewpage odd
16 @comment %**end of header (This is for running Texinfo on a region.)
18 @c Use @kwindex for keywords
21 @c Use @flindex for files
25 @c Merge all indices into a single one
37 This file documents the GNU dbm utility.
39 Copyright @copyright{} 1989-1999, 2007, 2008, 2009-2011 Free Software Foundation, Inc.
41 Permission is granted to copy, distribute and/or modify this document
42 under the terms of the GNU Free Documentation License, Version 1.3 or
43 any later version published by the Free Software Foundation; with no
44 Invariant Sections, with the Front-Cover Texts being ``The GNU Database
45 Manager,'' and with the Back-Cover Texts as in (a) below. A copy of the
46 license is included in the section entitled ``GNU Free Documentation
49 (a) The FSF's Back-Cover Text is: ``You have the freedom to
50 copy and modify this GNU manual. Buying copies from the FSF
51 supports it in developing GNU and promoting software freedom.''
56 @center @titlefont{GNU dbm}
58 @center A Database Manager
60 @center by Philip A. Nelson, Jason Downs and Sergey Poznyakoff
62 @center Manual by Pierre Gaumond, Philip A. Nelson, Jason Downs
63 @center and Sergey Poznyakoff
65 @center Edition @value{EDITION}
67 @center for GNU @code{dbm}, Version @value{VERSION}
69 @vskip 0pt plus 1filll
70 Copyright @copyright{} 1993-1999, 2007-2011 Free Software Foundation, Inc.
73 This is Edition @value{EDITION} of the @cite{GNU @code{dbm} Manual},
74 for @code{gdbm} Version @value{VERSION}. @*
75 Last updated @value{UPDATED}
77 Published by the Free Software Foundation @*
78 675 Massachusetts Avenue, @*
79 Cambridge, MA 02139 USA @*
81 Permission is granted to make and distribute verbatim copies of
82 this manual provided the copyright notice and this permission notice
83 are preserved on all copies.
85 Permission is granted to copy and distribute modified versions of this
86 manual under the conditions for verbatim copying, provided also that
87 the entire resulting derived work is distributed under the terms of a
88 permission notice identical to this one.
90 Permission is granted to copy and distribute translations of this manual
91 into another language, under the above conditions for modified versions,
92 except that this permission notice may be stated in a translation approved
93 by the Free Software Foundation.
106 @top The GNU database manager.
108 GNU @code{dbm} is a library of functions implementing a hashed database
109 on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION}
110 (@code{gdbm}). The software was originally written by Philip A. Nelson. This
111 document was originally written by Pierre Gaumond from texts written by
118 * Copying:: Your rights.
119 * Intro:: Introduction to GNU dbm.
120 * List:: List of functions.
124 * Open:: Opening the database.
125 * Close:: Closing the database.
126 * Store:: Inserting and replacing records in the database.
127 * Fetch:: Searching records in the database.
128 * Delete:: Removing records from the database.
129 * Sequential:: Sequential access to records.
130 * Reorganization:: Database reorganization.
131 * Sync:: Insure all writes to disk have competed.
132 * Flat files:: Export and import to Flat file format.
133 * Errors:: Convert internal error codes into English.
134 * Options:: Setting internal options.
135 * Locking:: File locking.
139 * testgdbm:: Test and modify a GDBM database.
140 * gdbmexport:: Export a database into a portable format.
144 * Error codes:: Error codes returned by @code{gdbm} calls.
145 * Variables:: Two useful variables.
146 * Compatibility:: Compatibility with UNIX dbm and ndbm.
147 * Bugs:: Problems and bugs.
148 * Resources:: Additional resources,
150 * GNU Free Documentation License:: Document license.
155 @chapter Copying Conditions.
156 This library is @dfn{free}; this means that everyone is free to use
157 it and free to redistribute it on a free basis. GNU @code{dbm} (@code{gdbm})
158 is not in the public domain; it is copyrighted and there
159 are restrictions on its distribution, but these restrictions are
160 designed to permit everything that a good cooperating citizen would want
161 to do. What is not allowed is to try to prevent others from further
162 sharing any version of @code{gdbm} that they might get from
165 Specifically, we want to make sure that you have the right to give
166 away copies @code{gdbm}, that you receive
167 source code or else can get it if you want it, that you can change these
168 functions or use pieces of them in new free programs, and that you know
169 you can do these things.@refill
171 To make sure that everyone has such rights, we have to forbid you to
172 deprive anyone else of these rights. For example, if you distribute
173 copies @code{gdbm}, you must give the recipients all
174 the rights that you have. You must make sure that they, too, receive or
175 can get the source code. And you must tell them their rights.@refill
177 Also, for our own protection, we must make certain that everyone finds
178 out that there is no warranty for anything in the @code{gdbm} distribution.
179 If these functions are modified by someone else and passed on, we want
180 their recipients to know that what they have is not what we distributed,
181 so that any problems introduced by others will not reflect on our
184 @code{Gdbm} is currently distributed under the terms of the GNU General
185 Public License, Version 3. (@emph{NOT} under the GNU General Library
186 Public License.) A copy the GNU General Public License is included with
187 the distribution of @code{gdbm}.
190 @chapter Introduction to GNU @code{dbm}.
192 GNU @code{dbm} (@code{gdbm}) is a library of database functions that use
193 extensible hashing and works similar to the standard UNIX @code{dbm}
194 functions. These routines are provided to a programmer needing to
195 create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a
196 complete database package for an end user.)
198 The basic use of @code{gdbm} is to store key/data pairs in a data file.
199 Each key must be unique and each key is paired with only one data item.
200 The keys can not be directly accessed in sorted order. The basic unit
201 of data in @code{gdbm} is the structure:
210 This structure allows for arbitrary sized keys and data items.
212 The key/data pairs are stored in a @code{gdbm} disk file, called a
213 @code{gdbm} database. An application must open a @code{gdbm} database
214 to be able manipulate the keys and data contained in the database.
215 @code{gdbm} allows an application to have multiple databases open at the
216 same time. When an application opens a @code{gdbm} database, it is
217 designated as a @code{reader} or a @code{writer}. A @code{gdbm}
218 database can be opened by at most one writer at a time. However, many readers
219 may open the database simultaneously. Readers and writers can not
220 open the @code{gdbm} database at the same time.
223 @chapter List of functions.
225 The following is a quick list of the functions contained in the @code{gdbm}
226 library. The include file @code{gdbm.h}, that can be included by the user,
227 contains a definition of these functions.
232 GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func);
233 void gdbm_close(dbf);
234 int gdbm_store(dbf, key, content, flag);
235 datum gdbm_fetch(dbf, key);
236 int gdbm_delete(dbf, key);
237 datum gdbm_firstkey(dbf);
238 datum gdbm_nextkey(dbf, key);
239 int gdbm_reorganize(dbf);
241 int gdbm_exists(dbf, key);
242 char *gdbm_strerror(errno);
243 int gdbm_setopt(dbf, option, value, size);
247 The @code{gdbm.h} include file is often in the @file{/usr/local/include}
248 directory. (The actual location of @code{gdbm.h} depends on your local
249 installation of @code{gdbm}.)
252 @chapter Opening the database.
254 @cindex opening the database
255 @cindex database, opening or creating
256 @deftypefn {gdbm interface} GDBM_FILE gdbm_open (const char *@var{name}, int @var{block_size}, @
257 int @var{flags}, int @var{mode}, void (*fatal_func)(const char *))
258 Initializes @code{gdbm} system. If the file has a size of zero bytes, a file
259 initialization procedure is performed, setting up the initial structure in the
266 The name of the file (the complete name, @code{gdbm} does not append any
267 characters to this name).
269 It is used during initialization to determine the size of various
270 constructs. It is the size of a single transfer from disk to
271 memory. This parameter is ignored if the file has been previously
272 initialized. The minimum size is 512. If the value is less than 512,
273 the file system block size is used, otherwise the value of
274 @var{block_size} is used.
278 @kwindex GDBM_WRCREAT
280 If @code{flags} is set to @samp{GDBM_READER}, the user wants to just read the
281 database and any call to @code{gdbm_store} or @code{gdbm_delete} will fail.
282 Many readers can access the database at the same time. If @code{flags} is
283 set to @samp{GDBM_WRITER}, the user wants both read and write access
284 to the database and requires exclusive access. If @code{flags} is set
285 to @samp{GDBM_WRCREAT}, the user wants both read and write access to
286 the database and wants it created if it does not already exist. If
287 @code{flags} is set to @samp{GDBM_NEWDB}, the user want a new database
288 created, regardless of whether one existed, and wants read and write
289 access to the new database.
294 The following may also be logically or'd into the database flags:
295 @samp{GDBM_SYNC}, which causes all database operations to be
296 synchronized to the disk, @samp{GDBM_NOLOCK}, which prevents the library
297 from performing any locking on the database file, and @samp{GDBM_NOMMAP},
298 which disables the memory mapping mechanism. The option @samp{GDBM_FAST} is
299 now obsolete, since @code{gdbm} defaults to no-sync mode.
301 @kwindex GDBM_CLOEXEC
302 @cindex close-on-exec
303 If the host @samp{open} call
305 (@uref{http://www.manpagez.com/man/2/open, open(2)})
308 (@pxref{open,,,open(2),open(2) man page})
310 supports the @samp{O_CLOEXEC} flag, the @samp{GDBM_CLOEXEC} can be
311 or'd into the flags, to enable the close-on-exec flag for the
312 database file descriptor.
316 @uref{http://www.manpagez.com/man/2/chmod},
319 @ref{chmod,,change permissions of a file,chmod(2),
324 @uref{http://www.manpagez.com/man/2/open}),
327 @pxref{open,,open a file,open(2), open(2) man page}),
329 which is used if the file is created).
331 A function for @code{gdbm} to call if it detects a fatal error. The only
332 parameter of this function is a string. If the value of @samp{NULL} is
333 provided, @code{gdbm} will use a default function.
336 The return value, is the pointer needed by all other functions to
337 access that @code{gdbm} file. If the return is the @samp{NULL} pointer,
338 @code{gdbm_open} was not successful. The errors can be found in
339 @code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). Available
340 error codes are discussed in @ref{Error codes}.
342 In all of the following calls, the parameter @var{dbf} refers to the pointer
343 returned from @code{gdbm_open}.
347 @chapter Closing the database.
348 @cindex closing database
349 @cindex database, closing
351 It is important that every file opened is also closed. This is needed to
352 update the reader/writer count on the file:
354 @deftypefn {gdbm interface} void gdbm_close (GDBM_FILE @var{dbf})
355 This function closes the @code{gdbm} file and frees all memory
356 associated with it. The parameter is:
360 The pointer returned by @code{gdbm_open}.
365 @chapter Inserting and replacing records in the database.
366 @cindex storing records
367 @cindex records, storing
369 @deftypefn {gdbm interface} int gdbm_store (GDBM_FILE @var{dbf}, datum @var{key}, @
370 datum @var{content}, int @var{flag})
371 The function @code{gdbm_store} inserts or replaces records in the database.
377 The pointer returned by @code{gdbm_open}.
381 The data to be associated with the key.
383 @kwindex GDBM_REPLACE
385 Defines the action to take when the key is already in the database. The value
386 @samp{GDBM_REPLACE} (defined in @file{gdbm.h}) asks that the old data
387 be replaced by the new @var{content}. The value @samp{GDBM_INSERT}
388 asks that an error be returned and no action taken if the @var{key}
392 This function can return the following values:
396 The item was not stored in the database because the caller was not an
397 official writer or either @var{key} or @var{content} have a
398 @samp{NULL} @samp{dptr} field.
400 Both @var{key} and @var{content} must have the @samp{dptr} field be a
401 non-@samp{NULL} value. Since a @samp{NULL} @samp{dptr} field is used by
402 other functions to indicate an error, it cannot be valid data.
404 The item was not stored because the argument @var{flag} was
405 @samp{GDBM_INSERT} and the @var{key} was already in the database.
407 No error. The value of @var{content} is keyed by @var{key}. The file
408 on disk is updated to reflect the structure of the new database before
409 returning from this function.
413 If you store data for a @var{key} that is already in the data base,
414 @code{gdbm} replaces the old data with the new data if called with
415 @samp{GDBM_REPLACE}. You do not get two data items for the same
416 @code{key} and you do not get an error from @code{gdbm_store}.
418 The size in @code{gdbm} is not restricted like @code{dbm} or @code{ndbm}. Your
419 data can be as large as you want.
422 @chapter Searching for records in the database.
423 @cindex fetching records
424 @cindex looking up records
425 @cindex record, fetching
427 @deftypefn {gdbm interface} datum gdbm_fetch (GDBM_FILE @var{dbf}, datum @var{key})
428 Looks up a given @var{key} and returns the information associated with it.
429 The @samp{dptr} field in the structure that is returned points to a
430 memory block allocated by @code{malloc}. It is the caller's
431 responsibility to free it when no longer needed.
433 If the @samp{dptr} is @samp{NULL}, no data was found.
439 The pointer returned by @code{gdbm_open}.
445 An example of using this function:
448 content = gdbm_fetch (dbf, key);
449 if (content.dptr == NULL)
451 fprintf(stderr, "key not found\n");
455 /* do something with content.dptr */
459 @cindex records, testing existence
460 You may also search for a particular key without retrieving it:
462 @deftypefn {gdbm interface} int gdbm_exists (GDBM_FILE @var{dbf}, datum @var{key})
463 Returns @samp{true} (@samp{1}) if the @var{key} exists in @var{dbf}
464 and @samp{false} (@samp{0}) otherwise.
470 The pointer returned by @code{gdbm_open}.
477 @chapter Removing records from the database.
478 @cindex deleting records
479 @cindex record, deleting
481 To remove some data from the database, use the @code{gdbm_delete}
484 @deftypefn {gdbm interface} int gdbm_delete (GDBM_FILE @var{dbf}, datum @var{key})
485 Deletes the data associated with the given @var{key}, if it exists in
486 the database @var{dbf}. The file on disk is updated to reflect the
487 structure of the new database before returning from this function.
493 The pointer returned by @code{gdbm_open}.
498 The function returns @samp{-1} if the item is not present or the
499 requester is a reader. The return of @samp{0} marks a successful delete.
503 @chapter Sequential access to records.
504 @cindex sequential access
505 @cindex iterating over records
506 @cindex records, iterating over
508 The next two functions allow for accessing all items in the database. This
509 access is not @code{key} sequential, but it is guaranteed to visit every
510 @code{key} in the database once. The order has to do with the hash values.
511 @code{gdbm_firstkey} starts the visit of all keys in the database.
512 @code{gdbm_nextkey} finds and reads the next entry in the hash structure for
515 @deftypefn {gdbm interface} datum gdbm_firstkey (GDBM_FILE @var{dbf})
516 Initiate sequential access to the database @var{dbf}. The returned
517 value is the first key accessed in the database. If the @samp{dptr}
518 field in the returned datum is @samp{NULL}, the database contains no
521 Otherwise, @samp{dptr} points to a memory block obtained from
522 @code{malloc}, which holds the key value. The caller is responsible
523 for freeing this memory block when no longer needed.
526 @deftypefn {gdbm interface} datum gdbm_nextkey (GDBM_FILE @var{dbf}, datum @var{prev})
527 This function continues the iteration over the keys in @var{dbf},
528 initiated by @code{gdbm_firstkey}. The parameter @var{prev} holds the
529 value returned from a previous call to @code{gdbm_nextkey} or
530 @code{gdbm_firstkey}.
532 The function returns next key from the database. If the @samp{dptr}
533 field in the returned datum is @samp{NULL}, all keys in the database
536 Otherwise, @samp{dptr} points to a memory block obtained from
537 @code{malloc}, which holds the key value. The caller is responsible
538 for freeing this memory block when no longer needed.
541 @cindex iteration loop
542 These functions were intended to visit the database in read-only algorithms,
543 for instance, to validate the database or similar operations. The
544 usual algorithm for sequential access is:
548 key = gdbm_firstkey (dbf);
553 /* do something with the key */
556 /* Obtain the next key */
557 nextkey = gdbm_nextkey (dbf, key);
558 /* Reclaim the memory used by the key */
560 /* Use nextkey in the next iteration. */
566 @cindex iteration and @code{gdbm_delete}
567 @cindex deletion in iteration loops
568 @cindex @code{gdbm_delete} and sequential access
569 Care should be taken when the @code{gdbm_delete} function is used in
570 such a loop. File visiting is based on a @dfn{hash table}. The
571 @code{gdbm_delete} function re-arranges the hash table to make sure
572 that any collisions in the table do not leave some item
573 @dfn{un-findable}. The original key order is @emph{not} guaranteed to
574 remain unchanged in all instances. So it is possible that some key
575 will not be visited if a loop like the following is executed:
579 key = gdbm_firstkey (dbf);
585 gdbm_delete (dbf, key);
587 nextkey = gdbm_nextkey (dbf, key);
595 @chapter Database reorganization.
596 @cindex database reorganization
597 @cindex reorganization, database
599 The following function should be used very seldom.
601 @deftypefn {gdbm interface} int gdbm_reorganize (GDBM_FILE @var{dbf})
602 Reorganizes the database.
608 The pointer returned by @code{gdbm_open}.
612 If you have had a lot of deletions and would like to shrink the space
613 used by the @code{gdbm} file, this function will reorganize the database.
614 This results, in particular, in shortening the length of a @code{gdbm}
615 file by removing the space occupied by deleted records.
617 This reorganization requires creating a new file and inserting all the elements
618 in the old file @var{dbf} into the new file. The new file is then renamed to
619 the same name as the old file and @var{dbf} is updated to contain all the
620 correct information about the new file. If an error is detected, the return
621 value is negative. The value zero is returned after a successful
625 @chapter Database Synchronization
626 @cindex database synchronization
627 @cindex synchronization, database
630 Unless your database was opened with the @samp{GDBM_SYNC} flag,
631 @code{gdbm} does not wait for writes to be flushed to the disk before
632 continuing. This allows for faster writing of databases at the risk
633 of having a corrupted database if the application terminates in an
634 abnormal fashion. The following function allows the programmer to
635 make sure the disk version of the database has been completely updated
636 with all changes to the current time.
638 @deftypefn {gdbm interface} void gdbm_sync (GDBM_FILE @var{dbf})
639 Synchronizes the changes in @var{dbf} with its disk file. The
640 parameter is a pointer returned by @code{gdbm_open}.
642 This function would usually be called after a complete set of changes
643 have been made to the database and before some long waiting time.
644 The @code{gdbm_close} function automatically calls the equivalent of
645 @code{gdbm_sync} so no call is needed if the database is to be closed
646 immediately after the set of changes have been made.
650 @chapter Export and Import
651 @cindex Flat file format
654 @code{Gdbm} databases can be converted into a portable @dfn{flat
655 format}. This format can be used, for example, to migrate between
656 the different versions of @code{gdbm} databases. Generally speaking,
657 flat files are safe to send over the network, and can be used to
658 recreate the database on another machine. The recreated database is
659 guaranteed to be a byte-to-byte equivalent of the database from which
660 the flat file was created. This does not necessarily mean, however,
661 that this file can be used in the same way as the original one. For
662 example, if the original database contained non-@acronym{ASCII} data
663 (e.g. @acronym{C} structures, integers etc.), the recreated database
664 can be of any use only if the target machine has the same integer
665 size and byte ordering as the source one and if its @acronym{C}
666 compiler uses the same packing conventions as the one which generated
667 @acronym{C} which populated the original database. In general, such
668 binary databases are not portable between machines, unless you follow
669 some stringent rules on what data is written to them and how it is
672 @deftypefn {gdbm interface} int gdbm_export (GDBM_FILE @var{dbf}, @
673 const char *@var{exportfile}, int @var{flag}, int @var{mode})
674 Create a flat file from the @code{gdbm} database. The parameters are:
678 A pointer to the source database, returned by a call to
679 @code{gdbm_open}. The database must be open in @samp{GDBM_WRITER} mode.
682 The name of the output file.
685 @kwindex GDBM_WRCREAT
687 How to create the output file. If @var{flag} is @samp{GDBM_WRCREAT},
688 the file will be created if it does not exist already. Otherwise, if
689 it is @samp{GDBM_NEWDB}, it will be created if it does not exist, and
693 The permissions to use when creating the output file.
695 @uref{http://www.manpagez.com/man/2/open},
698 @ref{open,,open a file,open(2), open(2) man page},
700 for a detailed discussion.
704 @deftypefn {gdbm interface} int gdbm_import (GDBM_FILE @var{dbf}, @
705 const char *@var{importfile}, int @var{flag})
706 Populates the database from an existing flat file.
710 A pointer to the source database, returned by a call to
711 @code{gdbm_open}. The database must be open in @samp{GDBM_WRITER} mode.
714 The name of the input flat file. The file must exist.
717 The @var{flag} argument to be passed to @code{gdbm_store} function
718 when adding new records. @xref{Store}, for a description of its
723 See also @ref{gdbmexport}, @ref{testgdbm export}, and
724 @ref{testgdbm import}.
727 @chapter Error strings.
728 @cindex error strings
730 To convert a @code{gdbm} error code into English text, use this
733 @deftypefn {gdbm interface} {const char *} gdbm_strerror (gdbm_error @var{errno})
734 Converts @var{errno} (which is an integer value) into a human-readable
735 descriptive text. Returns a pointer to a static string. The caller
736 must not alter or free the returned pointer.
738 The @var{errno} argument is usually the value of the global variable
739 @code{gdbm_errno}. @xref{Variables, gdbm_errno}.
743 @chapter Setting options
744 @cindex database options
745 @cindex options, database
747 @code{Gdbm} supports the ability to set certain options on an already
750 @deftypefn {gdbm interface} int gdbm_setopt (GDBM_FILE @var{dbf}, int @var{option}, @
751 void *@var{value}, int @var{size})
752 Sets an option on the database or returns the value of an option.
758 The pointer returned by @code{gdbm_open}.
760 The option to be set or retreived.
762 A pointer to the value to which @var{option} will be set or where to
763 place the option value (depending on the option).
765 The length of the data pointed to by @var{value}.
769 The valid options are:
772 @kwindex GDBM_CACHESIZE
773 @kwindex GDBM_SETCACHESIZE
774 @item GDBM_SETCACHESIZE
775 @itemx GDBM_CACHESIZE
776 Set the size of the internal bucket cache. This option may only be
777 set once on each GDBM_FILE descriptor, and is set automatically to 100
778 upon the first access to the database. The @var{value} should point
779 to a @code{size_t} holding the desired cache size.
781 The @samp{GDBM_CACHESIZE} option is provided for compatibility with
784 @kwindex GDBM_GETCACHESIZE
785 @item GDBM_GETCACHESIZE
786 Return the size of the internal bucket cache. The @var{value} should
787 point to a @code{size_t} variable, where the size will be stored.
789 @kwindex GDBM_GETFLAGS
791 Return the flags describing the state of the database. The @var{value} should
792 point to a @code{int} variable where to store the flags. The return
793 is the same as the flags used when opening the database (@pxref{Open,
794 gdbm_open}), except that it reflects the current state (which may have
795 been altered by another calls to @code{gdbm_setopt}.
797 @kwindex GDBM_FASTMODE
799 Enable or disable the @dfn{fast writes mode}, i.e. writes without
800 subsequent synchronization. The @var{value} should point
801 to an integer: @samp{TRUE} to enable fast mode, and @samp{FALSE} to
804 This option is retained for compatibility with previous versions of
805 @code{gdbm}. Its effect is the reverse of @code{GDBM_SETSYNCMODE}
808 @kwindex GDBM_SETSYNCMODE
809 @kwindex GDBM_SYNCMODE
810 @item GDBM_SETSYNCMODE
812 Turn on or off file system synchronization operations. This
813 setting defaults to off. The @var{value} should point
814 to an integer: @samp{TRUE} to turn synchronization on, and @samp{FALSE} to
817 Note, that this option is a reverse of @code{GDBM_FASTMODE},
818 i.e. calling @code{GDBM_SETSYNCMODE} with @samp{TRUE} has the same effect
819 as calling @code{GDBM_FASTMODE} with @samp{FALSE}.
821 The @samp{GDBM_SYNCMODE} option is provided for compatibility with
824 @kwindex GDBM_GETSYNCMODE
825 @item GDBM_GETSYNCMODE
826 Return the current synchronization status. The @var{value} should
827 point to an @code{int} where the status will be stored.
829 @kwindex GDBM_SETCENTFREE
830 @kwindex GDBM_CENTFREE
831 @item GDBM_SETCENTFREE
833 @emph{NOTICE: This feature is still under study.}
835 Set central free block pool to either on or off. The default is off,
836 which is how previous versions of @code{gdbm} handled free blocks. If
837 set, this option causes all subsequent free blocks to be placed in the
838 @emph{global} pool, allowing (in theory) more file space to be reused
839 more quickly. The @var{value} should point to an integer: @samp{TRUE} to
840 turn central block pool on, and @samp{FALSE} to turn it off.
842 The @samp{GDBM_CENTFREE} option is provided for compatibility with
845 @kwindex GDBM_SETCOALESCEBLKS
846 @kwindex GDBM_COALESCEBLKS
847 @item GDBM_SETCOALESCEBLKS
848 @itemx GDBM_COALESCEBLKS
849 @emph{NOTICE: This feature is still under study.}
851 Set free block merging to either on or off. The default is off, which
852 is how previous versions of @code{gdbm} handled free blocks. If set,
853 this option causes adjacent free blocks to be merged. This can become
854 a @acronym{CPU} expensive process with time, though, especially if
855 used in conjunction with GDBM_CENTFREE. The @var{value} should point
856 to an integer: @samp{TRUE} to turn free block merging on, and @samp{FALSE} to
859 @kwindex GDBM_GETCOALESCEBLKS
860 @item GDBM_GETCOALESCEBLKS
861 Return the current status of free block merging. The @var{value} should
862 point to an @code{int} where the status will be stored.
864 @kwindex GDBM_SETMAXMAPSIZE
865 @item GDBM_SETMAXMAPSIZE
866 Sets maximum size of a memory mapped region. The @var{value} should
867 point to a value of type @code{size_t}, @code{unsigned long} or
868 @code{unsigned}. The actual value is rounded to the nearest page
869 boundary (the page size is obtained from
870 @code{sysconf(_SC_PAGESIZE)}).
872 @kwindex GDBM_GETMAXMAPSIZE
873 @item GDBM_GETMAXMAPSIZE
874 Return the maximum size of a memory mapped region. The @var{value} should
875 point to a value of type @code{size_t} where to return the data.
877 @kwindex GDBM_SETMMAP
879 Enable or disable memory mapping mode. The @var{value} should point
880 to an integer: @samp{TRUE} to enable memory mapping or @samp{FALSE} to
883 @kwindex GDBM_GETMMAP
885 Check whether memory mapping is enabled. The @var{value} should point
886 to an integer where to return the status.
888 @kwindex GDBM_GETDBNAME
890 Return the name of the database disk file. The @var{value} should
891 point to a variable of type @code{char**}. A pointer to the newly
892 allocated copy of the file name will be placed there. The caller is
893 responsible for freeing this memory when no longer needed. For
899 if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
901 fprintf (stderr, "gdbm_setopt failed: %s\n",
902 gdbm_strerror (gdbm_errno));
906 printf ("database name: %s\n", name);
913 The return value will be @samp{-1} upon failure, or @samp{0} upon
914 success. The global variable @code{gdbm_errno} will be set upon failure.
916 For instance, to set a database to use a cache of 10, after opening it
917 with @code{gdbm_open}, but prior to accessing it in any way, the following
923 ret = gdbm_setopt (dbf, GDBM_CACHESIZE, &value, sizeof (int));
928 @chapter File Locking.
932 With locking disabled (if @code{gdbm_open} was called with @samp{GDBM_NOLOCK}),
933 the user may want to perform their own file locking on the database file
934 in order to prevent multiple writers operating on the same file
937 In order to support this, the @code{gdbm_fdesc} routine is provided.
939 @deftypefn {gdbm interface} int gdbm_fdesc (GDBM_FILE @var{dbf})
940 Returns the file descriptor of the database @var{dbf}. This value
941 can be used as an argument to @code{flock}, @code{lockf} or similar
946 @chapter Test and modify a GDBM database.
949 The @command{testgdbm} utility allows you to view and modify an
950 existing @acronym{GDBM} database or to create a new one.
952 @cindex default database, @command{testgdbm}
953 @cindex @option{-g}, @command{testgdbm} option
955 When invoked without options, it tries to open a database file called
956 @file{junk.gdbm}, located in the current working directory. You can
957 change this default using the @option{-g} command line option. This
958 option takes a single argument, specifying the file name to open, e.g.:
961 $ testgdbm -g file.db
964 @cindex read-only mode, @command{testgdbm}
965 @cindex @option{-r}, @command{testgdbm} option
966 The database will be opened in read-write mode, unless the @option{-r}
967 option is specified, in which case it will be opened only for reading.
969 @cindex creating a database, @command{testgdbm}
970 @cindex @option{-n}, @command{testgdbm} option
971 If the database does not exist, @command{testgdbm} will create it.
972 There is a special option @option{-n}, which instructs the utility to
973 create a new database. If it is used and if the database already
974 exists, it will be deleted, so use it sparingly.
982 @section testgdbm invocation
983 @cindex command line options, @command{testgdbm}
985 The following table summarizes all @command{testgdbm} command line
994 Operate on @var{file} instead of the default @file{junk.gdbm}.
996 Print a concise help summary.
1000 Open the database in read-only mode.
1002 Synchronize to the disk after each write.
1004 Print program version and licensing information and exit.
1008 @section testgdbm interactive mode
1009 @cindex interactive mode, @command{testgdbm}
1011 After successful startup, @command{testgdbm} starts a loop, in which
1012 it reads commands from the user, executes them and prints the results
1013 on the standard output. If the standard input is attached to a console,
1014 @command{testgdbm} runs in interactive mode, which is indicated by its
1021 The utility finishes when it reads the @samp{quit} command (see below) or
1022 detects end-of-file on its standard input, whichever occurs first.
1024 A @command{testgdbm} command consists of a @dfn{command verb},
1025 optionally followed by one or two @dfn{arguments}, separated by any
1026 amount of white space. A command verb can be entered either in full
1027 or in an abbreviated form, as long as that abbreviation does not match
1028 any other verb. For example, @samp{co} can be used instead of
1029 @samp{count} and @samp{ca} instead of @samp{cache}. Furthermore,
1030 many command verbs also have single-letter forms, called @dfn{command
1033 An argument is any sequence of non-whitespace characters. Notice,
1034 that currently there is no way to enter arguments containing white
1035 space. This limitation will be removed in future releases.
1037 Each command takes at most two @dfn{formal parameters}, which can be
1038 optional or mandatory. If the number of actual arguments is less than the
1039 number of mandatory parameters, @command{testgdbm} will prompt you to
1040 supply missing arguments. For example, the @samp{store} command takes two
1041 mandatory parameters, so if you invoked it with no arguments, you
1042 would be prompted twice to supply the necessary data, as shown in
1046 testgdbm> @kbd{store}
1051 However, such prompting is possible only in interactive mode. In
1052 non-interactive mode (e.g. when running a script), all arguments must
1053 be supplied with each command, otherwise @command{testgdbm} will report an
1054 error and exit immediately.
1057 @cindex pager, @command{testgdbm}
1059 Some commands produce excessive amounts of output. To help you follow
1060 it, @command{testgdbm} uses a pager utility to display such
1061 output. The name of the pager utility is taken from the environment
1062 variable @env{PAGER}. The pager is invoked only in interactive mode
1063 and only if the estimated number of output lines is greater then the
1064 number of lines on your screen.
1066 @anchor{nul-termination}
1067 Many of the @command{testgdbm} commands operate on database key and
1068 data values. The utility assumes that both keys and data are
1069 @acronym{ASCII} strings, either nul-terminated or not. By default,
1070 it is assumed that strings are nul-terminated. You can change this
1071 by using @code{z} (@code{key-zero}, for keys) and @code{Z}
1072 (@code{data-zero}, for data) commands.
1074 The following table summarizes all available commands:
1076 @deffn {command verb} count
1077 @deffnx {command abbrev} co
1078 @deffnx {command letter} c
1079 Print the number of entries in the database.
1082 @deffn {command verb} delete @var{key}
1083 @deffnx {command abbrev} de @var{key}
1084 @deffnx {command letter} d @var{key}
1085 Delete entry with a given @var{key}
1088 @anchor{testgdbm export}
1089 @deffn {command verb} export @var{file-name} [truncate]
1090 @deffnx {command abbrev} e @var{file-name} [truncate]
1091 Export the database to the flat file @var{file-name}. @xref{Flat files},
1092 for a description of the flat file format and its purposes. This
1093 command will not overwrite an existing file, unless the word
1094 @samp{truncate} is given as its second argument.
1096 See also @ref{gdbmexport}.
1099 @deffn {command verb} fetch @var{key}
1100 @deffnx {command abbrev} fe @var{key}
1101 @deffnx {command letter} f @var{key}
1102 Fetch and display a record with the given @var{key}.
1105 @anchor{testgdbm import}
1106 @deffn {command verb} import @var{file-name} [replace]
1107 @deffnx {command abbrev} i @var{file-name} [replace]
1108 Import data from a flat dump file @var{file-name}
1109 (@pxref{Flat files}). If the word @samp{replace} is given
1110 as the second argument, any records with the same keys as the already
1111 existing ones will replace them.
1114 @deffn {command verb} list
1115 @deffnx {command abbrev} l
1116 List the contents of the database (@pxref{pager}).
1119 @deffn {command verb} next [@var{key}]
1120 @deffnx {command abbrev} n [@var{key}]
1121 Sequential access: fetch and display a next record. If @var{key} is
1122 given, a record following one with this key will be fetched.
1123 Otherwise, the key supplied by the latest @code{1}, @code{2} or
1124 @var{n} command will be used.
1126 See also @code{first}, below.
1128 @xref{Sequential}, for more information on sequential access.
1131 @deffn {command verb} quit
1132 @deffnx {command abbrev} q
1133 Close the database and quit the utility.
1136 @deffn {command verb} store @var{key} @var{data}
1137 @deffnx {command abbrev} sto @var{key} @var{data}
1138 @deffnx {command letter} s @var{key} @var{data}
1139 Store the @var{data} with @var{key} in the database. If @var{key}
1140 already exists, its data will be replaced.
1143 @deffn {command verb} first
1144 @deffnx {command abbrev} fi
1145 @deffnx {command letter} 1
1146 Fetch and display the first record in the database. Subsequent
1147 records can be fetched using @code{next} command (see above).
1148 @xref{Sequential}, for more information on sequential access.
1151 @deffn {command verb} read @var{file} [replace]
1152 @deffnx {command abbrev} rea @var{file} [replace]
1153 @deffnx {command letter} < @var{file} [replace]
1154 Read entries from @var{file} and store them in the database. If the
1155 word @samp{replace} is given as the second argument, any existing
1156 records with matching keys will be replaced.
1159 @deffn {command verb} reorganize
1160 @deffnx {command abbrev} reo
1161 @deffnx {command letter} r
1162 Reorganize the database (@pxref{Reorganization}).
1165 @deffn {command verb} key-zero
1166 @deffnx {command abbrev} k
1167 @deffnx {command letter} z
1168 Toggle key nul-termination. Use @code{status} to inspect the current
1169 state. @xref{nul-termination}.
1172 @deffn {command verb} avail
1173 @deffnx {command abbrev} a
1174 @deffnx {command letter} A
1175 Print the @dfn{avail list}.
1178 @deffn {command verb} bucket
1179 @deffnx {command abbrev} b
1180 @deffnx {command letter} B
1181 Print the bucket number @var{num}.
1184 @deffn {command verb} current
1185 @deffnx {command abbrev} cu
1186 @deffnx {command letter} C
1187 Print the current bucket.
1190 @deffn {command verb} dir
1191 @deffnx {command abbrev} di
1192 @deffnx {command letter} D
1193 Print hash directory.
1196 @deffn {command verb} header
1197 @deffnx {command abbrev} hea
1198 @deffnx {command letter} F
1202 @deffn {command verb} hash @var{key}
1203 @deffnx {command abbrev} ha @var{key}
1204 @deffnx {command letter} H @var{key}
1205 Compute and display the hash value for the given @var{key}.
1208 @deffn {command verb} cache
1209 @deffnx {command abbrev} ca
1210 @deffnx {command letter} K
1211 Print the bucket cache.
1214 @deffn {command verb} status
1215 @deffnx {command abbrev} sta
1216 @deffnx {command letter} S
1217 Print current program status. The following example shows the
1218 information displayed:
1221 Database file: junk.gdbm
1222 Zero terminated keys: yes
1223 Zero terminated data: yes
1227 @deffn {command verb} version
1228 @deffnx {command abbrev} v
1229 Print the version of @command{gdbm}.
1232 @deffn {command verb} data-zero
1233 @deffnx {command abbrev} da
1234 @deffnx {command letter} Z
1235 Toggle data nul-termination. Use @code{status} to examine the current
1238 @xref{nul-termination}.
1241 @deffn {command verb} help
1242 @deffnx {command abbrev} hel
1243 @deffnx {command letter} ?
1244 Print a concise command summary, showing each command letter and verb
1245 with its parameters and a short description of what it does. Optional
1246 arguments are enclosed in square brackets.
1250 @chapter Export a database into a portable format.
1253 The @command{gdbmexport} utility converts the database into a portable
1254 @dfn{flat format}. Files in this format can be used to populate
1255 databases using the @code{gdbm_import} function (@pxref{Flat files,
1256 gdbm_import}) or the @code{i} command of @command{testgdbm} utility
1257 (@pxref{testgdbm import}). In many cases files in this format are suitable for
1258 sending over the network to populate the database on another machine.
1259 The only exception to this are databases whose records contain
1260 non-@acronym{ASCII} data (e.g. @acronym{C} structures, integers
1261 etc.). For such databases you will be better off by writing a
1262 specialized utility to convert them to an architecture-independent
1265 If @command{gdbmexport} is linked with @file{libgdbm}
1266 version 1.8.3, it can be used to convert databases from old to new
1269 The utility takes two mandatory arguments: the name of the database
1270 file to convert and the output file name, e.g.:
1273 $ gdbmexport junk.gdbm junk.flat
1276 In addition two options are understood:
1280 Display short usage summary and exit.
1283 Display program version and licensing information, and exit.
1287 @chapter Useful global variables.
1289 The following global variables and constants are available:
1291 @deftypevar gdbm_error gdbm_errno
1292 This variable contains error code from the last failed @code{gdbm}
1293 call. @xref{Error codes}, for a list of available error codes and
1296 Use @code{gdbm_strerror} (@pxref{Errors}) to convert it to a
1300 @deftypevar {const char *} gdbm_errlist[]
1301 This variable is an array of error descriptions, which is used by
1302 @code{gdbm_strerror} to convert error codes to human-readable text
1303 (@pxref{Errors}). You can access it directly, if you wish so. It
1304 contains @code{_GDBM_MAX_ERRNO + 1} elements and can be directly
1305 indexed by the error code to obtain a corresponding descriptive
1309 @defvr {Constant} _GDBM_MIN_ERRNO
1310 The minimum error code used by @code{gdbm}.
1313 @defvr {Constant} _GDBM_MAX_ERRNO
1314 The maximum error code used by @code{gdbm}.
1317 @cindex version number
1318 @deftypevar {const char *} gdbm_version
1319 A string containing the version information.
1322 @deftypevar {int const} gdbm_version_number[3]
1323 This variable contains the @code{gdbm} version numbers:
1325 @multitable @columnfractions 0.4 0.5
1326 @headitem Index @tab Meaning
1327 @item 0 @tab Major number
1328 @item 1 @tab Minor number
1329 @item 2 @tab Patchlevel number
1332 Additionally, the following constants are defined in the @file{gdbm.h}
1336 @kwindex GDBM_VERSION_MAJOR
1337 @item GDBM_VERSION_MAJOR
1340 @kwindex GDBM_VERSION_MINOR
1341 @item GDBM_VERSION_MINOR
1344 @kwindex GDBM_VERSION_PATCH
1345 @item GDBM_VERSION_PATCH
1349 These can be used to verify whether the header file matches the library.
1352 To compare two split-out version numbers, use the following function:
1354 @deftypefn {gdbm interface} int gdbm_version_cmp (int const @var{a}[3], @
1355 int const @var{b}[3])
1356 Compare two version numbers. Return @samp{-1} if @var{a} is less than
1357 @var{b}, @samp{1} if @var{a} is greater than @var{b} and @samp{0} if
1360 Comparison is done from left to right, so that:
1365 gdbm_version_cmp (a, b) @result{} 0
1369 gdbm_version_cmp (a, b) @result{} 1
1373 gdbm_version_cmp (a, b) @result{} -1
1378 @chapter Error codes
1381 This chapter summarizes the error codes which can be set by the
1382 functions in @code{gdbm} library.
1385 @kwindex GDBM_NO_ERROR
1389 @kwindex GDBM_MALLOC_ERROR
1390 @item GDBM_MALLOC_ERROR
1391 Memory allocation failed. Not enough memory.
1393 @kwindex GDBM_BLOCK_SIZE_ERROR
1394 @item GDBM_BLOCK_SIZE_ERROR
1395 This error is set by the @code{gdbm_open} function (@pxref{Open}), if
1396 the value of its @var{block_size} argument is incorrect.
1398 @kwindex GDBM_FILE_OPEN_ERROR
1399 @item GDBM_FILE_OPEN_ERROR
1400 The library was not able to open a disk file. This can be set by
1401 @code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
1402 @code{gdbm_import} functions (@pxref{Flat files}).
1404 Inspect the value of the system @code{errno} variable to get more
1405 detailed diagnostics.
1407 @kwindex GDBM_FILE_WRITE_ERROR
1408 @item GDBM_FILE_WRITE_ERROR
1409 Writing to a disk file failed. This can be set by
1410 @code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
1411 @code{gdbm_import} functions.
1413 Inspect the value of the system @code{errno} variable to get more
1414 detailed diagnostics.
1416 @kwindex GDBM_FILE_SEEK_ERROR
1417 @item GDBM_FILE_SEEK_ERROR
1418 Positioning in a disk file failed. This can be set by
1419 @code{gdbm_open} (@pxref{Open}) function.
1421 Inspect the value of the system @code{errno} variable to get a more
1422 detailed diagnostics.
1424 @kwindex GDBM_FILE_READ_ERROR
1425 @item GDBM_FILE_READ_ERROR
1426 Reading from a disk file failed. This can be set by
1427 @code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
1428 @code{gdbm_import} functions.
1430 Inspect the value of the system @code{errno} variable to get a more
1431 detailed diagnostics.
1433 @kwindex GDBM_BAD_MAGIC_NUMBER
1434 @item GDBM_BAD_MAGIC_NUMBER
1435 The file given as argument to @code{gdbm_open} function is not a valid
1436 @code{gdbm} file: it has a wrong magic number.
1438 @kwindex GDBM_EMPTY_DATABASE
1439 @item GDBM_EMPTY_DATABASE
1440 The file given as argument to @code{gdbm_open} function is not a valid
1441 @code{gdbm} file: it has zero length.
1443 @kwindex GDBM_CANT_BE_READER
1444 @item GDBM_CANT_BE_READER
1445 This error code is set by the @code{gdbm_open} function if it is not
1446 able to lock file when called in @samp{GDBM_READER} mode (@pxref{Open,
1449 @kwindex GDBM_CANT_BE_WRITER
1450 @item GDBM_CANT_BE_WRITER
1451 This error code is set by the @code{gdbm_open} function if it is not
1452 able to lock file when called in writer mode (@pxref{Open}).
1454 @kwindex GDBM_READER_CANT_DELETE
1455 @item GDBM_READER_CANT_DELETE
1456 Set by the @code{gdbm_delete} (@pxref{Delete}) if it attempted to
1457 operate on a database that is open in read-only mode (@pxref{Open,
1460 @kwindex GDBM_READER_CANT_STORE
1461 @item GDBM_READER_CANT_STORE
1462 Set by the @code{gdbm_store} (@pxref{Store}) if it attempted to
1463 operate on a database that is open in read-only mode (@pxref{Open,
1466 @kwindex GDBM_READER_CANT_REORGANIZE
1467 @item GDBM_READER_CANT_REORGANIZE
1468 Set by the @code{gdbm_reorganize} (@pxref{Reorganization}) if it attempted to
1469 operate on a database that is open in read-only mode (@pxref{Open,
1472 @kwindex GDBM_UNKNOWN_UPDATE
1473 @item GDBM_UNKNOWN_UPDATE
1474 Currently unused. Reserved for future uses.
1476 @kwindex GDBM_ITEM_NOT_FOUND
1477 @item GDBM_ITEM_NOT_FOUND
1478 Requested item was not found. This error is set by @code{gdbm_delete}
1479 (@pxref{Delete}) and @code{gdbm_fetch} (@pxref{Fetch}) when the requested
1480 @var{key} value is not found in the database.
1482 @kwindex GDBM_REORGANIZE_FAILED
1483 @item GDBM_REORGANIZE_FAILED
1484 The @code{gdbm_reorganize} function is not
1485 able to create a temporary database. @xref{Reorganization}.
1487 @kwindex GDBM_CANNOT_REPLACE
1488 @item GDBM_CANNOT_REPLACE
1489 Cannot replace existing item. This error is set by the
1490 @code{gdbm_store} if the requested @var{key} value is found in the
1491 database and the @var{flag} parameter is not @samp{GDBM_REPLACE}.
1492 @xref{Store}, for a detailed discussion.
1494 @kwindex GDBM_ILLEGAL_DATA
1495 @item GDBM_ILLEGAL_DATA
1496 Either @var{key} or @var{content} parameter was wrong in a call to
1497 to @code{gdbm_store} (@pxref{Store}).
1499 @kwindex GDBM_OPT_ALREADY_SET
1500 @item GDBM_OPT_ALREADY_SET
1501 Requested option can be set only once and was already set. This error
1502 is returned by the @code{gdbm_setopt} function. @xref{Options,
1505 @kwindex GDBM_OPT_ILLEGAL
1506 @item GDBM_OPT_ILLEGAL
1507 The @var{option} argument is not valid or the @var{value} argument
1508 points to an invalid value in a call to @code{gdbm_setopt} function.
1511 @kwindex GDBM_BYTE_SWAPPED
1512 @item GDBM_BYTE_SWAPPED
1513 The @code{gdbm_open} function (@pxref{Open}) attempts to open a
1514 database which is created on a machine with different byte ordering.
1516 @kwindex GDBM_BAD_FILE_OFFSET
1517 @item GDBM_BAD_FILE_OFFSET
1518 The @code{gdbm_open} function (@pxref{Open}) sets this error code if
1519 the file it tries to open has a wrong magic number.
1521 @kwindex GDBM_BAD_OPEN_FLAGS
1522 @item GDBM_BAD_OPEN_FLAGS
1523 Set by the @code{gdbm_export} function if supplied an invalid
1524 @var{flags} argument. @xref{Flat files}.
1526 @kwindex GDBM_FILE_STAT_ERROR
1527 @item GDBM_FILE_STAT_ERROR
1528 Getting information about a disk file failed. The system @code{errno}
1529 will give more details about the error.
1531 This error can be set by the following functions: @code{gdbm_open},
1532 @code{gdbm_reorganize}.
1534 @kwindex GDBM_FILE_EOF
1536 End of file was encountered where more data was expected to be
1537 present. This error can occur when fetching data from the database
1538 and usually means that the database is truncated or otherwise corrupted.
1540 This error can be set by any GDBM function that does I/O. Some of
1541 these functions are: @code{gdbm_delete}, @code{gdbm_exists},
1542 @code{gdbm_fetch}, @code{gdbm_export}, @code{gdbm_import},
1543 @code{gdbm_reorganize}, @code{gdbm_firstkey}, @code{gdbm_nextkey},
1548 @chapter Compatibility with standard @code{dbm} and @code{ndbm}.
1550 @cindex compatibility layer
1551 @code{Gdbm} includes a compatibility layer, which provides traditional
1552 @samp{ndbm} and older @samp{dbm} functions. The layer is compiled and
1553 installed if the @option{--enable-libgdbm-compat} option is used when
1554 configuring the package.
1558 @findex libgdbm_compat
1559 The compatibility layer consists of two header files: @file{ndbm.h}
1560 and @file{dbm.h} and the @file{libgdbm_compat} library.
1562 Older programs using @code{ndbm} or @code{dbm} interfaces can
1563 use @file{libgdbm_compat} without any changes. To link a program with
1564 the compatibility library, add the following two options to the
1565 @command{cc} invocation: @option{-lgdbm -lgdbm_compat}. The @option{-L}
1566 option may also be required, depending on where @code{gdbm} is
1570 cc ... -L/usr/local/lib -lgdbm -lgdbm_compat
1573 @cindex @samp{dir} file
1574 @cindex @samp{pag} file
1575 Databases created and manipulated by the compatibility interfaces
1576 consist of two different files: @file{@var{file}.dir} and
1577 @file{@var{file}.pag}. This is required by the @acronym{POSIX}
1578 specification and corresponds to the traditional usage. Note,
1579 however, that despite the similarity of the naming convention,
1580 actual data stored in these files has not the same format as
1581 in the databases created by other @code{dbm} or @code{ndbm}
1582 libraries. In other words, you cannot access a standard UNIX
1583 @code{dbm} file with GNU @code{dbm}!
1585 GNU @code{dbm} files are not @code{sparse}. You can copy them with
1586 the usual @code{cp} command and they will not expand in the copying
1590 * ndbm:: NDBM interface functions.
1591 * dbm:: DBM interface functions.
1595 @section NDBM interface functions.
1596 @cindex NDBM functions
1598 The functions below implement the @acronym{POSIX} @samp{ndbm} interface:
1600 @deftypefn {ndbm} {DBM *} dbm_open (char *@var{file}, int @var{flags}, int @var{mode})
1601 Opens a database. The @var{file} argument is the full name of the
1602 database file to be opened. The function opens two files:
1603 @file{@var{file}.pag} and @file{@var{file}.dir}. The @var{flags} and
1604 @var{mode} arguments have the same meaning as the second and third
1607 @uref{http://www.manpagez.com/man/2/open,,open(2)},
1610 @code{open} (@pxref{open,,open a file,open(2), open(2) man page}),
1612 except that a database opened for write-only access opens the files
1613 for read and write access and the behavior of the @code{O_APPEND} flag is
1616 The function returns a pointer to the @code{DBM} structure describing
1617 the database. This pointer is used to refer to this database in all
1618 operations described below.
1620 Any error detected will cause a return value of @samp{NULL} and an
1621 appropriate value will be stored in @code{gdbm_errno}
1622 (@pxref{Variables}).
1625 @deftypefn {ndbm} void dbm_close (DBM *@var{dbf})
1626 Closes the database. The @var{dbf} argument must be a pointer
1627 returned by an earlier call to @code{dbm_open}.
1630 @deftypefn {ndbm} datum dbm_fetch (DBM *@var{dbf}, datum @var{key})
1631 Reads a record from the database with the matching key. The @var{key}
1632 argument supplies the key that is being looked for.
1634 If no matching record is found, the @code{dptr} member of the returned
1635 datum is @samp{NULL}. Otherwise, the @code{dptr} member of the
1636 returned datum points to the memory managed by the compatibility
1637 library. The application should never free it.
1640 @deftypefn {ndbm} int dbm_store (DBM *@var{dbf}, datum @var{key}, @
1641 datum @var{content}, int @var{mode})
1642 Writes a key/value pair to the database. The argument @var{dbf} is a
1643 pointer to the @code{DBM} structure returned from a call to
1644 @code{dbm_open}. The @var{key} and @var{content} provide the values
1645 for the record key and content. The @var{mode} argument controls
1646 the behavior of @code{dbm_store} in case a matching record already
1647 exists in the database. It can have one of the following two values:
1650 @kwindex DBM_REPLACE
1652 Replace existing record with the new one.
1656 The existing record is left unchanged, and the function returns
1660 If no matching record exists in the database, new record will be
1661 inserted no matter what the value of the @var{mode} is.
1664 @deftypefn {ndbm} int dbm_delete (DBM *@var{dbf}, datum @var{key})
1665 Deletes the record with the matching key from the database. If the
1666 function succeeds, @samp{0} is returned. Otherwise, if no matching
1667 record is found or if an error occurs, @samp{-1} is returned.
1670 @deftypefn {ndbm} datum dbm_firstkey (DBM *@var{dbf})
1671 Initializes iteration over the keys from the database and returns
1672 the first key. Note, that the word @samp{first} does not imply any
1673 specific ordering of the keys.
1675 If there are no records in the database, the @code{dptr} member of the
1676 returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of
1677 the returned datum points to the memory managed by the compatibility
1678 library. The application should never free it.
1681 @deftypefn {ndbm} datum dbm_nextkey (DBM *@var{dbf})
1682 Continues the iteration started by @code{dbm_firstkey}. Returns the
1683 next key in the database. If the iteration covered all keys in the
1684 database, the @code{dptr} member of the returned datum is @samp{NULL}.
1685 Otherwise, the @code{dptr} member of the returned datum points to the
1686 memory managed by the compatibility library. The application should
1689 @cindex sequential access, using @samp{NDBM}
1690 @cindex iteration loop, using @samp{NDBM}
1691 The usual way of iterating over all the records in the database is:
1694 for (key = dbm_firstkey (dbf);
1696 key = dbm_nextkey (dbf))
1698 /* do something with the key */
1702 The loop above should not try to delete any records from the database,
1703 otherwise the iteration is not guaranteed to cover all the keys.
1704 @xref{Sequential}, for a detailed discussion of this.
1707 @deftypefn {ndbm} int dbm_error (DBM *@var{dbf})
1708 Returns the error condition of the database: @samp{0} if no errors
1709 occurred so far while manipulating the database, and a non-zero value
1713 @deftypefn {ndbm} void dbm_clearerr (DBM *@var{dbf})
1714 Clears the error condition of the database.
1717 @deftypefn {ndbm} int dbm_dirfno (DBM *@var{dbf})
1718 Returns the file descriptor of the @samp{dir} file of the database.
1719 It is guaranteed to be different from the descriptor returned by
1720 the @code{dbm_pagfno} function (see below).
1722 The application can lock this descriptor to serialize accesses to the
1726 @deftypefn {ndbm} int dbm_pagfno (DBM *@var{dbf})
1727 Returns the file descriptor of the @samp{pag} file of the database.
1728 See also @code{dbm_dirfno}.
1731 @deftypefn {ndbm} int dbm_rdonly (DBM *@var{dbf})
1732 Returns @samp{1} if the database @var{dbf} is open in a read-only mode
1733 and @samp{0} otherwise.
1737 @section DBM interface functions.
1738 @cindex DBM functions
1740 The functions below are provided for compatibility with the old
1741 UNIX @samp{DBM} interface. Only one database at a time can be
1742 manipulated using them.
1744 @deftypefn {dbm} int dbminit (char *@var{file})
1745 Opens a database. The @var{file} argument is the full name of the
1746 database file to be opened. The function opens two files:
1747 @file{@var{file}.pag} and @file{@var{file}.dir}. If any of
1748 them does not exist, the function fails. It never attempts to create
1751 The database is opened in the read-write mode, if its disk permissions
1754 The application must ensure that the functions described below in
1755 this section are called only after a successful call to @code{dbminit}.
1758 @deftypefn {dbm} int dbmclose (void)
1759 Closes the database opened by an earlier call to @code{dbminit}.
1762 @deftypefn {dbm} datum fetch (datum @var{key})
1763 Reads a record from the database with the matching key. The @var{key}
1764 argument supplies the key that is being looked for.
1766 If no matching record is found, the @code{dptr} member of the returned
1767 datum is @samp{NULL}. Otherwise, the @code{dptr} member of the
1768 returned datum points to the memory managed by the compatibility
1769 library. The application should never free it.
1772 @deftypefn {dbm} int store (datum @var{key}, datum @var{content})
1773 Stores the key/value pair in the database. If a record with the
1774 matching key already exists, its content will be replaced with the new
1777 Returns @samp{0} on success and @samp{-1} on error.
1780 @deftypefn {dbm} int delete (datum @var{key})
1781 Deletes a record with the matching key.
1783 If the function succeeds, @samp{0} is returned. Otherwise, if no
1784 matching record is found or if an error occurs, @samp{-1} is
1788 @deftypefn {dbm} datum firstkey (void)
1789 Initializes iteration over the keys from the database and returns
1790 the first key. Note, that the word @samp{first} does not imply any
1791 specific ordering of the keys.
1793 If there are no records in the database, the @code{dptr} member of the
1794 returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of
1795 the returned datum points to the memory managed by the compatibility
1796 library. The application should never free it.
1799 @deftypefn {dbm} datum nextkey (datum @var{key})
1800 Continues the iteration started by a call to @code{firstkey}. Returns
1801 the next key in the database. If the iteration covered all keys in the
1802 database, the @code{dptr} member of the returned datum is @samp{NULL}.
1803 Otherwise, the @code{dptr} member of the returned datum points to the
1804 memory managed by the compatibility library. The application should
1809 @chapter Problems and bugs.
1811 If you have problems with GNU @code{dbm} or think you've found a bug,
1812 please report it. Before reporting a bug, make sure you've actually
1813 found a real bug. Carefully reread the documentation and see if it
1814 really says you can do what you're trying to do. If it's not clear
1815 whether you should be able to do something or not, report that too; it's
1816 a bug in the documentation!
1818 Before reporting a bug or trying to fix it yourself, try to isolate it
1819 to the smallest possible input file that reproduces the problem. Then
1820 send us the input file and the exact results @code{gdbm} gave you. Also
1821 say what you expected to occur; this will help us decide whether the
1822 problem was really in the documentation.
1824 Once you've got a precise problem, send e-mail to
1825 @email{bug-gdbm@@gnu.org}.
1827 Please include the version number of GNU @code{dbm} you are using. You can get
1828 this information by printing the variable @code{gdbm_version}
1829 (@pxref{Variables}).
1831 Non-bug suggestions are always welcome as well. If you have questions
1832 about things that are unclear in the documentation or are just obscure
1833 features, please report them too.
1835 You may contact the authors and maintainers by e-mail:
1837 @email{phil@@cs.wwu.edu}, @email{downsj@@downsj.com}, @email{gray@@gnu.org.ua}
1841 @chapter Additional resources
1843 For the latest updates and pointers to additional resources, visit
1844 @uref{http://www.gnu.org/software/gdbm}.
1846 In particular, a copy of @code{gdbm} documentation in various formats
1847 is available online at @uref{http://www.gnu.org/software/gdbm/manual}.
1849 Latest versions of @code{gdbm} can be downloaded from anonymous FTP:
1850 @uref{ftp://ftp.gnu.org/gnu/gdbm}, or via HTTP from
1851 @uref{http://ftp.gnu.org/gnu/gdbm}, or from any
1853 @uref{http://www.gnu.org/order/ftp.html,,GNU mirror} worldwide.
1856 GNU mirror worldwide. See @uref{http://www.gnu.org/order/ftp.html},
1857 for a list of mirrors.
1860 To track @code{gdbm} development, visit
1861 @uref{http://puszcza.gnu.org.ua/projects/gdbm}.
1863 @node GNU Free Documentation License
1864 @appendix GNU Free Documentation License