1 \input texinfo @c -*- Texinfo -*-
2 @comment $Id: gdbm.texinfo,v 1.34 2013/12/25 09:31:59 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.
12 * gdbm_dump: gdbm_dump(gdbm). Dump the GDBM database into a flat file.
13 * gdbm_load: gdbm_load(gdbm). Load the database from a flat file.
17 @c @setchapternewpage odd
18 @comment %**end of header (This is for running Texinfo on a region.)
20 @c Use @kwindex for keywords
23 @c Use @flindex for files
26 @c Use @prindex for programs
30 @c Merge all indices into a single one
42 Published by the Free Software Foundation,
43 51 Franklin Street, Fifth Floor
44 Boston, MA 02110-1301, USA
46 Copyright @copyright{} 1989-1999, 2007-2011 Free Software Foundation, Inc.
48 Permission is granted to copy, distribute and/or modify this document
49 under the terms of the GNU Free Documentation License, Version 1.3 or
50 any later version published by the Free Software Foundation; with no
51 Invariant Sections, no Front-Cover, and no Back-Cover texts.
52 A copy of the license is included in the section entitled ``GNU Free
53 Documentation License.''
58 @center @titlefont{GNU dbm}
60 @center A Database Manager
62 @center by Philip A. Nelson, Jason Downs and Sergey Poznyakoff
64 @center Manual by Pierre Gaumond, Philip A. Nelson, Jason Downs
65 @center and Sergey Poznyakoff
67 @center Edition @value{EDITION}
69 @center for GNU @code{dbm}, Version @value{VERSION}
71 @vskip 0pt plus 1filll
84 @top The GNU database manager.
86 GNU @code{dbm} is a library of functions implementing a hashed database
87 on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION}
88 (@code{gdbm}). The software was originally written by Philip A.@:
89 Nelson. This document was originally written by Pierre Gaumond from
90 texts written by Phil.
96 * Copying:: Your rights.
97 * Intro:: Introduction to GNU dbm.
98 * List:: List of functions.
102 * Open:: Opening the database.
103 * Close:: Closing the database.
104 * Count:: Counting records in the database.
105 * Store:: Inserting and replacing records in the database.
106 * Fetch:: Searching records in the database.
107 * Delete:: Removing records from the database.
108 * Sequential:: Sequential access to records.
109 * Reorganization:: Database reorganization.
110 * Sync:: Insure all writes to disk have competed.
111 * Flat files:: Export and import to Flat file format.
112 * Errors:: Convert internal error codes into English.
113 * Options:: Setting internal options.
114 * Locking:: File locking.
116 * Error codes:: Error codes returned by @code{gdbm} calls.
117 * Variables:: Two useful variables.
118 * Compatibility:: Compatibility with UNIX dbm and ndbm.
122 * gdbmtool:: Examine and modify a GDBM database.
123 * gdbm_dump:: Dump the database into a flat file.
124 * gdbm_load:: Load the database from a flat file.
125 * gdbmexport:: Export a database into a portable format.
126 * Exit codes:: Exit codes returned by GDBM utilities.
130 * Bugs:: Problems and bugs.
131 * Resources:: Additional resources,
133 * GNU Free Documentation License:: Document license.
138 @chapter Copying Conditions.
139 This library is @dfn{free}; this means that everyone is free to use
140 it and free to redistribute it on a free basis. GNU @code{dbm} (@code{gdbm})
141 is not in the public domain; it is copyrighted and there
142 are restrictions on its distribution, but these restrictions are
143 designed to permit everything that a good cooperating citizen would want
144 to do. What is not allowed is to try to prevent others from further
145 sharing any version of @code{gdbm} that they might get from
148 Specifically, we want to make sure that you have the right to give
149 away copies @code{gdbm}, that you receive
150 source code or else can get it if you want it, that you can change these
151 functions or use pieces of them in new free programs, and that you know
152 you can do these things.@refill
154 To make sure that everyone has such rights, we have to forbid you to
155 deprive anyone else of these rights. For example, if you distribute
156 copies @code{gdbm}, you must give the recipients all
157 the rights that you have. You must make sure that they, too, receive or
158 can get the source code. And you must tell them their rights.@refill
160 Also, for our own protection, we must make certain that everyone finds
161 out that there is no warranty for anything in the @code{gdbm} distribution.
162 If these functions are modified by someone else and passed on, we want
163 their recipients to know that what they have is not what we distributed,
164 so that any problems introduced by others will not reflect on our
167 @code{Gdbm} is currently distributed under the terms of the GNU General
168 Public License, Version 3. (@emph{NOT} under the GNU General Library
169 Public License.) A copy the GNU General Public License is included with
170 the distribution of @code{gdbm}.
173 @chapter Introduction to GNU @code{dbm}.
175 GNU @code{dbm} (@code{gdbm}) is a library of database functions that use
176 extensible hashing and works similar to the standard UNIX @code{dbm}
177 functions. These routines are provided to a programmer needing to
178 create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a
179 complete database package for an end user.)
181 The basic use of @code{gdbm} is to store key/data pairs in a data file.
182 Each key must be unique and each key is paired with only one data item.
183 The keys can not be directly accessed in sorted order. The basic unit
184 of data in @code{gdbm} is the structure:
193 This structure allows for arbitrary sized keys and data items.
195 The key/data pairs are stored in a @code{gdbm} disk file, called a
196 @code{gdbm} database. An application must open a @code{gdbm} database
197 to be able manipulate the keys and data contained in the database.
198 @code{gdbm} allows an application to have multiple databases open at the
199 same time. When an application opens a @code{gdbm} database, it is
200 designated as a @code{reader} or a @code{writer}. A @code{gdbm}
201 database can be opened by at most one writer at a time. However, many readers
202 may open the database simultaneously. Readers and writers can not
203 open the @code{gdbm} database at the same time.
206 @chapter List of functions.
208 The following is a quick list of the functions contained in the @code{gdbm}
209 library. The include file @code{gdbm.h}, that can be included by the user,
210 contains a definition of these functions.
215 GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func);
216 void gdbm_close(dbf);
217 int gdbm_store(dbf, key, content, flag);
218 datum gdbm_fetch(dbf, key);
219 int gdbm_delete(dbf, key);
220 datum gdbm_firstkey(dbf);
221 datum gdbm_nextkey(dbf, key);
222 int gdbm_reorganize(dbf);
224 int gdbm_exists(dbf, key);
225 char *gdbm_strerror(errno);
226 int gdbm_setopt(dbf, option, value, size);
228 int gdbm_export (GDBM_FILE, const char *, int, int);
229 int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp);
230 int gdbm_import (GDBM_FILE, const char *, int);
231 int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag);
232 int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
233 int gdbm_version_cmp (int const a[], int const b[]);
236 The @code{gdbm.h} include file is often in the @file{/usr/local/include}
237 directory. (The actual location of @code{gdbm.h} depends on your local
238 installation of @code{gdbm}.)
241 @chapter Opening the database.
243 @cindex opening the database
244 @cindex database, opening or creating
245 @deftypefn {gdbm interface} GDBM_FILE gdbm_open (const char *@var{name}, int @var{block_size}, @
246 int @var{flags}, int @var{mode}, void (*fatal_func)(const char *))
247 Initializes @code{gdbm} system. If the file has a size of zero bytes, a file
248 initialization procedure is performed, setting up the initial structure in the
255 The name of the file (the complete name, @code{gdbm} does not append any
256 characters to this name).
258 It is used during initialization to determine the size of various
259 constructs. It is the size of a single transfer from disk to
260 memory. This parameter is ignored if the file has been previously
261 initialized. The minimum size is 512. If the value is less than 512,
262 the file system block size is used, otherwise the value of
263 @var{block_size} is used.
267 @kwindex GDBM_WRCREAT
269 If @code{flags} is set to @samp{GDBM_READER}, the user wants to just read the
270 database and any call to @code{gdbm_store} or @code{gdbm_delete} will fail.
271 Many readers can access the database at the same time. If @code{flags} is
272 set to @samp{GDBM_WRITER}, the user wants both read and write access
273 to the database and requires exclusive access. If @code{flags} is set
274 to @samp{GDBM_WRCREAT}, the user wants both read and write access to
275 the database and wants it created if it does not already exist. If
276 @code{flags} is set to @samp{GDBM_NEWDB}, the user want a new database
277 created, regardless of whether one existed, and wants read and write
278 access to the new database.
283 The following may also be logically or'd into the database flags:
284 @samp{GDBM_SYNC}, which causes all database operations to be
285 synchronized to the disk, @samp{GDBM_NOLOCK}, which prevents the library
286 from performing any locking on the database file, and @samp{GDBM_NOMMAP},
287 which disables the memory mapping mechanism. The option @samp{GDBM_FAST} is
288 now obsolete, since @code{gdbm} defaults to no-sync mode.
290 @kwindex GDBM_CLOEXEC
291 @cindex close-on-exec
292 If the host @samp{open} call
294 (@uref{http://www.manpagez.com/man/2/open, open(2)})
297 (@pxref{open,,,open(2),open(2) man page})
299 supports the @samp{O_CLOEXEC} flag, the @samp{GDBM_CLOEXEC} can be
300 or'd into the flags, to enable the close-on-exec flag for the
301 database file descriptor.
305 @uref{http://www.manpagez.com/man/2/chmod},
308 @ref{chmod,,change permissions of a file,chmod(2),
313 @uref{http://www.manpagez.com/man/2/open}),
316 @pxref{open,,open a file,open(2), open(2) man page}),
318 which is used if the file is created).
320 A function for @code{gdbm} to call if it detects a fatal error. The only
321 parameter of this function is a string. If the value of @samp{NULL} is
322 provided, @code{gdbm} will use a default function.
325 The return value, is the pointer needed by all other functions to
326 access that @code{gdbm} file. If the return is the @samp{NULL} pointer,
327 @code{gdbm_open} was not successful. The errors can be found in
328 @code{gdbm_errno} variable (@pxref{Variables, gdbm_errno}). Available
329 error codes are discussed in @ref{Error codes}.
331 In all of the following calls, the parameter @var{dbf} refers to the pointer
332 returned from @code{gdbm_open}.
336 @chapter Closing the database.
337 @cindex closing database
338 @cindex database, closing
340 It is important that every file opened is also closed. This is needed to
341 update the reader/writer count on the file:
343 @deftypefn {gdbm interface} void gdbm_close (GDBM_FILE @var{dbf})
344 This function closes the @code{gdbm} file and frees all memory
345 associated with it. The parameter is:
349 The pointer returned by @code{gdbm_open}.
354 @chapter Number of Records
355 @cindex number of records
356 @deftypefn {gdbm interface} int gdbm_count (GDBM_FILE @var{dbf}, @
357 gdbm_count_t *@var{pcount})
358 Counts number of records in the database @var{dbf}. On success,
359 stores it in the memory location pointed to by @var{pcount} and return
360 0. On error, sets @code{gdbm_errno} (if relevant, also @code{errno})
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 so-called @dfn{flat
655 format} files. Such files cannot be used for searching, their sole
656 purpose is to keep the data from the database for restoring it when
657 the need arrives. There are two flat file formats, which differ in
658 the way they represent the data and in the amount of meta-information
659 stored. Both formats can be used, for example, to migrate between
660 the different versions of @code{gdbm} databases. Generally speaking,
661 flat files are safe to send over the network, and can be used to
662 recreate the database on another machine. The recreated database is
663 guaranteed to be a byte-to-byte equivalent of the database from which
664 the flat file was created. This does not necessarily mean, however,
665 that this file can be used in the same way as the original one. For
666 example, if the original database contained non-@acronym{ASCII} data
667 (e.g.@: @acronym{C} structures, integers etc.), the recreated database
668 can be of any use only if the target machine has the same integer
669 size and byte ordering as the source one and if its @acronym{C}
670 compiler uses the same packing conventions as the one which generated
671 @acronym{C} which populated the original database. In general, such
672 binary databases are not portable between machines, unless you follow
673 some stringent rules on what data is written to them and how it is
676 The GDBM version @value{VERSION} supports two flat file formats. The
677 @dfn{binary} flat file format was first implemented in GDBM version
678 1.9.1. This format stores only key/data pairs, it does not keep
679 information about the database file itself. As its name implies,
680 files in this format are binary files.
682 The @dfn{ascii} flat file format encodes all data in base64 and stores
683 not only key/data pairs, but also the original database file metadata,
684 such as file name, mode and ownership. Files in this format can be
685 sent without additional encapsulation over transmission channels that
686 normally allow only ASCII data, such as, e.g.@: SMTP. Due to additional
687 metadata they allow for restoring an exact copy of the database,
688 including file ownership and privileges, which is especially important
689 if the database in question contained some security-related data.
691 We call a process of creating a flat file from a database
692 @dfn{exporting} or @dfn{dumping} this database. The reverse process,
693 creating the database from a flat file is called @dfn{importing} or
694 @dfn{loading} the database.
696 @deftypefn {gdbm interface} int gdbm_dump (GDBM_FILE @var{dbf}, @
697 const char *@var{filename}, int @var{format}, @
698 int @var{open_flags}, int @var{mode})
699 Dumps the database file to the named file in requested format.
704 A pointer to the source database, returned by a prior call to
708 Name of the dump file.
711 Output file format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to
712 create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII
716 How to create the output file. If @var{flag} is @samp{GDBM_WRCREAT}
717 the file will be created if it does not exist. If it does exist,
718 the @code{gdbm_dump} will fail.
720 If @var{flag} is @samp{GDBM_NEWDB}, the function will create a new
721 output file, replacing it if it already exists.
724 The permissions to use when creating the output file.
726 @uref{http://www.manpagez.com/man/2/open},
729 @ref{open,,open a file,open(2), open(2) man page},
731 for a detailed discussion.
735 @anchor{gdbm_load function}
736 @deftypefn {gdbm interface} int gdbm_load (GDBM_FILE *@var{pdbf}, @
737 const char *@var{filename}, int @var{flag}, @
738 int @var{meta_mask}, @
739 unsigned long *@var{errline})
740 Loads data from the dump file @var{filename} into the database pointed
741 to by @var{pdbf}. The latter can point to @samp{NULL}, in which case
742 the function will try to create a new database. If it succeeds, the
743 function will return, in the memory location pointed to by @var{pdbf},
744 a pointer to the newly created database. If the dump file carries no
745 information about the original database file name, the function will
746 set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return
747 @samp{-1}, indicating failure.
749 The @var{flag} has the same meaning as the @var{flag} argument
750 to the @code{gdbm_store} function (@pxref{Store}).
752 The @var{meta_mask} argument can be used to disable restoring certain
753 bits of file's meta-data from the information in the input dump file.
754 It is a binary OR of zero or more of the following:
757 @item GDBM_META_MASK_MODE
758 Do not restore file mode.
760 @item GDBM_META_MASK_OWNER
761 Do not restore file owner.
764 The function returns 0 upon successful completion or -1 on fatal
765 errors and 1 on mild (non-fatal) errors.
767 If a fatal error occurs, @code{gdbm_errno} will be set to one of the
771 @item GDBM_FILE_OPEN_ERROR
772 Input file (@var{filename}) cannot be opened. The @code{errno}
773 variable can be used to get more detail about the failure.
775 @item GDBM_MALLOC_ERROR
776 Not enough memory to load data.
778 @item GDBM_FILE_READ_ERROR
779 Reading from @var{filename} failed. The @code{errno} variable can be
780 used to get more detail about the failure.
782 @item GDBM_ILLEGAL_DATA
783 Input contained some illegal data.
785 @item GDBM_ITEM_NOT_FOUND
786 This error can occur only when the input file is in ASCII format. It
787 indicates that the data part of the record about to be read lacked
788 length specification. Application developers are advised to treat
789 this error equally as @samp{GDBM_ILLEGAL_DATA}.
792 Mild errors mean that the function was able to successfully load and
793 restore the data, but was unable to change database file metadata
794 afterward. The table below lists possible values for @code{gdbm_errno}
795 in this case. To get more detail, inspect the system @code{errno} variable.
798 @kwindex GDBM_ERR_FILE_OWNER
799 @item GDBM_ERR_FILE_OWNER
800 The function was unable to restore database file owner.
802 @kwindex GDBM_ERR_FILE_MODE
803 @item GDBM_ERR_FILE_MODE
804 The function was unable to restore database file mode (permission bits).
807 If an error occurs while loading data from an input file in ASCII
808 format, the number of line in which the error occurred will be stored
809 in the location pointed to by the @var{errline} parameter, unless it
812 If the line information is not available or applicable, @var{errline}
813 will be set to @samp{0}.
816 @deftypefn {gdbm interface} int gdbm_dump_to_file (GDBM_FILE @var{dbf}, @
817 FILE *@var{fp}, int @var{format})
818 This is an alternative entry point to @code{gdbm_dump} (which see).
823 A pointer to the source database, returned by a call to
827 File to write the data to.
830 Format of the dump file. See the @var{format} argument to the
831 @code{gdbm_dump} function.
835 @deftypefn {gdbm interface} int gdbm_load_from_file (GDBM_FILE *@var{pdbf}, @
836 FILE *@var{fp}, int @var{replace}, int @var{meta_mask}, @
837 unsigned long *@var{line})
838 This is an alternative entry point to @code{gdbm_dump}. It writes the
839 output to @var{fp} which must be a file open for writing. The rest of
840 arguments is the same as for @code{gdbm_load} (excepting of course
841 @var{flag}, which is not needed in this case).
844 @deftypefn {gdbm interface} int gdbm_export (GDBM_FILE @var{dbf}, @
845 const char *@var{exportfile}, int @var{flag}, int @var{mode})
846 This function is retained for compatibility with GDBM 1.10 and
847 earlier. It dumps the database to a file in binary dump format and
848 is entirely equivalent to
851 gdbm_dump(@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY,
852 @var{flag}, @var{mode})
857 @deftypefn {gdbm interface} int gdbm_export_to_file (GDBM_FILE @var{dbf}, FILE *@var{fp})
858 This is an alternative entry point to @code{gdbm_export}. This
859 function writes to file @var{fp} a binary dump of the database @var{dbf}.
862 @deftypefn {gdbm interface} int gdbm_import (GDBM_FILE @var{dbf}, @
863 const char *@var{importfile}, int @var{flag})
864 This function is retained for compatibility with GDBM 1.10 and
865 earlier. It loads the file @var{importfile}, which must be a binary
866 flat file, into the database @var{dbf} and is equivalent to the
870 @var{dbf} = gdbm_open (@var{importfile}, 0,
871 @var{flag} == GDBM_REPLACE ?
872 GDBM_WRCREAT : GDBM_NEWDB,
874 gdbm_load (&@var{dbf}, @var{exportfile}, 0, @var{flag}, NULL)
878 @deftypefn {gdbm interface} int gdbm_import_from_file (GDBM_FILE @var{dbf}, @
879 FILE *@var{fp}, int @var{flag})
880 An alternative entry point to @code{gdbm_import}. Reads the binary
881 dump from the file @var{fp} and stores the key/value pairs to
882 @var{dbf}. @xref{Store}, for a description of @var{flag}.
884 This function is equivalent to:
887 @var{dbf} = gdbm_open (@var{importfile}, 0,
888 @var{flag} == GDBM_REPLACE ?
889 GDBM_WRCREAT : GDBM_NEWDB,
891 gdbm_load_from_file (@var{dbf}, @var{fp}, @var{flag}, 0, NULL);
896 @chapter Error strings.
897 @cindex error strings
899 To convert a @code{gdbm} error code into English text, use this
902 @deftypefn {gdbm interface} {const char *} gdbm_strerror (gdbm_error @var{errno})
903 Converts @var{errno} (which is an integer value) into a human-readable
904 descriptive text. Returns a pointer to a static string. The caller
905 must not alter or free the returned pointer.
907 The @var{errno} argument is usually the value of the global variable
908 @code{gdbm_errno}. @xref{Variables, gdbm_errno}.
912 @chapter Setting options
913 @cindex database options
914 @cindex options, database
916 @code{Gdbm} supports the ability to set certain options on an already
919 @deftypefn {gdbm interface} int gdbm_setopt (GDBM_FILE @var{dbf}, int @var{option}, @
920 void *@var{value}, int @var{size})
921 Sets an option on the database or returns the value of an option.
927 The pointer returned by @code{gdbm_open}.
929 The option to be set or retrieved.
931 A pointer to the value to which @var{option} will be set or where to
932 place the option value (depending on the option).
934 The length of the data pointed to by @var{value}.
938 The valid options are:
941 @kwindex GDBM_CACHESIZE
942 @kwindex GDBM_SETCACHESIZE
943 @item GDBM_SETCACHESIZE
944 @itemx GDBM_CACHESIZE
945 Set the size of the internal bucket cache. This option may only be
946 set once on each GDBM_FILE descriptor, and is set automatically to 100
947 upon the first access to the database. The @var{value} should point
948 to a @code{size_t} holding the desired cache size.
950 The @samp{GDBM_CACHESIZE} option is provided for compatibility with
953 @kwindex GDBM_GETCACHESIZE
954 @item GDBM_GETCACHESIZE
955 Return the size of the internal bucket cache. The @var{value} should
956 point to a @code{size_t} variable, where the size will be stored.
958 @kwindex GDBM_GETFLAGS
960 Return the flags describing the state of the database. The @var{value} should
961 point to a @code{int} variable where to store the flags. The return
962 is the same as the flags used when opening the database (@pxref{Open,
963 gdbm_open}), except that it reflects the current state (which may have
964 been altered by another calls to @code{gdbm_setopt}.
966 @kwindex GDBM_FASTMODE
968 Enable or disable the @dfn{fast writes mode}, i.e.@: writes without
969 subsequent synchronization. The @var{value} should point
970 to an integer: @samp{TRUE} to enable fast mode, and @samp{FALSE} to
973 This option is retained for compatibility with previous versions of
974 @code{gdbm}. Its effect is the reverse of @code{GDBM_SETSYNCMODE}
977 @kwindex GDBM_SETSYNCMODE
978 @kwindex GDBM_SYNCMODE
979 @item GDBM_SETSYNCMODE
981 Turn on or off file system synchronization operations. This
982 setting defaults to off. The @var{value} should point
983 to an integer: @samp{TRUE} to turn synchronization on, and @samp{FALSE} to
986 Note, that this option is a reverse of @code{GDBM_FASTMODE},
987 i.e.@: calling @code{GDBM_SETSYNCMODE} with @samp{TRUE} has the same effect
988 as calling @code{GDBM_FASTMODE} with @samp{FALSE}.
990 The @samp{GDBM_SYNCMODE} option is provided for compatibility with
993 @kwindex GDBM_GETSYNCMODE
994 @item GDBM_GETSYNCMODE
995 Return the current synchronization status. The @var{value} should
996 point to an @code{int} where the status will be stored.
998 @kwindex GDBM_SETCENTFREE
999 @kwindex GDBM_CENTFREE
1000 @item GDBM_SETCENTFREE
1001 @itemx GDBM_CENTFREE
1002 @emph{NOTICE: This feature is still under study.}
1004 Set central free block pool to either on or off. The default is off,
1005 which is how previous versions of @code{gdbm} handled free blocks. If
1006 set, this option causes all subsequent free blocks to be placed in the
1007 @emph{global} pool, allowing (in theory) more file space to be reused
1008 more quickly. The @var{value} should point to an integer: @samp{TRUE} to
1009 turn central block pool on, and @samp{FALSE} to turn it off.
1011 The @samp{GDBM_CENTFREE} option is provided for compatibility with
1014 @kwindex GDBM_SETCOALESCEBLKS
1015 @kwindex GDBM_COALESCEBLKS
1016 @item GDBM_SETCOALESCEBLKS
1017 @itemx GDBM_COALESCEBLKS
1018 @emph{NOTICE: This feature is still under study.}
1020 Set free block merging to either on or off. The default is off, which
1021 is how previous versions of @code{gdbm} handled free blocks. If set,
1022 this option causes adjacent free blocks to be merged. This can become
1023 a @acronym{CPU} expensive process with time, though, especially if
1024 used in conjunction with GDBM_CENTFREE. The @var{value} should point
1025 to an integer: @samp{TRUE} to turn free block merging on, and @samp{FALSE} to
1028 @kwindex GDBM_GETCOALESCEBLKS
1029 @item GDBM_GETCOALESCEBLKS
1030 Return the current status of free block merging. The @var{value} should
1031 point to an @code{int} where the status will be stored.
1033 @kwindex GDBM_SETMAXMAPSIZE
1034 @item GDBM_SETMAXMAPSIZE
1035 Sets maximum size of a memory mapped region. The @var{value} should
1036 point to a value of type @code{size_t}, @code{unsigned long} or
1037 @code{unsigned}. The actual value is rounded to the nearest page
1038 boundary (the page size is obtained from
1039 @code{sysconf(_SC_PAGESIZE)}).
1041 @kwindex GDBM_GETMAXMAPSIZE
1042 @item GDBM_GETMAXMAPSIZE
1043 Return the maximum size of a memory mapped region. The @var{value} should
1044 point to a value of type @code{size_t} where to return the data.
1046 @kwindex GDBM_SETMMAP
1048 Enable or disable memory mapping mode. The @var{value} should point
1049 to an integer: @samp{TRUE} to enable memory mapping or @samp{FALSE} to
1052 @kwindex GDBM_GETMMAP
1054 Check whether memory mapping is enabled. The @var{value} should point
1055 to an integer where to return the status.
1057 @kwindex GDBM_GETDBNAME
1058 @item GDBM_GETDBNAME
1059 Return the name of the database disk file. The @var{value} should
1060 point to a variable of type @code{char**}. A pointer to the newly
1061 allocated copy of the file name will be placed there. The caller is
1062 responsible for freeing this memory when no longer needed. For
1068 if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
1070 fprintf (stderr, "gdbm_setopt failed: %s\n",
1071 gdbm_strerror (gdbm_errno));
1075 printf ("database name: %s\n", name);
1082 The return value will be @samp{-1} upon failure, or @samp{0} upon
1083 success. The global variable @code{gdbm_errno} will be set upon failure.
1085 For instance, to set a database to use a cache of 10, after opening it
1086 with @code{gdbm_open}, but prior to accessing it in any way, the following
1092 ret = gdbm_setopt (dbf, GDBM_CACHESIZE, &value, sizeof (int));
1097 @chapter File Locking.
1100 @kwindex GDBM_NOLOCK
1101 With locking disabled (if @code{gdbm_open} was called with @samp{GDBM_NOLOCK}),
1102 the user may want to perform their own file locking on the database file
1103 in order to prevent multiple writers operating on the same file
1106 In order to support this, the @code{gdbm_fdesc} routine is provided.
1108 @deftypefn {gdbm interface} int gdbm_fdesc (GDBM_FILE @var{dbf})
1109 Returns the file descriptor of the database @var{dbf}. This value
1110 can be used as an argument to @code{flock}, @code{lockf} or similar
1115 @chapter Useful global variables.
1117 The following global variables and constants are available:
1119 @deftypevar gdbm_error gdbm_errno
1120 This variable contains error code from the last failed @code{gdbm}
1121 call. @xref{Error codes}, for a list of available error codes and
1124 Use @code{gdbm_strerror} (@pxref{Errors}) to convert it to a
1128 @deftypevar {const char *} gdbm_errlist[]
1129 This variable is an array of error descriptions, which is used by
1130 @code{gdbm_strerror} to convert error codes to human-readable text
1131 (@pxref{Errors}). You can access it directly, if you wish so. It
1132 contains @code{_GDBM_MAX_ERRNO + 1} elements and can be directly
1133 indexed by the error code to obtain a corresponding descriptive
1137 @defvr {Constant} _GDBM_MIN_ERRNO
1138 The minimum error code used by @code{gdbm}.
1141 @defvr {Constant} _GDBM_MAX_ERRNO
1142 The maximum error code used by @code{gdbm}.
1145 @cindex version number
1146 @deftypevar {const char *} gdbm_version
1147 A string containing the version information.
1150 @deftypevar {int const} gdbm_version_number[3]
1151 This variable contains the @code{gdbm} version numbers:
1153 @multitable @columnfractions 0.4 0.5
1154 @headitem Index @tab Meaning
1155 @item 0 @tab Major number
1156 @item 1 @tab Minor number
1157 @item 2 @tab Patchlevel number
1160 Additionally, the following constants are defined in the @file{gdbm.h}
1164 @kwindex GDBM_VERSION_MAJOR
1165 @item GDBM_VERSION_MAJOR
1168 @kwindex GDBM_VERSION_MINOR
1169 @item GDBM_VERSION_MINOR
1172 @kwindex GDBM_VERSION_PATCH
1173 @item GDBM_VERSION_PATCH
1177 These can be used to verify whether the header file matches the library.
1180 To compare two split-out version numbers, use the following function:
1182 @deftypefn {gdbm interface} int gdbm_version_cmp (int const @var{a}[3], @
1183 int const @var{b}[3])
1184 Compare two version numbers. Return @samp{-1} if @var{a} is less than
1185 @var{b}, @samp{1} if @var{a} is greater than @var{b} and @samp{0} if
1188 Comparison is done from left to right, so that:
1193 gdbm_version_cmp (a, b) @result{} 0
1197 gdbm_version_cmp (a, b) @result{} 1
1201 gdbm_version_cmp (a, b) @result{} -1
1206 @chapter Error codes
1209 This chapter summarizes error codes which can be set by the
1210 functions in @code{gdbm} library.
1213 @kwindex GDBM_NO_ERROR
1217 @kwindex GDBM_MALLOC_ERROR
1218 @item GDBM_MALLOC_ERROR
1219 Memory allocation failed. Not enough memory.
1221 @kwindex GDBM_BLOCK_SIZE_ERROR
1222 @item GDBM_BLOCK_SIZE_ERROR
1223 This error is set by the @code{gdbm_open} function (@pxref{Open}), if
1224 the value of its @var{block_size} argument is incorrect.
1226 @kwindex GDBM_FILE_OPEN_ERROR
1227 @item GDBM_FILE_OPEN_ERROR
1228 The library was not able to open a disk file. This can be set by
1229 @code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
1230 @code{gdbm_import} functions (@pxref{Flat files}).
1232 Inspect the value of the system @code{errno} variable to get more
1233 detailed diagnostics.
1235 @kwindex GDBM_FILE_WRITE_ERROR
1236 @item GDBM_FILE_WRITE_ERROR
1237 Writing to a disk file failed. This can be set by
1238 @code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
1239 @code{gdbm_import} functions.
1241 Inspect the value of the system @code{errno} variable to get more
1242 detailed diagnostics.
1244 @kwindex GDBM_FILE_SEEK_ERROR
1245 @item GDBM_FILE_SEEK_ERROR
1246 Positioning in a disk file failed. This can be set by
1247 @code{gdbm_open} (@pxref{Open}) function.
1249 Inspect the value of the system @code{errno} variable to get a more
1250 detailed diagnostics.
1252 @kwindex GDBM_FILE_READ_ERROR
1253 @item GDBM_FILE_READ_ERROR
1254 Reading from a disk file failed. This can be set by
1255 @code{gdbm_open} (@pxref{Open}), @code{gdbm_export} and
1256 @code{gdbm_import} functions.
1258 Inspect the value of the system @code{errno} variable to get a more
1259 detailed diagnostics.
1261 @kwindex GDBM_BAD_MAGIC_NUMBER
1262 @item GDBM_BAD_MAGIC_NUMBER
1263 The file given as argument to @code{gdbm_open} function is not a valid
1264 @code{gdbm} file: it has a wrong magic number.
1266 @kwindex GDBM_EMPTY_DATABASE
1267 @item GDBM_EMPTY_DATABASE
1268 The file given as argument to @code{gdbm_open} function is not a valid
1269 @code{gdbm} file: it has zero length.
1271 @kwindex GDBM_CANT_BE_READER
1272 @item GDBM_CANT_BE_READER
1273 This error code is set by the @code{gdbm_open} function if it is not
1274 able to lock file when called in @samp{GDBM_READER} mode (@pxref{Open,
1277 @kwindex GDBM_CANT_BE_WRITER
1278 @item GDBM_CANT_BE_WRITER
1279 This error code is set by the @code{gdbm_open} function if it is not
1280 able to lock file when called in writer mode (@pxref{Open}).
1282 @kwindex GDBM_READER_CANT_DELETE
1283 @item GDBM_READER_CANT_DELETE
1284 Set by the @code{gdbm_delete} (@pxref{Delete}) if it attempted to
1285 operate on a database that is open in read-only mode (@pxref{Open,
1288 @kwindex GDBM_READER_CANT_STORE
1289 @item GDBM_READER_CANT_STORE
1290 Set by the @code{gdbm_store} (@pxref{Store}) if it attempted to
1291 operate on a database that is open in read-only mode (@pxref{Open,
1294 @kwindex GDBM_READER_CANT_REORGANIZE
1295 @item GDBM_READER_CANT_REORGANIZE
1296 Set by the @code{gdbm_reorganize} (@pxref{Reorganization}) if it attempted to
1297 operate on a database that is open in read-only mode (@pxref{Open,
1300 @kwindex GDBM_UNKNOWN_UPDATE
1301 @item GDBM_UNKNOWN_UPDATE
1302 Currently unused. Reserved for future uses.
1304 @kwindex GDBM_ITEM_NOT_FOUND
1305 @item GDBM_ITEM_NOT_FOUND
1306 Requested item was not found. This error is set by @code{gdbm_delete}
1307 (@pxref{Delete}) and @code{gdbm_fetch} (@pxref{Fetch}) when the requested
1308 @var{key} value is not found in the database.
1310 @kwindex GDBM_REORGANIZE_FAILED
1311 @item GDBM_REORGANIZE_FAILED
1312 The @code{gdbm_reorganize} function is not
1313 able to create a temporary database. @xref{Reorganization}.
1315 @kwindex GDBM_CANNOT_REPLACE
1316 @item GDBM_CANNOT_REPLACE
1317 Cannot replace existing item. This error is set by the
1318 @code{gdbm_store} if the requested @var{key} value is found in the
1319 database and the @var{flag} parameter is not @samp{GDBM_REPLACE}.
1320 @xref{Store}, for a detailed discussion.
1322 @kwindex GDBM_ILLEGAL_DATA
1323 @item GDBM_ILLEGAL_DATA
1324 Either @var{key} or @var{content} parameter was wrong in a call to
1325 to @code{gdbm_store} (@pxref{Store}).
1327 @kwindex GDBM_OPT_ALREADY_SET
1328 @item GDBM_OPT_ALREADY_SET
1329 Requested option can be set only once and was already set. This error
1330 is returned by the @code{gdbm_setopt} function. @xref{Options,
1333 @kwindex GDBM_OPT_ILLEGAL
1334 @item GDBM_OPT_ILLEGAL
1335 The @var{option} argument is not valid or the @var{value} argument
1336 points to an invalid value in a call to @code{gdbm_setopt} function.
1339 @kwindex GDBM_BYTE_SWAPPED
1340 @item GDBM_BYTE_SWAPPED
1341 The @code{gdbm_open} function (@pxref{Open}) attempts to open a
1342 database which is created on a machine with different byte ordering.
1344 @kwindex GDBM_BAD_FILE_OFFSET
1345 @item GDBM_BAD_FILE_OFFSET
1346 The @code{gdbm_open} function (@pxref{Open}) sets this error code if
1347 the file it tries to open has a wrong magic number.
1349 @kwindex GDBM_BAD_OPEN_FLAGS
1350 @item GDBM_BAD_OPEN_FLAGS
1351 Set by the @code{gdbm_export} function if supplied an invalid
1352 @var{flags} argument. @xref{Flat files}.
1354 @kwindex GDBM_FILE_STAT_ERROR
1355 @item GDBM_FILE_STAT_ERROR
1356 Getting information about a disk file failed. The system @code{errno}
1357 will give more details about the error.
1359 This error can be set by the following functions: @code{gdbm_open},
1360 @code{gdbm_reorganize}.
1362 @kwindex GDBM_FILE_EOF
1364 End of file was encountered where more data was expected to be
1365 present. This error can occur when fetching data from the database
1366 and usually means that the database is truncated or otherwise corrupted.
1368 This error can be set by any GDBM function that does I/O. Some of
1369 these functions are: @code{gdbm_delete}, @code{gdbm_exists},
1370 @code{gdbm_fetch}, @code{gdbm_export}, @code{gdbm_import},
1371 @code{gdbm_reorganize}, @code{gdbm_firstkey}, @code{gdbm_nextkey},
1374 @kwindex GDBM_NO_DBNAME
1375 @item GDBM_NO_DBNAME
1376 Output database name is not specified. This error code is set by
1377 @code{gdbm_load} (@pxref{gdbm_load function,,gdbm_load}) if the first
1378 argument points to @samp{NULL} and the input file does not specify the
1381 @kwindex GDBM_ERR_FILE_OWNER
1382 @item GDBM_ERR_FILE_OWNER
1383 This error code is set by @code{gdbm_load} if it is unable to restore
1384 database file owner. It is a mild error condition, meaning that the
1385 data have been restored successfully, only changing the target file
1386 owner failed. Inspect the system @code{errno} variable to get a more
1387 detailed diagnostics.
1389 @kwindex GDBM_ERR_FILE_MODE
1390 @item GDBM_ERR_FILE_MODE
1391 This error code is set by @code{gdbm_load} if it is unable to restore
1392 database file mode. It is a mild error condition, meaning that the data
1393 have been restored successfully, only changing the target file owner
1394 failed. Inspect the system @code{errno} variable to get a more
1395 detailed diagnostics.
1400 @chapter Compatibility with standard @code{dbm} and @code{ndbm}.
1402 @cindex compatibility layer
1403 @code{Gdbm} includes a compatibility layer, which provides traditional
1404 @samp{ndbm} and older @samp{dbm} functions. The layer is compiled and
1405 installed if the @option{--enable-libgdbm-compat} option is used when
1406 configuring the package.
1410 @findex libgdbm_compat
1411 The compatibility layer consists of two header files: @file{ndbm.h}
1412 and @file{dbm.h} and the @file{libgdbm_compat} library.
1414 Older programs using @code{ndbm} or @code{dbm} interfaces can
1415 use @file{libgdbm_compat} without any changes. To link a program with
1416 the compatibility library, add the following two options to the
1417 @command{cc} invocation: @option{-lgdbm -lgdbm_compat}. The @option{-L}
1418 option may also be required, depending on where @code{gdbm} is
1422 cc ... -L/usr/local/lib -lgdbm -lgdbm_compat
1425 @cindex @samp{dir} file
1426 @cindex @samp{pag} file
1427 Databases created and manipulated by the compatibility interfaces
1428 consist of two different files: @file{@var{file}.dir} and
1429 @file{@var{file}.pag}. This is required by the @acronym{POSIX}
1430 specification and corresponds to the traditional usage. Note,
1431 however, that despite the similarity of the naming convention,
1432 actual data stored in these files has not the same format as
1433 in the databases created by other @code{dbm} or @code{ndbm}
1434 libraries. In other words, you cannot access a standard UNIX
1435 @code{dbm} file with GNU @code{dbm}!
1437 GNU @code{dbm} files are not @code{sparse}. You can copy them with
1438 the usual @code{cp} command and they will not expand in the copying
1442 * ndbm:: NDBM interface functions.
1443 * dbm:: DBM interface functions.
1447 @section NDBM interface functions.
1448 @cindex NDBM functions
1450 The functions below implement the @acronym{POSIX} @samp{ndbm} interface:
1452 @deftypefn {ndbm} {DBM *} dbm_open (char *@var{file}, int @var{flags}, int @var{mode})
1453 Opens a database. The @var{file} argument is the full name of the
1454 database file to be opened. The function opens two files:
1455 @file{@var{file}.pag} and @file{@var{file}.dir}. The @var{flags} and
1456 @var{mode} arguments have the same meaning as the second and third
1459 @uref{http://www.manpagez.com/man/2/open,,open(2)},
1462 @code{open} (@pxref{open,,open a file,open(2), open(2) man page}),
1464 except that a database opened for write-only access opens the files
1465 for read and write access and the behavior of the @code{O_APPEND} flag is
1468 The function returns a pointer to the @code{DBM} structure describing
1469 the database. This pointer is used to refer to this database in all
1470 operations described below.
1472 Any error detected will cause a return value of @samp{NULL} and an
1473 appropriate value will be stored in @code{gdbm_errno}
1474 (@pxref{Variables}).
1477 @deftypefn {ndbm} void dbm_close (DBM *@var{dbf})
1478 Closes the database. The @var{dbf} argument must be a pointer
1479 returned by an earlier call to @code{dbm_open}.
1482 @deftypefn {ndbm} datum dbm_fetch (DBM *@var{dbf}, datum @var{key})
1483 Reads a record from the database with the matching key. The @var{key}
1484 argument supplies the key that is being looked for.
1486 If no matching record is found, the @code{dptr} member of the returned
1487 datum is @samp{NULL}. Otherwise, the @code{dptr} member of the
1488 returned datum points to the memory managed by the compatibility
1489 library. The application should never free it.
1492 @deftypefn {ndbm} int dbm_store (DBM *@var{dbf}, datum @var{key}, @
1493 datum @var{content}, int @var{mode})
1494 Writes a key/value pair to the database. The argument @var{dbf} is a
1495 pointer to the @code{DBM} structure returned from a call to
1496 @code{dbm_open}. The @var{key} and @var{content} provide the values
1497 for the record key and content. The @var{mode} argument controls
1498 the behavior of @code{dbm_store} in case a matching record already
1499 exists in the database. It can have one of the following two values:
1502 @kwindex DBM_REPLACE
1504 Replace existing record with the new one.
1508 The existing record is left unchanged, and the function returns
1512 If no matching record exists in the database, new record will be
1513 inserted no matter what the value of the @var{mode} is.
1516 @deftypefn {ndbm} int dbm_delete (DBM *@var{dbf}, datum @var{key})
1517 Deletes the record with the matching key from the database. If the
1518 function succeeds, @samp{0} is returned. Otherwise, if no matching
1519 record is found or if an error occurs, @samp{-1} is returned.
1522 @deftypefn {ndbm} datum dbm_firstkey (DBM *@var{dbf})
1523 Initializes iteration over the keys from the database and returns
1524 the first key. Note, that the word @samp{first} does not imply any
1525 specific ordering of the keys.
1527 If there are no records in the database, the @code{dptr} member of the
1528 returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of
1529 the returned datum points to the memory managed by the compatibility
1530 library. The application should never free it.
1533 @deftypefn {ndbm} datum dbm_nextkey (DBM *@var{dbf})
1534 Continues the iteration started by @code{dbm_firstkey}. Returns the
1535 next key in the database. If the iteration covered all keys in the
1536 database, the @code{dptr} member of the returned datum is @samp{NULL}.
1537 Otherwise, the @code{dptr} member of the returned datum points to the
1538 memory managed by the compatibility library. The application should
1541 @cindex sequential access, using @samp{NDBM}
1542 @cindex iteration loop, using @samp{NDBM}
1543 The usual way of iterating over all the records in the database is:
1546 for (key = dbm_firstkey (dbf);
1548 key = dbm_nextkey (dbf))
1550 /* do something with the key */
1554 The loop above should not try to delete any records from the database,
1555 otherwise the iteration is not guaranteed to cover all the keys.
1556 @xref{Sequential}, for a detailed discussion of this.
1559 @deftypefn {ndbm} int dbm_error (DBM *@var{dbf})
1560 Returns the error condition of the database: @samp{0} if no errors
1561 occurred so far while manipulating the database, and a non-zero value
1565 @deftypefn {ndbm} void dbm_clearerr (DBM *@var{dbf})
1566 Clears the error condition of the database.
1569 @deftypefn {ndbm} int dbm_dirfno (DBM *@var{dbf})
1570 Returns the file descriptor of the @samp{dir} file of the database.
1571 It is guaranteed to be different from the descriptor returned by
1572 the @code{dbm_pagfno} function (see below).
1574 The application can lock this descriptor to serialize accesses to the
1578 @deftypefn {ndbm} int dbm_pagfno (DBM *@var{dbf})
1579 Returns the file descriptor of the @samp{pag} file of the database.
1580 See also @code{dbm_dirfno}.
1583 @deftypefn {ndbm} int dbm_rdonly (DBM *@var{dbf})
1584 Returns @samp{1} if the database @var{dbf} is open in a read-only mode
1585 and @samp{0} otherwise.
1589 @section DBM interface functions.
1590 @cindex DBM functions
1592 The functions below are provided for compatibility with the old
1593 UNIX @samp{DBM} interface. Only one database at a time can be
1594 manipulated using them.
1596 @deftypefn {dbm} int dbminit (char *@var{file})
1597 Opens a database. The @var{file} argument is the full name of the
1598 database file to be opened. The function opens two files:
1599 @file{@var{file}.pag} and @file{@var{file}.dir}. If any of
1600 them does not exist, the function fails. It never attempts to create
1603 The database is opened in the read-write mode, if its disk permissions
1606 The application must ensure that the functions described below in
1607 this section are called only after a successful call to @code{dbminit}.
1610 @deftypefn {dbm} int dbmclose (void)
1611 Closes the database opened by an earlier call to @code{dbminit}.
1614 @deftypefn {dbm} datum fetch (datum @var{key})
1615 Reads a record from the database with the matching key. The @var{key}
1616 argument supplies the key that is being looked for.
1618 If no matching record is found, the @code{dptr} member of the returned
1619 datum is @samp{NULL}. Otherwise, the @code{dptr} member of the
1620 returned datum points to the memory managed by the compatibility
1621 library. The application should never free it.
1624 @deftypefn {dbm} int store (datum @var{key}, datum @var{content})
1625 Stores the key/value pair in the database. If a record with the
1626 matching key already exists, its content will be replaced with the new
1629 Returns @samp{0} on success and @samp{-1} on error.
1632 @deftypefn {dbm} int delete (datum @var{key})
1633 Deletes a record with the matching key.
1635 If the function succeeds, @samp{0} is returned. Otherwise, if no
1636 matching record is found or if an error occurs, @samp{-1} is
1640 @deftypefn {dbm} datum firstkey (void)
1641 Initializes iteration over the keys from the database and returns
1642 the first key. Note, that the word @samp{first} does not imply any
1643 specific ordering of the keys.
1645 If there are no records in the database, the @code{dptr} member of the
1646 returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of
1647 the returned datum points to the memory managed by the compatibility
1648 library. The application should never free it.
1651 @deftypefn {dbm} datum nextkey (datum @var{key})
1652 Continues the iteration started by a call to @code{firstkey}. Returns
1653 the next key in the database. If the iteration covered all keys in the
1654 database, the @code{dptr} member of the returned datum is @samp{NULL}.
1655 Otherwise, the @code{dptr} member of the returned datum points to the
1656 memory managed by the compatibility library. The application should
1661 @chapter Examine and modify a GDBM database.
1664 The @command{gdbmtool} utility allows you to view and modify an
1665 existing @acronym{GDBM} database or to create a new one.
1667 @cindex default database, @command{gdbmtool}
1669 When invoked without arguments, it tries to open a database file called
1670 @file{junk.gdbm}, located in the current working directory. You can
1671 change this default by supplying the name of the database to use as
1672 an argument to the program, e.g.:
1678 @cindex read-only mode, @command{gdbmtool}
1679 @cindex @option{-r}, @command{gdbmtool} option
1680 @cindex @option{--read-only}, @command{gdbmtool} option
1681 The database will be opened in read-write mode, unless the
1682 @option{-r} (@option{--read-only}) option is specified, in which case
1683 it will be opened only for reading.
1685 @cindex creating a database, @command{gdbmtool}
1686 @cindex @option{-n}, @command{gdbmtool} option
1687 @cindex @option{--newdb}, @command{gdbmtool} option
1688 If the database does not exist, @command{gdbmtool} will create it.
1689 There is a special option @option{-n} (@option{--newdb}, which
1690 instructs the utility to create a new database. If it is used and if
1691 the database already exists, it will be deleted, so use it sparingly.
1699 @section gdbmtool invocation
1700 @cindex command line options, @command{gdbmtool}
1702 The following table summarizes all @command{gdbmtool} command line
1707 @itemx --block-size=@var{size}
1710 @itemx --cache-size=@var{size}
1713 @item --file @var{file}
1714 Read commands from @var{file}, instead of the standard input.
1717 Print a concise help summary.
1720 Don't read startup files (@pxref{startup files}).
1723 Create the database.
1726 Disable file locking.
1733 Don't print the usual welcome banner at startup. This is the same as
1734 setting the variable @samp{quiet} in the startup file. @xref{quiet}.
1737 Open the database in read-only mode.
1739 @itemx --synchronize
1740 Synchronize to the disk after each write.
1743 Print program version and licensing information and exit.
1745 Print a terse invocation syntax summary along with a list of available
1746 command line options.
1750 @section gdbmtool interactive mode
1751 @cindex interactive mode, @command{gdbmtool}
1753 After successful startup, @command{gdbmtool} starts a loop, in which
1754 it reads commands from the standard input, executes them and prints
1755 the results on the standard output. If the standard input is attached
1756 to a console, @command{gdbmtool} runs in interactive mode, which is
1757 indicated by its @dfn{prompt}:
1763 The utility finishes when it reads the @samp{quit} command (see below) or
1764 detects end-of-file on its standard input, whichever occurs first.
1766 A @command{gdbmtool} command consists of a @dfn{command verb},
1767 optionally followed by @dfn{arguments}, separated by any
1768 amount of white space. A command verb can be entered either in full
1769 or in an abbreviated form, as long as that abbreviation does not match
1770 any other verb. For example, @samp{co} can be used instead of
1771 @samp{count} and @samp{ca} instead of @samp{cache}.
1773 Any sequence of non-whitespace characters appearing after the command
1774 verb forms an argument. If the argument contains whitespace or
1775 unprintable characters it must be enclosed in double quotes. Within
1776 double quotes the usual @dfn{escape sequences} are understood, as
1777 shown in the table below:
1779 @float Table, backslash-interpretation
1780 @caption{Backslash escapes}
1781 @multitable @columnfractions 0.30 .5
1782 @item Sequence @tab Replaced with
1783 @item \a @tab Audible bell character (@acronym{ASCII} 7)
1784 @item \b @tab Backspace character (@acronym{ASCII} 8)
1785 @item \f @tab Form-feed character (@acronym{ASCII} 12)
1786 @item \n @tab Newline character (@acronym{ASCII} 10)
1787 @item \r @tab Carriage return character (@acronym{ASCII} 13)
1788 @item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
1789 @item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
1790 @item \\ @tab Single slash
1791 @item \" @tab Double quote
1795 In addition, a backslash immediately followed by the end-of-line
1796 character effectively removes that character, allowing to split long
1797 arguments over several input lines.
1799 Command parameters may be optional or mandatory. If the number of
1800 actual arguments is less than the number of mandatory parameters,
1801 @command{gdbmtool} will prompt you to supply missing arguments. For
1802 example, the @samp{store} command takes two mandatory parameters, so
1803 if you invoked it with no arguments, you would be prompted twice to
1804 supply the necessary data, as shown in example below:
1807 gdbmtool> @kbd{store}
1812 However, such prompting is possible only in interactive mode. In
1813 non-interactive mode (e.g.@: when running a script), all arguments must
1814 be supplied with each command, otherwise @command{gdbmtool} will report an
1815 error and exit immediately.
1818 * variables:: shell variables.
1819 * commands:: shell commands.
1820 * definitions:: how to define structured data.
1825 @subsection Shell Variables
1826 @cindex variables, gdbmtool
1827 A number of @command{gdbmtool} parameters is kept in its internal
1830 @deftypevr {gdbmtool variable} bool confirm
1831 Whether to ask for confirmation before certain destructive operations,
1832 such as truncating the existing database.
1834 Default is @samp{true}.
1837 @deftypevr {gdbmtool variable} string ps1
1838 Primary prompt string. Its value can contain @dfn{conversion
1839 specifiers}, consisting of the @samp{%} character followed by another
1840 character. These specifiers are expanded in the resulting prompt as
1843 @multitable @columnfractions 0.4 0.5
1844 @headitem Sequence @tab Expansion
1845 @item %f @tab name of the current database file
1846 @item %p @tab program invocation name
1847 @item %P @tab package name (@samp{GDBM})
1848 @item %v @tab program version
1849 @item %_ @tab single space character
1853 The default value is @samp{%p>%_}, i.e. the program name, followed by
1854 a ``greater than'' sign, followed by a single space.
1857 @deftypevr {gdbmtool variable} string ps2
1858 Secondary prompt. See @samp{ps1} for a description of its value.
1859 This prompt is displayed before reading the second and subsequent
1860 lines of a multi-line command.
1862 The default value is @samp{%_>%_}.
1865 @deftypevr {gdbmtool variable} string delim1
1866 A string used to delimit fields of a structured datum on output
1867 (@pxref{definitions}).
1869 Default is @samp{,} (a comma). This variable cannot be unset.
1872 @deftypevr {gdbmtool variable} string delim2
1873 A string used to delimit array items when printing a structured datum
1874 (@pxref{definitions}).
1876 Default is @samp{,} (a comma). This variable cannot be unset.
1879 @deftypevr {gdbmtool variable} string pager
1880 The name and command line of the pager program to pipe output to.
1881 This program is used in interactive mode when the estimated number of
1882 output lines is greater then the number of lines on your screen.
1884 The default value is inherited from the environment variable
1885 @env{PAGER}. Unsetting this variable disables paging.
1889 @deftypevr {gdbmtool variable} bool quiet
1890 Whether to display a welcome banner at startup. This variable should
1891 be set in a startup script file (@pxref{startup files}).
1895 @anchor{open parameters}
1896 The following variables control how the database is opened:
1898 @deftypevr {gdbmtool variable} numeric blocksize
1899 Sets the block size. @xref{Open, block_size}. Unset by default.
1902 @deftypevr {gdbmtool variable} numeric cachesize
1903 Sets the cache size. @xref{Options, GDBM_SETCACHESIZE}.
1904 By default this variable is not set.
1908 @deftypevr {gdbmtool variable} string open
1909 Open mode. The following values are allowed:
1913 Truncate the database if it exists or create a new one. Open it in
1916 Technically, this sets the @samp{GDBM_NEWDB} flag in call to @samp{gdbm_open}.
1917 @xref{Open, GDBM_NEWDB}.
1920 Open the database in read-write mode. Create it if it does not
1921 exist. This is the default.
1923 Technically speaking, it sets the @samp{GDBM_WRCREAT} flag in call to
1924 @code{gdbm_open}. @xref{Open, GDBM_WRCREAT}.
1927 Open the database in read-only mode. Signal an error if it does not
1930 This sets the @samp{GDBM_READER} flag (@pxref{Open, GDBM_READER}).
1933 Attempting to set any other value or to unset this variable produces
1938 @deftypevr {gdbmtool variable} number filemode
1939 File mode (in octal) for creating new database files and database
1943 @deftypevr {gdbmtool variable} bool lock
1944 Lock the database. This is the default.
1946 Setting this variable to false or unsetting it results in passing
1947 @samp{GDBM_NOLOCK} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOLOCK}).
1950 @deftypevr {gdbmtool variable} bool mmap
1951 Use memory mapping. This is the default.
1953 Setting this variable to false or unsetting it results in passing
1954 @samp{GDBM_NOMMAP} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOMMAP}).
1957 @deftypevr {gdbmtool variable} bool sync
1958 Flush all database writes on disk immediately. Default is false.
1959 @xref{Open, GDBM_SYNC}.
1962 The following commands are used to list or modify the variables:
1964 @deffn {command verb} set [@var{assignments}]
1965 When used without arguments, lists all variables and their values.
1966 Unset variables are shown after a comment sign (@samp{#}). For string
1967 and numeric variables, values are shown after an equals sign. For
1968 boolean variables, only the variable name is displayed if the variable
1969 is @samp{true}. If it is @samp{false}, its name is prefixed with
1981 # cachesize is unset
1982 # blocksize is unset
1992 If used with arguments, the @code{set} command alters the specified
1993 variables. In this case, arguments are variable assignments in the
1994 form @samp{@var{name}=@var{value}}. For boolean variables, the
1995 @var{value} is interpreted as follows: if it is numeric, @samp{0}
1996 stands for @samp{false}, any non-zero value stands for @samp{true}.
1997 Otherwise, the values @samp{on}, @samp{true}, and @samp{yes} denote
1998 @samp{true}, and @samp{off}, @samp{false}, @samp{no} stand for
1999 @samp{false}. Alternatively, only the name of a boolean variable can be
2000 supplied to set it to @samp{true}, and its name prefixed with
2001 @samp{no} can be used to set it to false. For example, the following
2002 command sets the @samp{delim2} variable to @samp{;} and the
2003 @samp{confirm} variable to @samp{false}:
2006 set delim2=";" noconfirm
2010 @deffn {command verb} unset @var{variables}
2011 Unsets the listed variables. The effect of unsetting depends on the
2012 variable. Unless explicitly described in the discussion of the
2013 variables above, unsetting a boolean variable is equivalent to setting it to
2014 @samp{false}. Unsetting a string variable is equivalent to assigning it
2019 @subsection Gdbmtool Commands
2021 @deffn {command verb} avail
2022 Print the @dfn{avail list}.
2025 @deffn {command verb} bucket @var{num}
2026 Print the bucket number @var{num} and set it as the current one.
2029 @deffn {command verb} cache
2030 Print the bucket cache.
2033 @deffn {command verb} close
2034 Close the currently open database.
2037 @deffn {command verb} count
2038 Print the number of entries in the database.
2041 @deffn {command verb} current
2042 Print the current bucket.
2045 @deffn {command verb} delete @var{key}
2046 Delete record with the given @var{key}
2049 @deffn {command verb} dir
2050 Print hash directory.
2053 @anchor{gdbmtool export}
2054 @deffn {command verb} export @var{file-name} [truncate] [binary|ascii]
2055 Export the database to the flat file @var{file-name}. @xref{Flat files},
2056 for a description of the flat file format and its purposes. This
2057 command will not overwrite an existing file, unless the
2058 @samp{truncate} parameter is also given. Another optional argument
2059 determines the type of the dump (@pxref{Flat files}). By default, ASCII
2062 The global variable @code{filemode} specifies the permissions to use
2063 for the created output file.
2065 See also @ref{gdbmexport}.
2068 @deffn {command verb} fetch @var{key}
2069 Fetch and display the record with the given @var{key}.
2072 @deffn {command verb} first
2073 Fetch and display the first record in the database. Subsequent
2074 records can be fetched using the @code{next} command (see below).
2075 @xref{Sequential}, for more information on sequential access.
2078 @deffn {command verb} hash @var{key}
2079 Compute and display the hash value for the given @var{key}.
2082 @deffn {command verb} header
2086 @deffn {command verb} help
2087 @deffnx {command verb} ?
2088 Print a concise command summary, showing each command verb
2089 with its parameters and a short description of what it does. Optional
2090 arguments are enclosed in square brackets.
2093 @anchor{gdbmtool import}
2094 @deffn {command verb} import @var{file-name} [replace] [nometa]
2095 Import data from a flat dump file @var{file-name}
2096 (@pxref{Flat files}). If the word @samp{replace} is given
2097 as an argument, any records with the same keys as the already
2098 existing ones will replace them. The word @samp{nometa} turns off
2099 restoring meta-information from the dump file.
2102 @deffn {command verb} list
2103 List the contents of the database.
2106 @deffn {command verb} next [@var{key}]
2107 Sequential access: fetch and display the next record. If the @var{key} is
2108 given, the record following the one with this key will be fetched.
2110 See also @code{first}, above.
2112 @xref{Sequential}, for more information on sequential access.
2115 @deffn {command verb} open @var{filename}
2116 Open the database file @var{filename}. If successful, any previously
2117 open database is closed. Otherwise, if the operation fails, the
2118 currently opened database remains unchanged.
2120 This command takes additional information from the following
2125 The database access mode. @xref{openvar,, The @var{open} variable},
2126 for a list of its values.
2128 Whether or not to lock the database. Default is @samp{on}.
2130 Use the memory mapping. Default is @samp{on}.
2132 Synchronize after each write. Default is @samp{off}.
2134 Specifies the permissions to use in case a new file is created.
2137 @xref{open parameters}, for a detailed description of these variables.
2140 @deffn {command verb} quit
2141 Close the database and quit the utility.
2144 @deffn {command verb} reorganize
2145 Reorganize the database (@pxref{Reorganization}).
2148 @deffn {command verb} source @var{filename}
2149 Read @command{gdbmtool} commands from the file @var{filename}.
2152 @deffn {command verb} status
2153 Print current program status. The following example shows the
2154 information displayed:
2157 Database file: junk.gdbm
2160 define content string
2163 The two @samp{define} strings show the defined formats for key and
2164 content data. @xref{definitions}, for a detailed discussion of their
2168 @deffn {command verb} store @var{key} @var{data}
2169 Store the @var{data} with @var{key} in the database. If @var{key}
2170 already exists, its data will be replaced.
2173 @deffn {command verb} version
2174 Print the version of @command{gdbm}.
2178 @subsection Data Definitions
2179 GDBM databases are able to keep data of any type, both in the key and
2180 in the content part of a record. Quite often these data are
2181 structured, i.e. they consist of several fields of various types.
2182 @command{Gdbmtool} provides a mechanism for handling such kind of
2185 The @code{define} command defines a record structure. The general
2189 define @var{what} @var{definition}
2193 where @var{what} is @samp{key} to defining the structure of key data and
2194 @samp{content} to define the structure of the content records.
2196 The @var{definition} can be of two distinct formats. In the simplest
2197 case it is a single data type. For example,
2204 defines content records consisting of a single integer field.
2205 Supported data types are:
2209 Single byte (signed).
2211 Signed short integer.
2213 Unsigned short integer.
2220 Signed long integer.
2222 Unsigned long integer.
2224 Signed long long integer.
2226 Unsigned long long integer.
2228 A floating point number.
2230 Double-precision floating point number.
2234 Null-terminated string, trailing null being part of the string.
2237 All numeric data types (integer as well as floating point) have the
2238 same respective widths as in C language on the host where the database
2241 The @samp{string} and @samp{stringz} are special. Both define a
2242 string of bytes, similar to @samp{char x[]} in C. The former
2243 defines an array of bytes, the latter - a null-terminated string.
2244 This makes a difference, in particular, when the string is the only
2245 part of datum. Consider the following two definitions:
2248 @item @code{define key string}
2249 @item @code{define key stringz}
2253 Now, suppose we want to store the string "ab" in the key. Using the
2254 definition (1), the @code{dptr} member of GDBM @code{datum} will
2255 contain two bytes: @samp{a}, and @samp{b}. Consequently, the
2256 @code{dsize} member will have the value 2. Using the definition (2),
2257 the @code{dptr} member will contain three bytes: @samp{a}, @samp{b},
2258 and ASCII 0. The @code{dsize} member will have the value 3.
2260 The definition (1) is the default for both key and content.
2262 The second form of the @code{define} statement is similar to the C
2263 @code{struct} statement and allows for defining structural data. In
2264 this form, the @var{definition} part is a comma-separated list of data
2265 types and variables enclosed in curly braces. In contrast to the
2266 rest of @command{gdbm} commands, this command is inherently
2267 multiline and is terminated with the closing curly brace. For
2280 This defines a structure consisting of three members: an integer
2281 @code{status}, an array of 8 bytes @code{id}, and a null-terminated
2282 string @code{name}. Notice the @code{pad} statement: it allows to
2283 introduce padding between structure members. Another useful statement
2284 is @code{offset}: it specifies that the member following it begins at
2285 the given offset in the structure. Assuming the size of @code{int} is
2286 8 bytes, the above definition can also be written as
2297 @emph{NOTE}: The @samp{string} type can reasonably be used only if it
2298 is the last or the only member of the data structure. That's because it
2299 provides no information about the number of elements in the array, so
2300 it is interpreted to contain all bytes up to the end of the datum.
2302 When displaying the structured data, @command{gdbmtool} precedes each
2303 value with the corresponding field name and delimits parts of the
2304 structure with the string defined in the @samp{delim1} variable
2305 (@pxref{variables}). Array elements are delimited using the string from
2306 @samp{delim2}. For example:
2310 status=2,id=@{ a, u, x @},name="quux"
2313 To supply a structured datum as an argument to a @command{gdbmtool}
2314 command, use the same notation, but without field names, e.g.:
2317 gdbmtool> hash @{ 2, @{a,u,x@}, "quux" @}
2318 hash value = 13089969.
2322 @subsection Startup Files
2323 @cindex startup file, gdbmtool
2324 @cindex init file, gdbmtool
2325 @flindex .gdbmtoolrc
2326 Upon startup @command{gdbmtool} looks for a file named
2327 @samp{.gdbmtoolrc} first in the current working directory and, if not
2328 found, in the home directory of the user who started the command.
2330 If found, this file is read and interpreted as a list of
2331 @command{gdbmtool} commands. This allows you to customize the
2334 Following is an example startup file which disables the welcome
2335 banner, sets command line prompt to contain the name of the database
2336 file in parentheses and defines the structure of the database content
2353 @chapter The @command{gdbm_dump} utility
2356 The @command{gdbm_dump} utility creates a flat file dump of a GDBM
2357 database (@pxref{Flat files}). It takes one mandatory argument: the
2358 name of the source database file. The second argument, if given,
2359 specifies the name of the output file. If not given,
2360 @command{gdbm_dump} will produce the dump on the standard output.
2362 For example, the following invocation creates a dump of the database
2363 @file{file.db} in the file @file{file.dump}:
2366 $ gdbm_dump file.db file.dump
2369 By default the utility creates dumps in ASCII format (@pxref{Flat
2370 files,ASCII}). Another format can be requested using the
2371 @option{--format} (@option{-H}) option.
2373 The @command{gdbm_dump} utility understands the following command line
2378 @itemx --format=@var{fmt}
2379 Select output format. Valid values for @var{fmt} are: @samp{binary}
2380 or @samp{0} to select binary dump format, and @samp{ascii} or @samp{1}
2381 to select ASCII format.
2385 Print a concise help summary.
2389 Print program version and licensing information and exit.
2392 Print a terse invocation syntax summary along with a list of available
2393 command line options.
2397 @chapter The @command{gdbm_load} utility
2400 The @command{gdbm_load} utility restores a GDBM database from a flat
2401 file. The utility requires at least one argument: the name of the
2402 input flat file. If it is @samp{-}, the standard input will be read.
2403 The format of the input file is detected automatically.
2405 By default the utility attempts to restore the database under its
2406 original name, as stored in the input file. It will fail to do so if
2407 the input is in binary format. In that case, the name of the database
2408 must be given as the second argument.
2410 In general, if two arguments are given the second one is treated as
2411 the name of the database to create, overriding the file name specified
2414 The utility understands the following command line arguments:
2419 @itemx --block-size=@var{num}
2420 Sets block size. @xref{Open, block_size}.
2423 @itemx --cache-size=@var{num}
2424 Sets cache size. @xref{Options, GDBM_SETCACHESIZE}.
2431 @item --mode=@var{mode}
2432 Sets the file mode. The argument is the desired file mode in octal.
2436 Do not restore file meta-data (ownership and mode) from the flat file.
2440 Replace existing keys.
2442 @item -u @var{user}[:@var{group}]
2443 @itemx --user=@var{user}[:@var{group}]
2444 Set file owner. The @var{user} can be either a valid user name or
2445 UID. Similarly, the @var{group} is either a valid group name or GID.
2446 If @var{group} is not given, the main group of @var{user} is used.
2448 User and group parts can be separated by a dot, instead of the colon.
2452 Print a concise help summary.
2456 Print program version and licensing information and exit.
2459 Print a terse invocation syntax summary along with a list of available
2460 command line options.
2464 @chapter Export a database into a portable format.
2467 The @command{gdbmexport} utility converts the database of an older
2468 GDBM version into a binary flat format.
2470 The utility takes two mandatory arguments: the name of the database
2471 file to convert and the output file name, e.g.:
2474 $ gdbmexport junk.gdbm junk.flat
2477 In addition the following two options are understood:
2481 Display short usage summary and exit.
2484 Display program version and licensing information, and exit.
2491 All GDBM utilities return uniform exit codes. These are summarized in
2494 @multitable @columnfractions 0.3 0.7
2495 @headitem Code @tab Meaning
2496 @item 0 @tab Successful termination.
2497 @item 1 @tab A fatal error occurred.
2498 @item 2 @tab Program was unable to restore file ownership or mode.
2499 @item 3 @tab Command line usage error.
2503 @chapter Problems and bugs.
2505 If you have problems with GNU @code{dbm} or think you've found a bug,
2506 please report it. Before reporting a bug, make sure you've actually
2507 found a real bug. Carefully reread the documentation and see if it
2508 really says you can do what you're trying to do. If it's not clear
2509 whether you should be able to do something or not, report that too; it's
2510 a bug in the documentation!
2512 Before reporting a bug or trying to fix it yourself, try to isolate it
2513 to the smallest possible input file that reproduces the problem. Then
2514 send us the input file and the exact results @code{gdbm} gave you. Also
2515 say what you expected to occur; this will help us decide whether the
2516 problem was really in the documentation.
2518 Once you've got a precise problem, send e-mail to
2519 @email{bug-gdbm@@gnu.org}.
2521 Please include the version number of GNU @code{dbm} you are using. You can get
2522 this information by printing the variable @code{gdbm_version}
2523 (@pxref{Variables}).
2525 Non-bug suggestions are always welcome as well. If you have questions
2526 about things that are unclear in the documentation or are just obscure
2527 features, please report them too.
2529 You may contact the authors and maintainers by e-mail:
2531 @email{phil@@cs.wwu.edu}, @email{downsj@@downsj.com}, @email{gray@@gnu.org.ua}
2535 @chapter Additional resources
2537 For the latest updates and pointers to additional resources, visit
2538 @uref{http://www.gnu.org/@/software/@/gdbm}.
2540 In particular, a copy of @code{gdbm} documentation in various formats
2541 is available online at @uref{http://www.gnu.org/@/software/@/gdbm/@/manual.html}.
2543 Latest versions of @code{gdbm} can be downloaded from anonymous FTP:
2544 @uref{ftp://ftp.gnu.org/@/gnu/@/gdbm}, or via HTTP from
2545 @uref{http://ftp.gnu.org/@/gnu/@/gdbm}, or from any
2547 @uref{http://www.gnu.org/order/ftp.html,,GNU mirror} worldwide.
2550 GNU mirror worldwide. See @uref{http://www.gnu.org/@/order/@/ftp.html},
2551 for a list of mirrors.
2554 To track @code{gdbm} development, visit
2555 @uref{http://puszcza.gnu.org.ua/@/projects/@/gdbm}.
2557 @node GNU Free Documentation License
2558 @appendix GNU Free Documentation License