aboutsummaryrefslogtreecommitdiff
path: root/doc/gdbm.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/gdbm.texi')
-rw-r--r--doc/gdbm.texi2567
1 files changed, 2567 insertions, 0 deletions
diff --git a/doc/gdbm.texi b/doc/gdbm.texi
new file mode 100644
index 0000000..6322a9b
--- /dev/null
+++ b/doc/gdbm.texi
@@ -0,0 +1,2567 @@
1\input texinfo @c -*- Texinfo -*-
2@comment $Id$
3@comment %**start of header (This is for running Texinfo on a region.)
4@setfilename gdbm.info
5@include version.texi
6@settitle GDBM manual
7
8@ifinfo
9@dircategory Programming & development tools
10@direntry
11* GDBM: (gdbm). The GNU database manager.
12* gdbm_dump: (gdbm) gdbm_dump. Dump the GDBM database into a flat file.
13* gdbm_load: (gdbm) gdbm_load. Load the database from a flat file.
14@end direntry
15@end ifinfo
16
17@c @setchapternewpage odd
18@comment %**end of header (This is for running Texinfo on a region.)
19
20@c Use @kwindex for keywords
21@defcodeindex kw
22@syncodeindex kw cp
23@c Use @flindex for files
24@defcodeindex fl
25@syncodeindex fl cp
26@c Use @prindex for programs
27@defcodeindex pr
28@syncodeindex pr cp
29
30@c Merge all indices into a single one
31@syncodeindex fn cp
32@syncodeindex vr cp
33@syncodeindex ky cp
34@syncodeindex pg cp
35@syncodeindex tp cp
36
37@iftex
38@finalout
39@end iftex
40
41@copying
42Published by the Free Software Foundation,
4351 Franklin Street, Fifth Floor
44Boston, MA 02110-1301, USA
45
46Copyright @copyright{} 1989-1999, 2007-2011 Free Software Foundation, Inc.
47
48Permission is granted to copy, distribute and/or modify this document
49under the terms of the GNU Free Documentation License, Version 1.3 or
50any later version published by the Free Software Foundation; with no
51Invariant Sections, no Front-Cover, and no Back-Cover texts.
52A copy of the license is included in the section entitled ``GNU Free
53Documentation License.''
54@end copying
55
56@titlepage
57@sp 6
58@center @titlefont{GNU dbm}
59@sp 2
60@center A Database Manager
61@sp 2
62@center by Philip A. Nelson, Jason Downs and Sergey Poznyakoff
63@sp 4
64@center Manual by Pierre Gaumond, Philip A. Nelson, Jason Downs
65@center and Sergey Poznyakoff
66@sp 1
67@center Edition @value{EDITION}
68@sp 1
69@center for GNU @code{dbm}, Version @value{VERSION}
70@page
71@vskip 0pt plus 1filll
72@insertcopying
73@end titlepage
74
75@ifnothtml
76@page
77@summarycontents
78@page
79@end ifnothtml
80@contents
81
82@ifnottex
83@node Top
84@top The GNU database manager.
85
86GNU @code{dbm} is a library of functions implementing a hashed database
87on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION}
88(@code{gdbm}). The software was originally written by Philip A.@:
89Nelson. This document was originally written by Pierre Gaumond from
90texts written by Phil.
91@end ifnottex
92
93@menu
94Introduction:
95
96* Copying:: Your rights.
97* Intro:: Introduction to GNU dbm.
98* List:: List of functions.
99
100Functions:
101
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.
115* Variables:: Useful global variables.
116
117* Error codes:: Error codes returned by @code{gdbm} calls.
118* Compatibility:: Compatibility with UNIX dbm and ndbm.
119
120Programs
121
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.
127
128Other topics:
129
130* Bugs:: Problems and bugs.
131* Resources:: Additional resources,
132
133* GNU Free Documentation License:: Document license.
134* Index:: Index
135@end menu
136
137@node Copying
138@chapter Copying Conditions.
139This library is @dfn{free}; this means that everyone is free to use
140it and free to redistribute it on a free basis. GNU @code{dbm} (@code{gdbm})
141is not in the public domain; it is copyrighted and there
142are restrictions on its distribution, but these restrictions are
143designed to permit everything that a good cooperating citizen would want
144to do. What is not allowed is to try to prevent others from further
145sharing any version of @code{gdbm} that they might get from
146you.@refill
147
148 Specifically, we want to make sure that you have the right to give
149away copies @code{gdbm}, that you receive
150source code or else can get it if you want it, that you can change these
151functions or use pieces of them in new free programs, and that you know
152you can do these things.@refill
153
154 To make sure that everyone has such rights, we have to forbid you to
155deprive anyone else of these rights. For example, if you distribute
156copies @code{gdbm}, you must give the recipients all
157the rights that you have. You must make sure that they, too, receive or
158can get the source code. And you must tell them their rights.@refill
159
160 Also, for our own protection, we must make certain that everyone finds
161out that there is no warranty for anything in the @code{gdbm} distribution.
162If these functions are modified by someone else and passed on, we want
163their recipients to know that what they have is not what we distributed,
164so that any problems introduced by others will not reflect on our
165reputation.@refill
166
167@code{Gdbm} is currently distributed under the terms of the GNU General
168Public License, Version 3. (@emph{NOT} under the GNU General Library
169Public License.) A copy the GNU General Public License is included with
170the distribution of @code{gdbm}.
171
172@node Intro
173@chapter Introduction to GNU @code{dbm}.
174
175GNU @code{dbm} (@code{gdbm}) is a library of database functions that use
176extensible hashing and works similar to the standard UNIX @code{dbm}
177functions. These routines are provided to a programmer needing to
178create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a
179complete database package for an end user.)
180
181The basic use of @code{gdbm} is to store key/data pairs in a data file.
182Each key must be unique and each key is paired with only one data item.
183The keys can not be directly accessed in sorted order. The basic unit
184of data in @code{gdbm} is the structure:
185
186@example
187 typedef struct @{
188 char *dptr;
189 int dsize;
190 @} datum;
191@end example
192
193This structure allows for arbitrary sized keys and data items.
194
195The 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
197to be able manipulate the keys and data contained in the database.
198@code{gdbm} allows an application to have multiple databases open at the
199same time. When an application opens a @code{gdbm} database, it is
200designated as a @code{reader} or a @code{writer}. A @code{gdbm}
201database can be opened by at most one writer at a time. However, many readers
202may open the database simultaneously. Readers and writers can not
203open the @code{gdbm} database at the same time.
204
205@node List
206@chapter List of functions.
207
208The following is a quick list of the functions contained in the @code{gdbm}
209library. The include file @code{gdbm.h}, that can be included by the user,
210contains a definition of these functions.
211
212@example
213#include <gdbm.h>
214
215GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func);
216void gdbm_close(dbf);
217int gdbm_store(dbf, key, content, flag);
218datum gdbm_fetch(dbf, key);
219int gdbm_delete(dbf, key);
220datum gdbm_firstkey(dbf);
221datum gdbm_nextkey(dbf, key);
222int gdbm_reorganize(dbf);
223void gdbm_sync(dbf);
224int gdbm_exists(dbf, key);
225char *gdbm_strerror(errno);
226int gdbm_setopt(dbf, option, value, size);
227int gdbm_fdesc(dbf);
228int gdbm_export (GDBM_FILE, const char *, int, int);
229int gdbm_export_to_file (GDBM_FILE dbf, FILE *fp);
230int gdbm_import (GDBM_FILE, const char *, int);
231int gdbm_import_from_file (GDBM_FILE dbf, FILE *fp, int flag);
232int gdbm_count (GDBM_FILE dbf, gdbm_count_t *pcount);
233int gdbm_version_cmp (int const a[], int const b[]);
234@end example
235
236The @code{gdbm.h} include file is often in the @file{/usr/include}
237directory. (The actual location of @code{gdbm.h} depends on your local
238installation of @code{gdbm}.)
239
240@node Open
241@chapter Opening the database.
242
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 *))
247Initializes @code{gdbm} system. If the file has a size of zero bytes, a file
248initialization procedure is performed, setting up the initial structure in the
249file.
250
251The arguments are:
252
253@table @var
254@item name
255The name of the file (the complete name, @code{gdbm} does not append any
256characters to this name).
257@item block_size
258It is used during initialization to determine the size of various
259constructs. It is the size of a single transfer from disk to
260memory. This parameter is ignored if the file has been previously
261initialized. The minimum size is 512. If the value is less than 512,
262the file system block size is used, otherwise the value of
263@var{block_size} is used.
264@item flags
265@kwindex GDBM_READER
266@kwindex GDBM_WRITER
267@kwindex GDBM_WRCREAT
268@kwindex GDBM_NEWDB
269If @code{flags} is set to @samp{GDBM_READER}, the user wants to just read the
270database and any call to @code{gdbm_store} or @code{gdbm_delete} will fail.
271Many readers can access the database at the same time. If @code{flags} is
272set to @samp{GDBM_WRITER}, the user wants both read and write access
273to the database and requires exclusive access. If @code{flags} is set
274to @samp{GDBM_WRCREAT}, the user wants both read and write access to
275the 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
277created, regardless of whether one existed, and wants read and write
278access to the new database.
279
280@kwindex GDBM_SYNC
281@kwindex GDBM_NOLOCK
282@kwindex GDBM_NOMMAP
283The following may also be logically or'd into the database flags:
284@samp{GDBM_SYNC}, which causes all database operations to be
285synchronized to the disk, @samp{GDBM_NOLOCK}, which prevents the library
286from performing any locking on the database file, and @samp{GDBM_NOMMAP},
287which disables the memory mapping mechanism. The option @samp{GDBM_FAST} is
288now obsolete, since @code{gdbm} defaults to no-sync mode.
289
290@kwindex GDBM_CLOEXEC
291@cindex close-on-exec
292If the host @samp{open} call
293@ifhtml
294(@uref{http://www.manpagez.com/man/2/open, open(2)})
295@end ifhtml
296@ifnothtml
297(@pxref{open,,,open(2),open(2) man page})
298@end ifnothtml
299supports the @samp{O_CLOEXEC} flag, the @samp{GDBM_CLOEXEC} can be
300or'd into the flags, to enable the close-on-exec flag for the
301database file descriptor.
302@item mode
303File mode (see
304@ifhtml
305@uref{http://www.manpagez.com/man/2/chmod},
306@end ifhtml
307@ifnothtml
308@ref{chmod,,change permissions of a file,chmod(2),
309chmod(2) man page},
310@end ifnothtml
311and
312@ifhtml
313@uref{http://www.manpagez.com/man/2/open}),
314@end ifhtml
315@ifnothtml
316@pxref{open,,open a file,open(2), open(2) man page}),
317@end ifnothtml
318which is used if the file is created).
319@item fatal_func
320A function for @code{gdbm} to call if it detects a fatal error. The only
321parameter of this function is a string. If the value of @samp{NULL} is
322provided, @code{gdbm} will use a default function.
323@end table
324
325The return value, is the pointer needed by all other functions to
326access 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
329error codes are discussed in @ref{Error codes}.
330
331In all of the following calls, the parameter @var{dbf} refers to the pointer
332returned from @code{gdbm_open}.
333@end deftypefn
334
335@node Close
336@chapter Closing the database.
337@cindex closing database
338@cindex database, closing
339
340It is important that every file opened is also closed. This is needed to
341update the reader/writer count on the file:
342
343@deftypefn {gdbm interface} void gdbm_close (GDBM_FILE @var{dbf})
344This function closes the @code{gdbm} file and frees all memory
345associated with it. The parameter is:
346
347@table @var
348@item dbf
349The pointer returned by @code{gdbm_open}.
350@end table
351@end deftypefn
352
353@node Count
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})
358Counts number of records in the database @var{dbf}. On success,
359stores it in the memory location pointed to by @var{pcount} and return
3600. On error, sets @code{gdbm_errno} (if relevant, also @code{errno})
361and returns -1.
362@end deftypefn
363
364@node Store
365@chapter Inserting and replacing records in the database.
366@cindex storing records
367@cindex records, storing
368
369@deftypefn {gdbm interface} int gdbm_store (GDBM_FILE @var{dbf}, datum @var{key}, @
370 datum @var{content}, int @var{flag})
371The function @code{gdbm_store} inserts or replaces records in the database.
372
373The parameters are:
374
375@table @var
376@item dbf
377The pointer returned by @code{gdbm_open}.
378@item key
379The search key.
380@item content
381The data to be associated with the key.
382@item flag
383@kwindex GDBM_REPLACE
384@kwindex GDBM_INSERT
385Defines 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
387be replaced by the new @var{content}. The value @samp{GDBM_INSERT}
388asks that an error be returned and no action taken if the @var{key}
389already exists.
390@end table
391
392This function can return the following values:
393
394@table @asis
395@item -1
396The item was not stored in the database because the caller was not an
397official writer or either @var{key} or @var{content} have a
398@samp{NULL} @samp{dptr} field.
399
400Both @var{key} and @var{content} must have the @samp{dptr} field be a
401non-@samp{NULL} value. Since a @samp{NULL} @samp{dptr} field is used by
402other functions to indicate an error, it cannot be valid data.
403@item +1
404The item was not stored because the argument @var{flag} was
405@samp{GDBM_INSERT} and the @var{key} was already in the database.
406@item 0
407No error. The value of @var{content} is keyed by @var{key}. The file
408on disk is updated to reflect the structure of the new database before
409returning from this function.
410@end table
411@end deftypefn
412
413If 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}.
417
418The size in @code{gdbm} is not restricted like @code{dbm} or @code{ndbm}. Your
419data can be as large as you want.
420
421@node Fetch
422@chapter Searching for records in the database.
423@cindex fetching records
424@cindex looking up records
425@cindex record, fetching
426
427@deftypefn {gdbm interface} datum gdbm_fetch (GDBM_FILE @var{dbf}, datum @var{key})
428Looks up a given @var{key} and returns the information associated with it.
429The @samp{dptr} field in the structure that is returned points to a
430memory block allocated by @code{malloc}. It is the caller's
431responsibility to free it when no longer needed.
432
433If the @samp{dptr} is @samp{NULL}, no data was found.
434
435The parameters are:
436
437@table @var
438@item dbf
439The pointer returned by @code{gdbm_open}.
440@item key
441The search key.
442@end table
443@end deftypefn
444
445An example of using this function:
446
447@example
448content = gdbm_fetch (dbf, key);
449if (content.dptr == NULL)
450 @{
451 fprintf(stderr, "key not found\n");
452 @}
453else
454 @{
455 /* do something with content.dptr */
456 @}
457@end example
458
459@cindex records, testing existence
460You may also search for a particular key without retrieving it:
461
462@deftypefn {gdbm interface} int gdbm_exists (GDBM_FILE @var{dbf}, datum @var{key})
463Returns @samp{true} (@samp{1}) if the @var{key} exists in @var{dbf}
464and @samp{false} (@samp{0}) otherwise.
465
466The parameters are:
467
468@table @var
469@item dbf
470The pointer returned by @code{gdbm_open}.
471@item key
472The search key.
473@end table
474@end deftypefn
475
476@node Delete
477@chapter Removing records from the database.
478@cindex deleting records
479@cindex record, deleting
480
481To remove some data from the database, use the @code{gdbm_delete}
482function.
483
484@deftypefn {gdbm interface} int gdbm_delete (GDBM_FILE @var{dbf}, datum @var{key})
485Deletes the data associated with the given @var{key}, if it exists in
486the database @var{dbf}. The file on disk is updated to reflect the
487structure of the new database before returning from this function.
488
489The parameters are:
490
491@table @var
492@item dbf
493The pointer returned by @code{gdbm_open}.
494@item datum key
495The search key.
496@end table
497
498The function returns @samp{-1} if the item is not present or the
499requester is a reader. The return of @samp{0} marks a successful delete.
500@end deftypefn
501
502@node Sequential
503@chapter Sequential access to records.
504@cindex sequential access
505@cindex iterating over records
506@cindex records, iterating over
507
508The next two functions allow for accessing all items in the database. This
509access 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
513@code{dbf}.
514
515@deftypefn {gdbm interface} datum gdbm_firstkey (GDBM_FILE @var{dbf})
516Initiate sequential access to the database @var{dbf}. The returned
517value is the first key accessed in the database. If the @samp{dptr}
518field in the returned datum is @samp{NULL}, the database contains no
519data.
520
521Otherwise, @samp{dptr} points to a memory block obtained from
522@code{malloc}, which holds the key value. The caller is responsible
523for freeing this memory block when no longer needed.
524@end deftypefn
525
526@deftypefn {gdbm interface} datum gdbm_nextkey (GDBM_FILE @var{dbf}, datum @var{prev})
527This function continues the iteration over the keys in @var{dbf},
528initiated by @code{gdbm_firstkey}. The parameter @var{prev} holds the
529value returned from a previous call to @code{gdbm_nextkey} or
530@code{gdbm_firstkey}.
531
532The function returns next key from the database. If the @samp{dptr}
533field in the returned datum is @samp{NULL}, all keys in the database
534has been visited.
535
536Otherwise, @samp{dptr} points to a memory block obtained from
537@code{malloc}, which holds the key value. The caller is responsible
538for freeing this memory block when no longer needed.
539@end deftypefn
540
541@cindex iteration loop
542These functions were intended to visit the database in read-only algorithms,
543for instance, to validate the database or similar operations. The
544usual algorithm for sequential access is:
545
546@example
547@group
548 key = gdbm_firstkey (dbf);
549 while (key.dptr)
550 @{
551 datum nextkey;
552
553 /* do something with the key */
554 ...
555
556 /* Obtain the next key */
557 nextkey = gdbm_nextkey (dbf, key);
558 /* Reclaim the memory used by the key */
559 free (key.dptr);
560 /* Use nextkey in the next iteration. */
561 key = nextkey;
562 @}
563@end group
564@end example
565
566@cindex iteration and @code{gdbm_delete}
567@cindex deletion in iteration loops
568@cindex @code{gdbm_delete} and sequential access
569Care should be taken when the @code{gdbm_delete} function is used in
570such 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
572that any collisions in the table do not leave some item
573@dfn{un-findable}. The original key order is @emph{not} guaranteed to
574remain unchanged in all instances. So it is possible that some key
575will not be visited if a loop like the following is executed:
576
577@example
578@group
579 key = gdbm_firstkey (dbf);
580 while (key.dptr)
581 @{
582 datum nextkey;
583 if (some condition)
584 @{
585 gdbm_delete (dbf, key);
586 @}
587 nextkey = gdbm_nextkey (dbf, key);
588 free (key.dptr);
589 key = nextkey;
590 @}
591@end group
592@end example
593
594@node Reorganization
595@chapter Database reorganization.
596@cindex database reorganization
597@cindex reorganization, database
598
599The following function should be used very seldom.
600
601@deftypefn {gdbm interface} int gdbm_reorganize (GDBM_FILE @var{dbf})
602Reorganizes the database.
603
604The parameter is:
605
606@table @var
607@item dbf
608The pointer returned by @code{gdbm_open}.
609@end table
610@end deftypefn
611
612If you have had a lot of deletions and would like to shrink the space
613used by the @code{gdbm} file, this function will reorganize the database.
614This results, in particular, in shortening the length of a @code{gdbm}
615file by removing the space occupied by deleted records.
616
617This reorganization requires creating a new file and inserting all the elements
618in the old file @var{dbf} into the new file. The new file is then renamed to
619the same name as the old file and @var{dbf} is updated to contain all the
620correct information about the new file. If an error is detected, the return
621value is negative. The value zero is returned after a successful
622reorganization.
623
624@node Sync
625@chapter Database Synchronization
626@cindex database synchronization
627@cindex synchronization, database
628
629@kwindex GDBM_SYNC
630Unless 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
632continuing. This allows for faster writing of databases at the risk
633of having a corrupted database if the application terminates in an
634abnormal fashion. The following function allows the programmer to
635make sure the disk version of the database has been completely updated
636with all changes to the current time.
637
638@deftypefn {gdbm interface} void gdbm_sync (GDBM_FILE @var{dbf})
639Synchronizes the changes in @var{dbf} with its disk file. The
640parameter is a pointer returned by @code{gdbm_open}.
641
642This function would usually be called after a complete set of changes
643have been made to the database and before some long waiting time.
644The @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
646immediately after the set of changes have been made.
647@end deftypefn
648
649@node Flat files
650@chapter Export and Import
651@cindex Flat file format
652@cindex export
653@cindex import
654@code{Gdbm} databases can be converted into so-called @dfn{flat
655format} files. Such files cannot be used for searching, their sole
656purpose is to keep the data from the database for restoring it when
657the need arrives. There are two flat file formats, which differ in
658the way they represent the data and in the amount of meta-information
659stored. Both formats can be used, for example, to migrate between
660the different versions of @code{gdbm} databases. Generally speaking,
661flat files are safe to send over the network, and can be used to
662recreate the database on another machine. The recreated database is
663guaranteed to be a byte-to-byte equivalent of the database from which
664the flat file was created. This does not necessarily mean, however,
665that this file can be used in the same way as the original one. For
666example, if the original database contained non-@acronym{ASCII} data
667(e.g.@: @acronym{C} structures, integers etc.), the recreated database
668can be of any use only if the target machine has the same integer
669size and byte ordering as the source one and if its @acronym{C}
670compiler uses the same packing conventions as the one which generated
671@acronym{C} which populated the original database. In general, such
672binary databases are not portable between machines, unless you follow
673some stringent rules on what data is written to them and how it is
674interpreted.
675
676The GDBM version @value{VERSION} supports two flat file formats. The
677@dfn{binary} flat file format was first implemented in GDBM version
6781.9.1. This format stores only key/data pairs, it does not keep
679information about the database file itself. As its name implies,
680files in this format are binary files.
681
682The @dfn{ascii} flat file format encodes all data in base64 and stores
683not only key/data pairs, but also the original database file metadata,
684such as file name, mode and ownership. Files in this format can be
685sent without additional encapsulation over transmission channels that
686normally allow only ASCII data, such as, e.g.@: SMTP. Due to additional
687metadata they allow for restoring an exact copy of the database,
688including file ownership and privileges, which is especially important
689if the database in question contained some security-related data.
690
691We call a process of creating a flat file from a database
692@dfn{exporting} or @dfn{dumping} this database. The reverse process,
693creating the database from a flat file is called @dfn{importing} or
694@dfn{loading} the database.
695
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})
699Dumps the database file to the named file in requested format.
700Arguments are:
701
702@table @var
703@item dbf
704A pointer to the source database, returned by a prior call to
705@code{gdbm_open}.
706
707@item filename
708Name of the dump file.
709
710@item format
711Output file format. Allowed values are: @samp{GDBM_DUMP_FMT_BINARY} to
712create a binary dump and @samp{GDBM_DUMP_FMT_ASCII} to create an ASCII
713dump file.
714
715@item open_flags
716How to create the output file. If @var{flag} is @samp{GDBM_WRCREAT}
717the file will be created if it does not exist. If it does exist,
718the @code{gdbm_dump} will fail.
719
720If @var{flag} is @samp{GDBM_NEWDB}, the function will create a new
721output file, replacing it if it already exists.
722
723@item mode
724The permissions to use when creating the output file.
725@ifhtml
726See @uref{http://www.manpagez.com/man/2/open},
727@end ifhtml
728@ifnothtml
729See @ref{open,,open a file,open(2), open(2) man page},
730@end ifnothtml
731for a detailed discussion.
732@end table
733@end deftypefn
734
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})
740Loads data from the dump file @var{filename} into the database pointed
741to by @var{pdbf}. The latter can point to @samp{NULL}, in which case
742the function will try to create a new database. If it succeeds, the
743function will return, in the memory location pointed to by @var{pdbf},
744a pointer to the newly created database. If the dump file carries no
745information about the original database file name, the function will
746set @code{gdbm_errno} to @samp{GDBM_NO_DBNAME} and return
747@samp{-1}, indicating failure.
748
749The @var{flag} has the same meaning as the @var{flag} argument
750to the @code{gdbm_store} function (@pxref{Store}).
751
752The @var{meta_mask} argument can be used to disable restoring certain
753bits of file's meta-data from the information in the input dump file.
754It is a binary OR of zero or more of the following:
755
756@table @asis
757@item GDBM_META_MASK_MODE
758Do not restore file mode.
759
760@item GDBM_META_MASK_OWNER
761Do not restore file owner.
762@end table
763
764The function returns 0 upon successful completion or -1 on fatal
765errors and 1 on mild (non-fatal) errors.
766
767If a fatal error occurs, @code{gdbm_errno} will be set to one of the
768following values:
769
770@table @asis
771@item GDBM_FILE_OPEN_ERROR
772Input file (@var{filename}) cannot be opened. The @code{errno}
773variable can be used to get more detail about the failure.
774
775@item GDBM_MALLOC_ERROR
776Not enough memory to load data.
777
778@item GDBM_FILE_READ_ERROR
779Reading from @var{filename} failed. The @code{errno} variable can be
780used to get more detail about the failure.
781
782@item GDBM_ILLEGAL_DATA
783Input contained some illegal data.
784
785@item GDBM_ITEM_NOT_FOUND
786This error can occur only when the input file is in ASCII format. It
787indicates that the data part of the record about to be read lacked
788length specification. Application developers are advised to treat
789this error equally as @samp{GDBM_ILLEGAL_DATA}.
790@end table
791
792Mild errors mean that the function was able to successfully load and
793restore the data, but was unable to change database file metadata
794afterward. The table below lists possible values for @code{gdbm_errno}
795in this case. To get more detail, inspect the system @code{errno} variable.
796
797@table @asis
798@kwindex GDBM_ERR_FILE_OWNER
799@item GDBM_ERR_FILE_OWNER
800The function was unable to restore database file owner.
801
802@kwindex GDBM_ERR_FILE_MODE
803@item GDBM_ERR_FILE_MODE
804The function was unable to restore database file mode (permission bits).
805@end table
806
807If an error occurs while loading data from an input file in ASCII
808format, the number of line in which the error occurred will be stored
809in the location pointed to by the @var{errline} parameter, unless it
810is @samp{NULL}.
811
812If the line information is not available or applicable, @var{errline}
813will be set to @samp{0}.
814@end deftypefn
815
816@deftypefn {gdbm interface} int gdbm_dump_to_file (GDBM_FILE @var{dbf}, @
817 FILE *@var{fp}, int @var{format})
818This is an alternative entry point to @code{gdbm_dump} (which see).
819Arguments are:
820
821@table @var
822@item dbf
823A pointer to the source database, returned by a call to
824@code{gdbm_open}.
825
826@item fp
827File to write the data to.
828
829@item format
830Format of the dump file. See the @var{format} argument to the
831@code{gdbm_dump} function.
832@end table
833@end deftypefn
834
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})
838This is an alternative entry point to @code{gdbm_dump}. It writes the
839output to @var{fp} which must be a file open for writing. The rest of
840arguments is the same as for @code{gdbm_load} (excepting of course
841@var{flag}, which is not needed in this case).
842@end deftypefn
843
844@deftypefn {gdbm interface} int gdbm_export (GDBM_FILE @var{dbf}, @
845 const char *@var{exportfile}, int @var{flag}, int @var{mode})
846This function is retained for compatibility with GDBM 1.10 and
847earlier. It dumps the database to a file in binary dump format and
848is entirely equivalent to
849
850@example
851gdbm_dump(@var{dbf}, @var{exportfile}, GDBM_DUMP_FMT_BINARY,
852 @var{flag}, @var{mode})
853@end example
854
855@end deftypefn
856
857@deftypefn {gdbm interface} int gdbm_export_to_file (GDBM_FILE @var{dbf}, FILE *@var{fp})
858This is an alternative entry point to @code{gdbm_export}. This
859function writes to file @var{fp} a binary dump of the database @var{dbf}.
860@end deftypefn
861
862@deftypefn {gdbm interface} int gdbm_import (GDBM_FILE @var{dbf}, @
863 const char *@var{importfile}, int @var{flag})
864This function is retained for compatibility with GDBM 1.10 and
865earlier. It loads the file @var{importfile}, which must be a binary
866flat file, into the database @var{dbf} and is equivalent to the
867following construct:
868
869@example
870@var{dbf} = gdbm_open (@var{importfile}, 0,
871 @var{flag} == GDBM_REPLACE ?
872 GDBM_WRCREAT : GDBM_NEWDB,
873 0600, NULL);
874gdbm_load (&@var{dbf}, @var{exportfile}, 0, @var{flag}, NULL)
875@end example
876@end deftypefn
877
878@deftypefn {gdbm interface} int gdbm_import_from_file (GDBM_FILE @var{dbf}, @
879 FILE *@var{fp}, int @var{flag})
880An alternative entry point to @code{gdbm_import}. Reads the binary
881dump from the file @var{fp} and stores the key/value pairs to
882@var{dbf}. @xref{Store}, for a description of @var{flag}.
883
884This function is equivalent to:
885
886@example
887@var{dbf} = gdbm_open (@var{importfile}, 0,
888 @var{flag} == GDBM_REPLACE ?
889 GDBM_WRCREAT : GDBM_NEWDB,
890 0600, NULL);
891gdbm_load_from_file (@var{dbf}, @var{fp}, @var{flag}, 0, NULL);
892@end example
893@end deftypefn
894
895@node Errors
896@chapter Error strings.
897@cindex error strings
898
899To convert a @code{gdbm} error code into English text, use this
900routine:
901
902@deftypefn {gdbm interface} {const char *} gdbm_strerror (gdbm_error @var{errno})
903Converts @var{errno} (which is an integer value) into a human-readable
904descriptive text. Returns a pointer to a static string. The caller
905must not alter or free the returned pointer.
906
907The @var{errno} argument is usually the value of the global variable
908@code{gdbm_errno}. @xref{Variables, gdbm_errno}.
909@end deftypefn
910
911@node Options
912@chapter Setting options
913@cindex database options
914@cindex options, database
915
916@code{Gdbm} supports the ability to set certain options on an already
917open database.
918
919@deftypefn {gdbm interface} int gdbm_setopt (GDBM_FILE @var{dbf}, int @var{option}, @
920 void *@var{value}, int @var{size})
921Sets an option on the database or returns the value of an option.
922
923The parameters are:
924
925@table @var
926@item dbf
927The pointer returned by @code{gdbm_open}.
928@item option
929The option to be set or retrieved.
930@item value
931A pointer to the value to which @var{option} will be set or where to
932place the option value (depending on the option).
933@item size
934The length of the data pointed to by @var{value}.
935@end table
936@end deftypefn
937
938The valid options are:
939
940@table @asis
941@kwindex GDBM_CACHESIZE
942@kwindex GDBM_SETCACHESIZE
943@item GDBM_SETCACHESIZE
944@itemx GDBM_CACHESIZE
945Set the size of the internal bucket cache. This option may only be
946set once on each GDBM_FILE descriptor, and is set automatically to 100
947upon the first access to the database. The @var{value} should point
948to a @code{size_t} holding the desired cache size.
949
950The @samp{GDBM_CACHESIZE} option is provided for compatibility with
951earlier versions.
952
953@kwindex GDBM_GETCACHESIZE
954@item GDBM_GETCACHESIZE
955Return the size of the internal bucket cache. The @var{value} should
956point to a @code{size_t} variable, where the size will be stored.
957
958@kwindex GDBM_GETFLAGS
959@item GDBM_GETFLAGS
960Return the flags describing the state of the database. The @var{value} should
961point to a @code{int} variable where to store the flags. The return
962is the same as the flags used when opening the database (@pxref{Open,
963gdbm_open}), except that it reflects the current state (which may have
964been altered by another calls to @code{gdbm_setopt}.
965
966@kwindex GDBM_FASTMODE
967@item GDBM_FASTMODE
968Enable or disable the @dfn{fast writes mode}, i.e.@: writes without
969subsequent synchronization. The @var{value} should point
970to an integer: @samp{TRUE} to enable fast mode, and @samp{FALSE} to
971disable it.
972
973This option is retained for compatibility with previous versions of
974@code{gdbm}. Its effect is the reverse of @code{GDBM_SETSYNCMODE}
975(see below).
976
977@kwindex GDBM_SETSYNCMODE
978@kwindex GDBM_SYNCMODE
979@item GDBM_SETSYNCMODE
980@itemx GDBM_SYNCMODE
981Turn on or off file system synchronization operations. This
982setting defaults to off. The @var{value} should point
983to an integer: @samp{TRUE} to turn synchronization on, and @samp{FALSE} to
984turn it off.
985
986Note, that this option is a reverse of @code{GDBM_FASTMODE},
987i.e.@: calling @code{GDBM_SETSYNCMODE} with @samp{TRUE} has the same effect
988as calling @code{GDBM_FASTMODE} with @samp{FALSE}.
989
990The @samp{GDBM_SYNCMODE} option is provided for compatibility with
991earlier versions.
992
993@kwindex GDBM_GETSYNCMODE
994@item GDBM_GETSYNCMODE
995Return the current synchronization status. The @var{value} should
996point to an @code{int} where the status will be stored.
997
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.}
1003
1004Set central free block pool to either on or off. The default is off,
1005which is how previous versions of @code{gdbm} handled free blocks. If
1006set, 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
1008more quickly. The @var{value} should point to an integer: @samp{TRUE} to
1009turn central block pool on, and @samp{FALSE} to turn it off.
1010
1011The @samp{GDBM_CENTFREE} option is provided for compatibility with
1012earlier versions.
1013
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.}
1019
1020Set free block merging to either on or off. The default is off, which
1021is how previous versions of @code{gdbm} handled free blocks. If set,
1022this option causes adjacent free blocks to be merged. This can become
1023a @acronym{CPU} expensive process with time, though, especially if
1024used in conjunction with GDBM_CENTFREE. The @var{value} should point
1025to an integer: @samp{TRUE} to turn free block merging on, and @samp{FALSE} to
1026turn it off.
1027
1028@kwindex GDBM_GETCOALESCEBLKS
1029@item GDBM_GETCOALESCEBLKS
1030Return the current status of free block merging. The @var{value} should
1031point to an @code{int} where the status will be stored.
1032
1033@kwindex GDBM_SETMAXMAPSIZE
1034@item GDBM_SETMAXMAPSIZE
1035Sets maximum size of a memory mapped region. The @var{value} should
1036point to a value of type @code{size_t}, @code{unsigned long} or
1037@code{unsigned}. The actual value is rounded to the nearest page
1038boundary (the page size is obtained from
1039@code{sysconf(_SC_PAGESIZE)}).
1040
1041@kwindex GDBM_GETMAXMAPSIZE
1042@item GDBM_GETMAXMAPSIZE
1043Return the maximum size of a memory mapped region. The @var{value} should
1044point to a value of type @code{size_t} where to return the data.
1045
1046@kwindex GDBM_SETMMAP
1047@item GDBM_SETMMAP
1048Enable or disable memory mapping mode. The @var{value} should point
1049to an integer: @samp{TRUE} to enable memory mapping or @samp{FALSE} to
1050disable it.
1051
1052@kwindex GDBM_GETMMAP
1053@item GDBM_GETMMAP
1054Check whether memory mapping is enabled. The @var{value} should point
1055to an integer where to return the status.
1056
1057@kwindex GDBM_GETDBNAME
1058@item GDBM_GETDBNAME
1059Return the name of the database disk file. The @var{value} should
1060point to a variable of type @code{char**}. A pointer to the newly
1061allocated copy of the file name will be placed there. The caller is
1062responsible for freeing this memory when no longer needed. For
1063example:
1064
1065@example
1066char *name;
1067
1068if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
1069 @{
1070 fprintf (stderr, "gdbm_setopt failed: %s\n",
1071 gdbm_strerror (gdbm_errno));
1072 @}
1073else
1074 @{
1075 printf ("database name: %s\n", name);
1076 free (name);
1077 @}
1078@end example
1079
1080@end table
1081
1082The return value will be @samp{-1} upon failure, or @samp{0} upon
1083success. The global variable @code{gdbm_errno} will be set upon failure.
1084
1085For instance, to set a database to use a cache of 10, after opening it
1086with @code{gdbm_open}, but prior to accessing it in any way, the following
1087code could be used:
1088
1089@example
1090@group
1091int value = 10;
1092ret = gdbm_setopt (dbf, GDBM_CACHESIZE, &value, sizeof (int));
1093@end group
1094@end example
1095
1096@node Locking
1097@chapter File Locking.
1098@cindex locking
1099
1100@kwindex GDBM_NOLOCK
1101With locking disabled (if @code{gdbm_open} was called with @samp{GDBM_NOLOCK}),
1102the user may want to perform their own file locking on the database file
1103in order to prevent multiple writers operating on the same file
1104simultaneously.
1105
1106In order to support this, the @code{gdbm_fdesc} routine is provided.
1107
1108@deftypefn {gdbm interface} int gdbm_fdesc (GDBM_FILE @var{dbf})
1109Returns the file descriptor of the database @var{dbf}. This value
1110can be used as an argument to @code{flock}, @code{lockf} or similar
1111calls.
1112@end deftypefn
1113
1114@node Variables
1115@chapter Useful global variables.
1116
1117The following global variables and constants are available:
1118
1119@deftypevar gdbm_error gdbm_errno
1120This variable contains error code from the last failed @code{gdbm}
1121call. @xref{Error codes}, for a list of available error codes and
1122their descriptions.
1123
1124Use @code{gdbm_strerror} (@pxref{Errors}) to convert it to a
1125descriptive text.
1126@end deftypevar
1127
1128@deftypevar {const char *} gdbm_errlist[]
1129This 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
1132contains @code{_GDBM_MAX_ERRNO + 1} elements and can be directly
1133indexed by the error code to obtain a corresponding descriptive
1134text.
1135@end deftypevar
1136
1137@defvr {Constant} _GDBM_MIN_ERRNO
1138The minimum error code used by @code{gdbm}.
1139@end defvr
1140
1141@defvr {Constant} _GDBM_MAX_ERRNO
1142The maximum error code used by @code{gdbm}.
1143@end defvr
1144
1145@cindex version number
1146@deftypevar {const char *} gdbm_version
1147A string containing the version information.
1148@end deftypevar
1149
1150@deftypevar {int const} gdbm_version_number[3]
1151This variable contains the @code{gdbm} version numbers:
1152
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
1158@end multitable
1159
1160Additionally, the following constants are defined in the @file{gdbm.h}
1161file:
1162
1163@table @asis
1164@kwindex GDBM_VERSION_MAJOR
1165@item GDBM_VERSION_MAJOR
1166Major number.
1167
1168@kwindex GDBM_VERSION_MINOR
1169@item GDBM_VERSION_MINOR
1170Minor number.
1171
1172@kwindex GDBM_VERSION_PATCH
1173@item GDBM_VERSION_PATCH
1174Patchlevel number.
1175@end table
1176
1177These can be used to verify whether the header file matches the library.
1178@end deftypevar
1179
1180To compare two split-out version numbers, use the following function:
1181
1182@deftypefn {gdbm interface} int gdbm_version_cmp (int const @var{a}[3], @
1183 int const @var{b}[3])
1184Compare 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
1186they are equal.
1187
1188Comparison is done from left to right, so that:
1189
1190@example
1191a = @{ 1, 8, 3 @};
1192b = @{ 1, 8, 3 @};
1193gdbm_version_cmp (a, b) @result{} 0
1194
1195a = @{ 1, 8, 3 @};
1196b = @{ 1, 8, 2 @};
1197gdbm_version_cmp (a, b) @result{} 1
1198
1199a = @{ 1, 8, 3 @};
1200b = @{ 1, 9. 0 @};
1201gdbm_version_cmp (a, b) @result{} -1
1202@end example
1203@end deftypefn
1204
1205@node Error codes
1206@chapter Error codes
1207@cindex error codes
1208
1209This chapter summarizes error codes which can be set by the
1210functions in @code{gdbm} library.
1211
1212@table @asis
1213@kwindex GDBM_NO_ERROR
1214@item GDBM_NO_ERROR
1215No error occurred.
1216
1217@kwindex GDBM_MALLOC_ERROR
1218@item GDBM_MALLOC_ERROR
1219Memory allocation failed. Not enough memory.
1220
1221@kwindex GDBM_BLOCK_SIZE_ERROR
1222@item GDBM_BLOCK_SIZE_ERROR
1223This error is set by the @code{gdbm_open} function (@pxref{Open}), if
1224the value of its @var{block_size} argument is incorrect.
1225
1226@kwindex GDBM_FILE_OPEN_ERROR
1227@item GDBM_FILE_OPEN_ERROR
1228The 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}).
1231
1232Inspect the value of the system @code{errno} variable to get more
1233detailed diagnostics.
1234
1235@kwindex GDBM_FILE_WRITE_ERROR
1236@item GDBM_FILE_WRITE_ERROR
1237Writing 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.
1240
1241Inspect the value of the system @code{errno} variable to get more
1242detailed diagnostics.
1243
1244@kwindex GDBM_FILE_SEEK_ERROR
1245@item GDBM_FILE_SEEK_ERROR
1246Positioning in a disk file failed. This can be set by
1247@code{gdbm_open} (@pxref{Open}) function.
1248
1249Inspect the value of the system @code{errno} variable to get a more
1250detailed diagnostics.
1251
1252@kwindex GDBM_FILE_READ_ERROR
1253@item GDBM_FILE_READ_ERROR
1254Reading 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.
1257
1258Inspect the value of the system @code{errno} variable to get a more
1259detailed diagnostics.
1260
1261@kwindex GDBM_BAD_MAGIC_NUMBER
1262@item GDBM_BAD_MAGIC_NUMBER
1263The file given as argument to @code{gdbm_open} function is not a valid
1264@code{gdbm} file: it has a wrong magic number.
1265
1266@kwindex GDBM_EMPTY_DATABASE
1267@item GDBM_EMPTY_DATABASE
1268The file given as argument to @code{gdbm_open} function is not a valid
1269@code{gdbm} file: it has zero length.
1270
1271@kwindex GDBM_CANT_BE_READER
1272@item GDBM_CANT_BE_READER
1273This error code is set by the @code{gdbm_open} function if it is not
1274able to lock file when called in @samp{GDBM_READER} mode (@pxref{Open,
1275GDBM_READER}).
1276
1277@kwindex GDBM_CANT_BE_WRITER
1278@item GDBM_CANT_BE_WRITER
1279This error code is set by the @code{gdbm_open} function if it is not
1280able to lock file when called in writer mode (@pxref{Open}).
1281
1282@kwindex GDBM_READER_CANT_DELETE
1283@item GDBM_READER_CANT_DELETE
1284Set by the @code{gdbm_delete} (@pxref{Delete}) if it attempted to
1285operate on a database that is open in read-only mode (@pxref{Open,
1286GDBM_READER}).
1287
1288@kwindex GDBM_READER_CANT_STORE
1289@item GDBM_READER_CANT_STORE
1290Set by the @code{gdbm_store} (@pxref{Store}) if it attempted to
1291operate on a database that is open in read-only mode (@pxref{Open,
1292GDBM_READER}).
1293
1294@kwindex GDBM_READER_CANT_REORGANIZE
1295@item GDBM_READER_CANT_REORGANIZE
1296Set by the @code{gdbm_reorganize} (@pxref{Reorganization}) if it attempted to
1297operate on a database that is open in read-only mode (@pxref{Open,
1298GDBM_READER}).
1299
1300@kwindex GDBM_UNKNOWN_UPDATE
1301@item GDBM_UNKNOWN_UPDATE
1302Currently unused. Reserved for future uses.
1303
1304@kwindex GDBM_ITEM_NOT_FOUND
1305@item GDBM_ITEM_NOT_FOUND
1306Requested 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.
1309
1310@kwindex GDBM_REORGANIZE_FAILED
1311@item GDBM_REORGANIZE_FAILED
1312The @code{gdbm_reorganize} function is not
1313able to create a temporary database. @xref{Reorganization}.
1314
1315@kwindex GDBM_CANNOT_REPLACE
1316@item GDBM_CANNOT_REPLACE
1317Cannot replace existing item. This error is set by the
1318@code{gdbm_store} if the requested @var{key} value is found in the
1319database and the @var{flag} parameter is not @samp{GDBM_REPLACE}.
1320@xref{Store}, for a detailed discussion.
1321
1322@kwindex GDBM_ILLEGAL_DATA
1323@item GDBM_ILLEGAL_DATA
1324Either @var{key} or @var{content} parameter was wrong in a call to
1325to @code{gdbm_store} (@pxref{Store}).
1326
1327@kwindex GDBM_OPT_ALREADY_SET
1328@item GDBM_OPT_ALREADY_SET
1329Requested option can be set only once and was already set. This error
1330is returned by the @code{gdbm_setopt} function. @xref{Options,
1331GDBM_CACHESIZE}.
1332
1333@kwindex GDBM_OPT_ILLEGAL
1334@item GDBM_OPT_ILLEGAL
1335The @var{option} argument is not valid or the @var{value} argument
1336points to an invalid value in a call to @code{gdbm_setopt} function.
1337@xref{Options}.
1338
1339@kwindex GDBM_BYTE_SWAPPED
1340@item GDBM_BYTE_SWAPPED
1341The @code{gdbm_open} function (@pxref{Open}) attempts to open a
1342database which is created on a machine with different byte ordering.
1343
1344@kwindex GDBM_BAD_FILE_OFFSET
1345@item GDBM_BAD_FILE_OFFSET
1346The @code{gdbm_open} function (@pxref{Open}) sets this error code if
1347the file it tries to open has a wrong magic number.
1348
1349@kwindex GDBM_BAD_OPEN_FLAGS
1350@item GDBM_BAD_OPEN_FLAGS
1351Set by the @code{gdbm_export} function if supplied an invalid
1352@var{flags} argument. @xref{Flat files}.
1353
1354@kwindex GDBM_FILE_STAT_ERROR
1355@item GDBM_FILE_STAT_ERROR
1356Getting information about a disk file failed. The system @code{errno}
1357will give more details about the error.
1358
1359This error can be set by the following functions: @code{gdbm_open},
1360@code{gdbm_reorganize}.
1361
1362@kwindex GDBM_FILE_EOF
1363@item GDBM_FILE_EOF
1364End of file was encountered where more data was expected to be
1365present. This error can occur when fetching data from the database
1366and usually means that the database is truncated or otherwise corrupted.
1367
1368This error can be set by any GDBM function that does I/O. Some of
1369these 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},
1372@code{gdbm_store}.
1373
1374@kwindex GDBM_NO_DBNAME
1375@item GDBM_NO_DBNAME
1376Output database name is not specified. This error code is set by
1377@code{gdbm_load} (@pxref{gdbm_load function,,gdbm_load}) if the first
1378argument points to @samp{NULL} and the input file does not specify the
1379database name.
1380
1381@kwindex GDBM_ERR_FILE_OWNER
1382@item GDBM_ERR_FILE_OWNER
1383This error code is set by @code{gdbm_load} if it is unable to restore
1384database file owner. It is a mild error condition, meaning that the
1385data have been restored successfully, only changing the target file
1386owner failed. Inspect the system @code{errno} variable to get a more
1387detailed diagnostics.
1388
1389@kwindex GDBM_ERR_FILE_MODE
1390@item GDBM_ERR_FILE_MODE
1391This error code is set by @code{gdbm_load} if it is unable to restore
1392database file mode. It is a mild error condition, meaning that the data
1393have been restored successfully, only changing the target file owner
1394failed. Inspect the system @code{errno} variable to get a more
1395detailed diagnostics.
1396
1397@end table
1398
1399@node Compatibility
1400@chapter Compatibility with standard @code{dbm} and @code{ndbm}.
1401
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
1405installed if the @option{--enable-libgdbm-compat} option is used when
1406configuring the package.
1407
1408@findex ndbm.h
1409@findex dbm.h
1410@findex libgdbm_compat
1411The compatibility layer consists of two header files: @file{ndbm.h}
1412and @file{dbm.h} and the @file{libgdbm_compat} library.
1413
1414Older programs using @code{ndbm} or @code{dbm} interfaces can
1415use @file{libgdbm_compat} without any changes. To link a program with
1416the compatibility library, add the following two options to the
1417@command{cc} invocation: @option{-lgdbm -lgdbm_compat}. The @option{-L}
1418option may also be required, depending on where @code{gdbm} is
1419installed, e.g.:
1420
1421@example
1422cc ... -lgdbm -lgdbm_compat
1423@end example
1424
1425@cindex @samp{dir} file
1426@cindex @samp{pag} file
1427Databases created and manipulated by the compatibility interfaces
1428consist of two different files: @file{@var{file}.dir} and
1429@file{@var{file}.pag}. This is required by the @acronym{POSIX}
1430specification and corresponds to the traditional usage. Note,
1431however, that despite the similarity of the naming convention,
1432actual data stored in these files has not the same format as
1433in the databases created by other @code{dbm} or @code{ndbm}
1434libraries. In other words, you cannot access a standard UNIX
1435@code{dbm} file with GNU @code{dbm}!
1436
1437GNU @code{dbm} files are not @code{sparse}. You can copy them with
1438the usual @code{cp} command and they will not expand in the copying
1439process.
1440
1441@menu
1442* ndbm:: NDBM interface functions.
1443* dbm:: DBM interface functions.
1444@end menu
1445
1446@node ndbm
1447@section NDBM interface functions.
1448@cindex NDBM functions
1449
1450The functions below implement the @acronym{POSIX} @samp{ndbm} interface:
1451
1452@deftypefn {ndbm} {DBM *} dbm_open (char *@var{file}, int @var{flags}, int @var{mode})
1453Opens a database. The @var{file} argument is the full name of the
1454database 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
1457arguments of
1458@ifhtml
1459@uref{http://www.manpagez.com/man/2/open,,open(2)},
1460@end ifhtml
1461@ifnothtml
1462@code{open} (@pxref{open,,open a file,open(2), open(2) man page}),
1463@end ifnothtml
1464except that a database opened for write-only access opens the files
1465for read and write access and the behavior of the @code{O_APPEND} flag is
1466unspecified.
1467
1468The function returns a pointer to the @code{DBM} structure describing
1469the database. This pointer is used to refer to this database in all
1470operations described below.
1471
1472Any error detected will cause a return value of @samp{NULL} and an
1473appropriate value will be stored in @code{gdbm_errno}
1474(@pxref{Variables}).
1475@end deftypefn
1476
1477@deftypefn {ndbm} void dbm_close (DBM *@var{dbf})
1478Closes the database. The @var{dbf} argument must be a pointer
1479returned by an earlier call to @code{dbm_open}.
1480@end deftypefn
1481
1482@deftypefn {ndbm} datum dbm_fetch (DBM *@var{dbf}, datum @var{key})
1483Reads a record from the database with the matching key. The @var{key}
1484argument supplies the key that is being looked for.
1485
1486If no matching record is found, the @code{dptr} member of the returned
1487datum is @samp{NULL}. Otherwise, the @code{dptr} member of the
1488returned datum points to the memory managed by the compatibility
1489library. The application should never free it.
1490@end deftypefn
1491
1492@deftypefn {ndbm} int dbm_store (DBM *@var{dbf}, datum @var{key}, @
1493 datum @var{content}, int @var{mode})
1494Writes a key/value pair to the database. The argument @var{dbf} is a
1495pointer to the @code{DBM} structure returned from a call to
1496@code{dbm_open}. The @var{key} and @var{content} provide the values
1497for the record key and content. The @var{mode} argument controls
1498the behavior of @code{dbm_store} in case a matching record already
1499exists in the database. It can have one of the following two values:
1500
1501@table @code
1502@kwindex DBM_REPLACE
1503@item DBM_REPLACE
1504Replace existing record with the new one.
1505
1506@kwindex DBM_INSERT
1507@item DBM_INSERT
1508The existing record is left unchanged, and the function returns
1509@samp{1}.
1510@end table
1511
1512If no matching record exists in the database, new record will be
1513inserted no matter what the value of the @var{mode} is.
1514@end deftypefn
1515
1516@deftypefn {ndbm} int dbm_delete (DBM *@var{dbf}, datum @var{key})
1517Deletes the record with the matching key from the database. If the
1518function succeeds, @samp{0} is returned. Otherwise, if no matching
1519record is found or if an error occurs, @samp{-1} is returned.
1520@end deftypefn
1521
1522@deftypefn {ndbm} datum dbm_firstkey (DBM *@var{dbf})
1523Initializes iteration over the keys from the database and returns
1524the first key. Note, that the word @samp{first} does not imply any
1525specific ordering of the keys.
1526
1527If there are no records in the database, the @code{dptr} member of the
1528returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of
1529the returned datum points to the memory managed by the compatibility
1530library. The application should never free it.
1531@end deftypefn
1532
1533@deftypefn {ndbm} datum dbm_nextkey (DBM *@var{dbf})
1534Continues the iteration started by @code{dbm_firstkey}. Returns the
1535next key in the database. If the iteration covered all keys in the
1536database, the @code{dptr} member of the returned datum is @samp{NULL}.
1537Otherwise, the @code{dptr} member of the returned datum points to the
1538memory managed by the compatibility library. The application should
1539never free it.
1540
1541@cindex sequential access, using @samp{NDBM}
1542@cindex iteration loop, using @samp{NDBM}
1543The usual way of iterating over all the records in the database is:
1544
1545@example
1546for (key = dbm_firstkey (dbf);
1547 key.ptr;
1548 key = dbm_nextkey (dbf))
1549 @{
1550 /* do something with the key */
1551 @}
1552@end example
1553
1554The loop above should not try to delete any records from the database,
1555otherwise the iteration is not guaranteed to cover all the keys.
1556@xref{Sequential}, for a detailed discussion of this.
1557@end deftypefn
1558
1559@deftypefn {ndbm} int dbm_error (DBM *@var{dbf})
1560Returns the error condition of the database: @samp{0} if no errors
1561occurred so far while manipulating the database, and a non-zero value
1562otherwise.
1563@end deftypefn
1564
1565@deftypefn {ndbm} void dbm_clearerr (DBM *@var{dbf})
1566Clears the error condition of the database.
1567@end deftypefn
1568
1569@deftypefn {ndbm} int dbm_dirfno (DBM *@var{dbf})
1570Returns the file descriptor of the @samp{dir} file of the database.
1571It is guaranteed to be different from the descriptor returned by
1572the @code{dbm_pagfno} function (see below).
1573
1574The application can lock this descriptor to serialize accesses to the
1575database.
1576@end deftypefn
1577
1578@deftypefn {ndbm} int dbm_pagfno (DBM *@var{dbf})
1579Returns the file descriptor of the @samp{pag} file of the database.
1580See also @code{dbm_dirfno}.
1581@end deftypefn
1582
1583@deftypefn {ndbm} int dbm_rdonly (DBM *@var{dbf})
1584Returns @samp{1} if the database @var{dbf} is open in a read-only mode
1585and @samp{0} otherwise.
1586@end deftypefn
1587
1588@node dbm
1589@section DBM interface functions.
1590@cindex DBM functions
1591
1592The functions below are provided for compatibility with the old
1593UNIX @samp{DBM} interface. Only one database at a time can be
1594manipulated using them.
1595
1596@deftypefn {dbm} int dbminit (char *@var{file})
1597Opens a database. The @var{file} argument is the full name of the
1598database file to be opened. The function opens two files:
1599@file{@var{file}.pag} and @file{@var{file}.dir}. If any of
1600them does not exist, the function fails. It never attempts to create
1601the files.
1602
1603The database is opened in the read-write mode, if its disk permissions
1604permit.
1605
1606The application must ensure that the functions described below in
1607this section are called only after a successful call to @code{dbminit}.
1608@end deftypefn
1609
1610@deftypefn {dbm} int dbmclose (void)
1611Closes the database opened by an earlier call to @code{dbminit}.
1612@end deftypefn
1613
1614@deftypefn {dbm} datum fetch (datum @var{key})
1615Reads a record from the database with the matching key. The @var{key}
1616argument supplies the key that is being looked for.
1617
1618If no matching record is found, the @code{dptr} member of the returned
1619datum is @samp{NULL}. Otherwise, the @code{dptr} member of the
1620returned datum points to the memory managed by the compatibility
1621library. The application should never free it.
1622@end deftypefn
1623
1624@deftypefn {dbm} int store (datum @var{key}, datum @var{content})
1625Stores the key/value pair in the database. If a record with the
1626matching key already exists, its content will be replaced with the new
1627one.
1628
1629Returns @samp{0} on success and @samp{-1} on error.
1630@end deftypefn
1631
1632@deftypefn {dbm} int delete (datum @var{key})
1633Deletes a record with the matching key.
1634
1635If the function succeeds, @samp{0} is returned. Otherwise, if no
1636matching record is found or if an error occurs, @samp{-1} is
1637returned.
1638@end deftypefn
1639
1640@deftypefn {dbm} datum firstkey (void)
1641Initializes iteration over the keys from the database and returns
1642the first key. Note, that the word @samp{first} does not imply any
1643specific ordering of the keys.
1644
1645If there are no records in the database, the @code{dptr} member of the
1646returned datum is @samp{NULL}. Otherwise, the @code{dptr} member of
1647the returned datum points to the memory managed by the compatibility
1648library. The application should never free it.
1649@end deftypefn
1650
1651@deftypefn {dbm} datum nextkey (datum @var{key})
1652Continues the iteration started by a call to @code{firstkey}. Returns
1653the next key in the database. If the iteration covered all keys in the
1654database, the @code{dptr} member of the returned datum is @samp{NULL}.
1655Otherwise, the @code{dptr} member of the returned datum points to the
1656memory managed by the compatibility library. The application should
1657never free it.
1658@end deftypefn
1659
1660@node gdbmtool
1661@chapter Examine and modify a GDBM database.
1662@prindex gdbmtool
1663
1664The @command{gdbmtool} utility allows you to view and modify an
1665existing @acronym{GDBM} database or to create a new one.
1666
1667@cindex default database, @command{gdbmtool}
1668@flindex junk.gdbm
1669When invoked without arguments, it tries to open a database file called
1670@file{junk.gdbm}, located in the current working directory. You can
1671change this default by supplying the name of the database to use as
1672an argument to the program, e.g.:
1673
1674@example
1675$ gdbmtool file.db
1676@end example
1677
1678@cindex read-only mode, @command{gdbmtool}
1679@cindex @option{-r}, @command{gdbmtool} option
1680@cindex @option{--read-only}, @command{gdbmtool} option
1681The database will be opened in read-write mode, unless the
1682@option{-r} (@option{--read-only}) option is specified, in which case
1683it will be opened only for reading.
1684
1685@cindex creating a database, @command{gdbmtool}
1686@cindex @option{-n}, @command{gdbmtool} option
1687@cindex @option{--newdb}, @command{gdbmtool} option
1688If the database does not exist, @command{gdbmtool} will create it.
1689There is a special option @option{-n} (@option{--newdb}, which
1690instructs the utility to create a new database. If it is used and if
1691the database already exists, it will be deleted, so use it sparingly.
1692
1693@menu
1694* invocation::
1695* shell::
1696@end menu
1697
1698@node invocation
1699@section gdbmtool invocation
1700@cindex command line options, @command{gdbmtool}
1701
1702The following table summarizes all @command{gdbmtool} command line
1703options:
1704
1705@table @option
1706@item -b @var{size}
1707@itemx --block-size=@var{size}
1708Set block size.
1709@item -c @var{size}
1710@itemx --cache-size=@var{size}
1711Set cache size.
1712@item -f @var{file}
1713@item --file @var{file}
1714Read commands from @var{file}, instead of the standard input.
1715@item -h
1716@itemx --help
1717Print a concise help summary.
1718@item -N
1719@itemx --norc
1720Don't read startup files (@pxref{startup files}).
1721@item -n
1722@itemx --newdb
1723Create the database.
1724@item -l
1725@itemx --no-lock
1726Disable file locking.
1727@item -m
1728@itemx --no-mmap
1729Disable mmap.
1730@anchor{-q option}
1731@item -q
1732@itemx --quiet
1733Don't print the usual welcome banner at startup. This is the same as
1734setting the variable @samp{quiet} in the startup file. @xref{quiet}.
1735@item -r
1736@itemx --read-only
1737Open the database in read-only mode.
1738@item -s
1739@itemx --synchronize
1740Synchronize to the disk after each write.
1741@item -V
1742@itemx --version
1743Print program version and licensing information and exit.
1744@item --usage
1745Print a terse invocation syntax summary along with a list of available
1746command line options.
1747@end table
1748
1749@node shell
1750@section gdbmtool interactive mode
1751@cindex interactive mode, @command{gdbmtool}
1752
1753After successful startup, @command{gdbmtool} starts a loop, in which
1754it reads commands from the standard input, executes them and prints
1755the results on the standard output. If the standard input is attached
1756to a console, @command{gdbmtool} runs in interactive mode, which is
1757indicated by its @dfn{prompt}:
1758
1759@example
1760gdbmtool> _
1761@end example
1762
1763The utility finishes when it reads the @samp{quit} command (see below) or
1764detects end-of-file on its standard input, whichever occurs first.
1765
1766A @command{gdbmtool} command consists of a @dfn{command verb},
1767optionally followed by @dfn{arguments}, separated by any
1768amount of white space. A command verb can be entered either in full
1769or in an abbreviated form, as long as that abbreviation does not match
1770any other verb. For example, @samp{co} can be used instead of
1771@samp{count} and @samp{ca} instead of @samp{cache}.
1772
1773Any sequence of non-whitespace characters appearing after the command
1774verb forms an argument. If the argument contains whitespace or
1775unprintable characters it must be enclosed in double quotes. Within
1776double quotes the usual @dfn{escape sequences} are understood, as
1777shown in the table below:
1778
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
1792@end multitable
1793@end float
1794
1795In addition, a backslash immediately followed by the end-of-line
1796character effectively removes that character, allowing to split long
1797arguments over several input lines.
1798
1799Command parameters may be optional or mandatory. If the number of
1800actual arguments is less than the number of mandatory parameters,
1801@command{gdbmtool} will prompt you to supply missing arguments. For
1802example, the @samp{store} command takes two mandatory parameters, so
1803if you invoked it with no arguments, you would be prompted twice to
1804supply the necessary data, as shown in example below:
1805
1806@example
1807gdbmtool> @kbd{store}
1808key? @kbd{three}
1809data? @kbd{3}
1810@end example
1811
1812However, such prompting is possible only in interactive mode. In
1813non-interactive mode (e.g.@: when running a script), all arguments must
1814be supplied with each command, otherwise @command{gdbmtool} will report an
1815error and exit immediately.
1816
1817@menu
1818* variables:: shell variables.
1819* commands:: shell commands.
1820* definitions:: how to define structured data.
1821* startup files::
1822@end menu
1823
1824@node variables
1825@subsection Shell Variables
1826@cindex variables, gdbmtool
1827A number of @command{gdbmtool} parameters is kept in its internal
1828variables.
1829
1830@deftypevr {gdbmtool variable} bool confirm
1831Whether to ask for confirmation before certain destructive operations,
1832such as truncating the existing database.
1833
1834Default is @samp{true}.
1835@end deftypevr
1836
1837@deftypevr {gdbmtool variable} string ps1
1838Primary prompt string. Its value can contain @dfn{conversion
1839specifiers}, consisting of the @samp{%} character followed by another
1840character. These specifiers are expanded in the resulting prompt as
1841follows:
1842
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
1850@item %% @tab %
1851@end multitable
1852
1853The default value is @samp{%p>%_}, i.e. the program name, followed by
1854a ``greater than'' sign, followed by a single space.
1855@end deftypevr
1856
1857@deftypevr {gdbmtool variable} string ps2
1858Secondary prompt. See @samp{ps1} for a description of its value.
1859This prompt is displayed before reading the second and subsequent
1860lines of a multi-line command.
1861
1862The default value is @samp{%_>%_}.
1863@end deftypevr
1864
1865@deftypevr {gdbmtool variable} string delim1
1866A string used to delimit fields of a structured datum on output
1867(@pxref{definitions}).
1868
1869Default is @samp{,} (a comma). This variable cannot be unset.
1870@end deftypevr
1871
1872@deftypevr {gdbmtool variable} string delim2
1873A string used to delimit array items when printing a structured datum
1874(@pxref{definitions}).
1875
1876Default is @samp{,} (a comma). This variable cannot be unset.
1877@end deftypevr
1878
1879@deftypevr {gdbmtool variable} string pager
1880The name and command line of the pager program to pipe output to.
1881This program is used in interactive mode when the estimated number of
1882output lines is greater then the number of lines on your screen.
1883
1884The default value is inherited from the environment variable
1885@env{PAGER}. Unsetting this variable disables paging.
1886@end deftypevr
1887
1888@anchor{quiet}
1889@deftypevr {gdbmtool variable} bool quiet
1890Whether to display a welcome banner at startup. This variable should
1891be set in a startup script file (@pxref{startup files}).
1892@xref{-q option}.
1893@end deftypevr
1894
1895@anchor{open parameters}
1896The following variables control how the database is opened:
1897
1898@deftypevr {gdbmtool variable} numeric blocksize
1899Sets the block size. @xref{Open, block_size}. Unset by default.
1900@end deftypevr
1901
1902@deftypevr {gdbmtool variable} numeric cachesize
1903Sets the cache size. @xref{Options, GDBM_SETCACHESIZE}.
1904By default this variable is not set.
1905@end deftypevr
1906
1907@anchor{openvar}
1908@deftypevr {gdbmtool variable} string open
1909Open mode. The following values are allowed:
1910
1911@table @asis
1912@item newdb
1913Truncate the database if it exists or create a new one. Open it in
1914read-write mode.
1915
1916Technically, this sets the @samp{GDBM_NEWDB} flag in call to @samp{gdbm_open}.
1917@xref{Open, GDBM_NEWDB}.
1918@item wrcreat
1919@itemx rw
1920Open the database in read-write mode. Create it if it does not
1921exist. This is the default.
1922
1923Technically speaking, it sets the @samp{GDBM_WRCREAT} flag in call to
1924@code{gdbm_open}. @xref{Open, GDBM_WRCREAT}.
1925@item reader
1926@itemx readonly
1927Open the database in read-only mode. Signal an error if it does not
1928exist.
1929
1930This sets the @samp{GDBM_READER} flag (@pxref{Open, GDBM_READER}).
1931@end table
1932
1933Attempting to set any other value or to unset this variable produces
1934an error.
1935@end deftypevr
1936
1937@anchor{filemode}
1938@deftypevr {gdbmtool variable} number filemode
1939File mode (in octal) for creating new database files and database
1940dumps.
1941@end deftypevr
1942
1943@deftypevr {gdbmtool variable} bool lock
1944Lock the database. This is the default.
1945
1946Setting this variable to false or unsetting it results in passing
1947@samp{GDBM_NOLOCK} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOLOCK}).
1948@end deftypevr
1949
1950@deftypevr {gdbmtool variable} bool mmap
1951Use memory mapping. This is the default.
1952
1953Setting this variable to false or unsetting it results in passing
1954@samp{GDBM_NOMMAP} flag to @code{gdbm_open} (@pxref{Open, GDBM_NOMMAP}).
1955@end deftypevr
1956
1957@deftypevr {gdbmtool variable} bool sync
1958Flush all database writes on disk immediately. Default is false.
1959@xref{Open, GDBM_SYNC}.
1960@end deftypevr
1961
1962The following commands are used to list or modify the variables:
1963
1964@deffn {command verb} set [@var{assignments}]
1965When used without arguments, lists all variables and their values.
1966Unset variables are shown after a comment sign (@samp{#}). For string
1967and numeric variables, values are shown after an equals sign. For
1968boolean variables, only the variable name is displayed if the variable
1969is @samp{true}. If it is @samp{false}, its name is prefixed with
1970@samp{no}.
1971
1972For example:
1973
1974@example
1975@group
1976ps1="%p>%_"
1977ps2="%_>%_"
1978delim1=","
1979delim2=","
1980confirm
1981# cachesize is unset
1982# blocksize is unset
1983open="wrcreat"
1984lock
1985mmap
1986nosync
1987pager="less"
1988# quiet is unset
1989@end group
1990@end example
1991
1992If used with arguments, the @code{set} command alters the specified
1993variables. In this case, arguments are variable assignments in the
1994form @samp{@var{name}=@var{value}}. For boolean variables, the
1995@var{value} is interpreted as follows: if it is numeric, @samp{0}
1996stands for @samp{false}, any non-zero value stands for @samp{true}.
1997Otherwise, 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
2000supplied 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
2002command sets the @samp{delim2} variable to @samp{;} and the
2003@samp{confirm} variable to @samp{false}:
2004
2005@example
2006set delim2=";" noconfirm
2007@end example
2008@end deffn
2009
2010@deffn {command verb} unset @var{variables}
2011Unsets the listed variables. The effect of unsetting depends on the
2012variable. Unless explicitly described in the discussion of the
2013variables above, unsetting a boolean variable is equivalent to setting it to
2014@samp{false}. Unsetting a string variable is equivalent to assigning it
2015an empty string.
2016@end deffn
2017
2018@node commands
2019@subsection Gdbmtool Commands
2020
2021@deffn {command verb} avail
2022Print the @dfn{avail list}.
2023@end deffn
2024
2025@deffn {command verb} bucket @var{num}
2026Print the bucket number @var{num} and set it as the current one.
2027@end deffn
2028
2029@deffn {command verb} cache
2030Print the bucket cache.
2031@end deffn
2032
2033@deffn {command verb} close
2034Close the currently open database.
2035@end deffn
2036
2037@deffn {command verb} count
2038Print the number of entries in the database.
2039@end deffn
2040
2041@deffn {command verb} current
2042Print the current bucket.
2043@end deffn
2044
2045@deffn {command verb} delete @var{key}
2046Delete record with the given @var{key}
2047@end deffn
2048
2049@deffn {command verb} dir
2050Print hash directory.
2051@end deffn
2052
2053@anchor{gdbmtool export}
2054@deffn {command verb} export @var{file-name} [truncate] [binary|ascii]
2055Export the database to the flat file @var{file-name}. @xref{Flat files},
2056for a description of the flat file format and its purposes. This
2057command will not overwrite an existing file, unless the
2058@samp{truncate} parameter is also given. Another optional argument
2059determines the type of the dump (@pxref{Flat files}). By default, ASCII
2060dump is created.
2061
2062The global variable @code{filemode} specifies the permissions to use
2063for the created output file.
2064
2065See also @ref{gdbmexport}.
2066@end deffn
2067
2068@deffn {command verb} fetch @var{key}
2069Fetch and display the record with the given @var{key}.
2070@end deffn
2071
2072@deffn {command verb} first
2073Fetch and display the first record in the database. Subsequent
2074records can be fetched using the @code{next} command (see below).
2075@xref{Sequential}, for more information on sequential access.
2076@end deffn
2077
2078@deffn {command verb} hash @var{key}
2079Compute and display the hash value for the given @var{key}.
2080@end deffn
2081
2082@deffn {command verb} header
2083Print file header.
2084@end deffn
2085
2086@deffn {command verb} help
2087@deffnx {command verb} ?
2088Print a concise command summary, showing each command verb
2089with its parameters and a short description of what it does. Optional
2090arguments are enclosed in square brackets.
2091@end deffn
2092
2093@anchor{gdbmtool import}
2094@deffn {command verb} import @var{file-name} [replace] [nometa]
2095Import data from a flat dump file @var{file-name}
2096(@pxref{Flat files}). If the word @samp{replace} is given
2097as an argument, any records with the same keys as the already
2098existing ones will replace them. The word @samp{nometa} turns off
2099restoring meta-information from the dump file.
2100@end deffn
2101
2102@deffn {command verb} list
2103List the contents of the database.
2104@end deffn
2105
2106@deffn {command verb} next [@var{key}]
2107Sequential access: fetch and display the next record. If the @var{key} is
2108given, the record following the one with this key will be fetched.
2109
2110See also @code{first}, above.
2111
2112@xref{Sequential}, for more information on sequential access.
2113@end deffn
2114
2115@deffn {command verb} open @var{filename}
2116Open the database file @var{filename}. If successful, any previously
2117open database is closed. Otherwise, if the operation fails, the
2118currently opened database remains unchanged.
2119
2120This command takes additional information from the following
2121variables:
2122
2123@table @samp
2124@item open
2125The database access mode. @xref{openvar,, The @var{open} variable},
2126for a list of its values.
2127@item lock
2128Whether or not to lock the database. Default is @samp{on}.
2129@item mmap
2130Use the memory mapping. Default is @samp{on}.
2131@item sync
2132Synchronize after each write. Default is @samp{off}.
2133@item filemode
2134Specifies the permissions to use in case a new file is created.
2135@end table
2136
2137@xref{open parameters}, for a detailed description of these variables.
2138@end deffn
2139
2140@deffn {command verb} quit
2141Close the database and quit the utility.
2142@end deffn
2143
2144@deffn {command verb} reorganize
2145Reorganize the database (@pxref{Reorganization}).
2146@end deffn
2147
2148@deffn {command verb} source @var{filename}
2149Read @command{gdbmtool} commands from the file @var{filename}.
2150@end deffn
2151
2152@deffn {command verb} status
2153Print current program status. The following example shows the
2154information displayed:
2155
2156@example
2157Database file: junk.gdbm
2158Database is open
2159define key string
2160define content string
2161@end example
2162
2163The two @samp{define} strings show the defined formats for key and
2164content data. @xref{definitions}, for a detailed discussion of their
2165meaning.
2166@end deffn
2167
2168@deffn {command verb} store @var{key} @var{data}
2169Store the @var{data} with @var{key} in the database. If @var{key}
2170already exists, its data will be replaced.
2171@end deffn
2172
2173@deffn {command verb} version
2174Print the version of @command{gdbm}.
2175@end deffn
2176
2177@node definitions
2178@subsection Data Definitions
2179GDBM databases are able to keep data of any type, both in the key and
2180in the content part of a record. Quite often these data are
2181structured, i.e. they consist of several fields of various types.
2182@command{Gdbmtool} provides a mechanism for handling such kind of
2183records.
2184
2185The @code{define} command defines a record structure. The general
2186syntax is:
2187
2188@example
2189define @var{what} @var{definition}
2190@end example
2191
2192@noindent
2193where @var{what} is @samp{key} to defining the structure of key data and
2194@samp{content} to define the structure of the content records.
2195
2196The @var{definition} can be of two distinct formats. In the simplest
2197case it is a single data type. For example,
2198
2199@example
2200define content int
2201@end example
2202
2203@noindent
2204defines content records consisting of a single integer field.
2205Supported data types are:
2206
2207@table @asis
2208@item char
2209Single byte (signed).
2210@item short
2211Signed short integer.
2212@item ushort
2213Unsigned short integer.
2214@item int
2215Signed integer.
2216@item unsigned
2217@itemx uint
2218Unsigned integer.
2219@item long
2220Signed long integer.
2221@item ulong
2222Unsigned long integer.
2223@item llong
2224Signed long long integer.
2225@item ullong
2226Unsigned long long integer.
2227@item float
2228A floating point number.
2229@item double
2230Double-precision floating point number.
2231@item string
2232Array of bytes.
2233@item stringz
2234Null-terminated string, trailing null being part of the string.
2235@end table
2236
2237All numeric data types (integer as well as floating point) have the
2238same respective widths as in C language on the host where the database
2239file resides.
2240
2241The @samp{string} and @samp{stringz} are special. Both define a
2242string of bytes, similar to @samp{char x[]} in C. The former
2243defines an array of bytes, the latter - a null-terminated string.
2244This makes a difference, in particular, when the string is the only
2245part of datum. Consider the following two definitions:
2246
2247@enumerate 1
2248@item @code{define key string}
2249@item @code{define key stringz}
2250@end enumerate
2251
2252@noindent
2253Now, suppose we want to store the string "ab" in the key. Using the
2254definition (1), the @code{dptr} member of GDBM @code{datum} will
2255contain two bytes: @samp{a}, and @samp{b}. Consequently, the
2256@code{dsize} member will have the value 2. Using the definition (2),
2257the @code{dptr} member will contain three bytes: @samp{a}, @samp{b},
2258and ASCII 0. The @code{dsize} member will have the value 3.
2259
2260The definition (1) is the default for both key and content.
2261
2262The second form of the @code{define} statement is similar to the C
2263@code{struct} statement and allows for defining structural data. In
2264this form, the @var{definition} part is a comma-separated list of data
2265types and variables enclosed in curly braces. In contrast to the
2266rest of @command{gdbm} commands, this command is inherently
2267multiline and is terminated with the closing curly brace. For
2268example:
2269
2270@example
2271define content @{
2272 int status,
2273 pad 8,
2274 char id[3],
2275 string name
2276@}
2277@end example
2278
2279@noindent
2280This defines a structure consisting of three members: an integer
2281@code{status}, an array of 8 bytes @code{id}, and a null-terminated
2282string @code{name}. Notice the @code{pad} statement: it allows to
2283introduce padding between structure members. Another useful statement
2284is @code{offset}: it specifies that the member following it begins at
2285the given offset in the structure. Assuming the size of @code{int} is
22868 bytes, the above definition can also be written as
2287
2288@example
2289define content @{
2290 int status,
2291 offset 16,
2292 char id[3],
2293 string name
2294@}
2295@end example
2296
2297@emph{NOTE}: The @samp{string} type can reasonably be used only if it
2298is the last or the only member of the data structure. That's because it
2299provides no information about the number of elements in the array, so
2300it is interpreted to contain all bytes up to the end of the datum.
2301
2302When displaying the structured data, @command{gdbmtool} precedes each
2303value with the corresponding field name and delimits parts of the
2304structure 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:
2307
2308@example
2309gdbmtool> fetch foo
2310status=2,id=@{ a, u, x @},name="quux"
2311@end example
2312
2313To supply a structured datum as an argument to a @command{gdbmtool}
2314command, use the same notation, but without field names, e.g.:
2315
2316@example
2317gdbmtool> hash @{ 2, @{a,u,x@}, "quux" @}
2318hash value = 13089969.
2319@end example
2320
2321@node startup files
2322@subsection Startup Files
2323@cindex startup file, gdbmtool
2324@cindex init file, gdbmtool
2325@flindex .gdbmtoolrc
2326Upon startup @command{gdbmtool} looks for a file named
2327@samp{.gdbmtoolrc} first in the current working directory and, if not
2328found, in the home directory of the user who started the command.
2329
2330If found, this file is read and interpreted as a list of
2331@command{gdbmtool} commands. This allows you to customize the
2332program behavior.
2333
2334Following is an example startup file which disables the welcome
2335banner, sets command line prompt to contain the name of the database
2336file in parentheses and defines the structure of the database content
2337records:
2338
2339@example
2340@group
2341set quiet
2342set ps1="(%f) "
2343define key stringz
2344define content @{
2345 int time,
2346 pad 4,
2347 int status
2348@}
2349@end group
2350@end example
2351
2352@node gdbm_dump
2353@chapter The @command{gdbm_dump} utility
2354@prindex gdbm_dump
2355
2356The @command{gdbm_dump} utility creates a flat file dump of a GDBM
2357database (@pxref{Flat files}). It takes one mandatory argument: the
2358name of the source database file. The second argument, if given,
2359specifies the name of the output file. If not given,
2360@command{gdbm_dump} will produce the dump on the standard output.
2361
2362For example, the following invocation creates a dump of the database
2363@file{file.db} in the file @file{file.dump}:
2364
2365@example
2366$ gdbm_dump file.db file.dump
2367@end example
2368
2369By default the utility creates dumps in ASCII format (@pxref{Flat
2370files,ASCII}). Another format can be requested using the
2371@option{--format} (@option{-H}) option.
2372
2373The @command{gdbm_dump} utility understands the following command line
2374options:
2375
2376@table @option
2377@item -H @var{fmt}
2378@itemx --format=@var{fmt}
2379Select output format. Valid values for @var{fmt} are: @samp{binary}
2380or @samp{0} to select binary dump format, and @samp{ascii} or @samp{1}
2381to select ASCII format.
2382
2383@item -h
2384@itemx --help
2385Print a concise help summary.
2386
2387@item -V
2388@itemx --version
2389Print program version and licensing information and exit.
2390
2391@item --usage
2392Print a terse invocation syntax summary along with a list of available
2393command line options.
2394@end table
2395
2396@node gdbm_load
2397@chapter The @command{gdbm_load} utility
2398@prindex gdbm_load
2399
2400The @command{gdbm_load} utility restores a GDBM database from a flat
2401file. The utility requires at least one argument: the name of the
2402input flat file. If it is @samp{-}, the standard input will be read.
2403The format of the input file is detected automatically.
2404
2405By default the utility attempts to restore the database under its
2406original name, as stored in the input file. It will fail to do so if
2407the input is in binary format. In that case, the name of the database
2408must be given as the second argument.
2409
2410In general, if two arguments are given the second one is treated as
2411the name of the database to create, overriding the file name specified
2412in the flat file.
2413
2414The utility understands the following command line arguments:
2415
2416@table @option
2417
2418@item -b @var{num}
2419@itemx --block-size=@var{num}
2420Sets block size. @xref{Open, block_size}.
2421
2422@item -c @var{num}
2423@itemx --cache-size=@var{num}
2424Sets cache size. @xref{Options, GDBM_SETCACHESIZE}.
2425
2426@item -M
2427@itemx --mmap
2428Use memory mapping.
2429
2430@item -m @var{mode}
2431@item --mode=@var{mode}
2432Sets the file mode. The argument is the desired file mode in octal.
2433
2434@item -n
2435@itemx --no-meta
2436Do not restore file meta-data (ownership and mode) from the flat file.
2437
2438@item -r
2439@itemx --replace
2440Replace existing keys.
2441
2442@item -u @var{user}[:@var{group}]
2443@itemx --user=@var{user}[:@var{group}]
2444Set file owner. The @var{user} can be either a valid user name or
2445UID. Similarly, the @var{group} is either a valid group name or GID.
2446If @var{group} is not given, the main group of @var{user} is used.
2447
2448User and group parts can be separated by a dot, instead of the colon.
2449
2450@item -h
2451@itemx --help
2452Print a concise help summary.
2453
2454@item -V
2455@itemx --version
2456Print program version and licensing information and exit.
2457
2458@item --usage
2459Print a terse invocation syntax summary along with a list of available
2460command line options.
2461@end table
2462
2463@node gdbmexport
2464@chapter Export a database into a portable format.
2465@prindex gdbmexport
2466
2467The @command{gdbmexport} utility converts the database of an older
2468GDBM version into a binary flat format.
2469
2470The utility takes two mandatory arguments: the name of the database
2471file to convert and the output file name, e.g.:
2472
2473@example
2474$ gdbmexport junk.gdbm junk.flat
2475@end example
2476
2477In addition the following two options are understood:
2478
2479@table @option
2480@item -h
2481Display short usage summary and exit.
2482
2483@item -v
2484Display program version and licensing information, and exit.
2485@end table
2486
2487@node Exit codes
2488@chapter Exit codes
2489@cindex exit code
2490
2491All GDBM utilities return uniform exit codes. These are summarized in
2492the table below:
2493
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.
2500@end multitable
2501
2502@node Bugs
2503@chapter Problems and bugs.
2504
2505If you have problems with GNU @code{dbm} or think you've found a bug,
2506please report it. Before reporting a bug, make sure you've actually
2507found a real bug. Carefully reread the documentation and see if it
2508really says you can do what you're trying to do. If it's not clear
2509whether you should be able to do something or not, report that too; it's
2510a bug in the documentation!
2511
2512Before reporting a bug or trying to fix it yourself, try to isolate it
2513to the smallest possible input file that reproduces the problem. Then
2514send us the input file and the exact results @code{gdbm} gave you. Also
2515say what you expected to occur; this will help us decide whether the
2516problem was really in the documentation.
2517
2518Once you've got a precise problem, send e-mail to
2519@email{bug-gdbm@@gnu.org}.
2520
2521Please include the version number of GNU @code{dbm} you are using. You can get
2522this information by printing the variable @code{gdbm_version}
2523(@pxref{Variables}).
2524
2525Non-bug suggestions are always welcome as well. If you have questions
2526about things that are unclear in the documentation or are just obscure
2527features, please report them too.
2528
2529You may contact the authors and maintainers by e-mail:
2530@example
2531@email{phil@@cs.wwu.edu}, @email{downsj@@downsj.com}, @email{gray@@gnu.org.ua}
2532@end example
2533
2534@node Resources
2535@chapter Additional resources
2536
2537For the latest updates and pointers to additional resources, visit
2538@uref{http://www.gnu.org/@/software/@/gdbm}.
2539
2540In particular, a copy of @code{gdbm} documentation in various formats
2541is available online at @uref{http://www.gnu.org/@/software/@/gdbm/@/manual.html}.
2542
2543Latest 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
2546@ifhtml
2547@uref{http://www.gnu.org/order/ftp.html,,GNU mirror} worldwide.
2548@end ifhtml
2549@ifnothtml
2550GNU mirror worldwide. See @uref{http://www.gnu.org/@/order/@/ftp.html},
2551for a list of mirrors.
2552@end ifnothtml
2553
2554To track @code{gdbm} development, visit
2555@uref{http://puszcza.gnu.org.ua/@/projects/@/gdbm}.
2556
2557@node GNU Free Documentation License
2558@appendix GNU Free Documentation License
2559
2560@include fdl.texi
2561
2562@node Index
2563@unnumbered Index
2564
2565@printindex cp
2566
2567@bye

Return to:

Send suggestions and report system problems to the System administrator.