diff options
author | Jason Downs <downsj@downsj.com> | 2008-11-21 21:33:39 +0000 |
---|---|---|
committer | Jason Downs <downsj@downsj.com> | 2008-11-21 21:33:39 +0000 |
commit | 10fe387708ddfba6449b9abd74cfbdf67d495465 (patch) | |
tree | 50115c0708c762940f580d081c73495bf148101a /doc/gdbm.texinfo | |
download | gdbm-10fe387708ddfba6449b9abd74cfbdf67d495465.tar.gz gdbm-10fe387708ddfba6449b9abd74cfbdf67d495465.tar.bz2 |
Initial revision
Diffstat (limited to 'doc/gdbm.texinfo')
-rw-r--r-- | doc/gdbm.texinfo | 1035 |
1 files changed, 1035 insertions, 0 deletions
diff --git a/doc/gdbm.texinfo b/doc/gdbm.texinfo new file mode 100644 index 0000000..3b3353e --- /dev/null +++ b/doc/gdbm.texinfo @@ -0,0 +1,1035 @@ +\input texinfo @c -*- Texinfo -*- +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename gdbm.info +@include version.texi +@settitle gdbm +@dircategory Programming & development tools +@direntry +* GDBM: (gdbm). The GNU database manager. +@end direntry +@c @setchapternewpage odd +@comment %**end of header (This is for running Texinfo on a region.) + +@iftex +@finalout +@end iftex + +@ifinfo +This file documents the GNU dbm utility. + +Copyright (C) 1989-1999, 2007 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@titlepage +@null +@sp 6 +@center @titlefont{GNU dbm} +@sp 2 +@center A Database Manager +@sp 2 +@center by Philip A. Nelson and Jason Downs +@sp 4 +@center Manual by Pierre Gaumond, Philip A. Nelson and Jason Downs +@sp 1 +@center Edition @value{EDITION} +@sp 1 +@center for GNU @code{dbm}, Version @value{VERSION} +@page +@null +@vskip 0pt plus 1filll +Copyright @copyright{} 1993-99 Free Software Foundation, Inc. +@sp 2 + +This is Edition 1.5 of the @cite{GNU @code{dbm} Manual}, for @code{gdbm} +Version @value{VERSION}. @* +Last updated @value{UPDATED} + +Published by the Free Software Foundation @* +675 Massachusetts Avenue, @* +Cambridge, MA 02139 USA @* + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end titlepage +@page + +@node Top, Copying, (dir), (dir) +@ifinfo +GNU @code{dbm} is a library of functions implementing a hashed database +on a disk file. This manual documents GNU @code{dbm} Version @value{VERSION} +(@code{gdbm}). The software was written by Philip A. Nelson. This +document was originally written by Pierre Gaumond from texts written by +Phil. +@end ifinfo + + +@menu +Introduction: + +* Copying:: Your rights. +* Intro:: Introduction to GNU dbm. +* List:: List of functions. + +Functions: + +* Open:: Opening the database. +* Close:: Closing the database. +* Store:: Inserting and replacing records in the database. +* Fetch:: Searching records in the database. +* Delete:: Removing records from the database. +* Sequential:: Sequential access to records. +* Reorganization:: Database reorganization. +* Sync:: Insure all writes to disk have competed. +* Errors:: Convert internal error codes into English. +* Options:: Setting internal options. +* Locking:: File locking. + +Programs + +* testgdbm:: Test and modify a GDBM database. +* gdbmexport:: Export a database into a portable format. + +Other topics: + +* Variables:: Two useful variables. +* Compatibility:: Compatibility with UNIX dbm and ndbm. +* Bugs:: Problems and bugs. +@end menu + +@node Copying, Intro, Top, Top +@chapter Copying Conditions. +This library is @dfn{free}; this means that everyone is free to use +it and free to redistribute it on a free basis. GNU @code{dbm} (@code{gdbm}) +is not in the public domain; it is copyrighted and there +are restrictions on its distribution, but these restrictions are +designed to permit everything that a good cooperating citizen would want +to do. What is not allowed is to try to prevent others from further +sharing any version of @code{gdbm} that they might get from +you.@refill + + Specifically, we want to make sure that you have the right to give +away copies @code{gdbm}, that you receive +source code or else can get it if you want it, that you can change these +functions or use pieces of them in new free programs, and that you know +you can do these things.@refill + + To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies @code{gdbm}, you must give the recipients all +the rights that you have. You must make sure that they, too, receive or +can get the source code. And you must tell them their rights.@refill + + Also, for our own protection, we must make certain that everyone finds +out that there is no warranty for anything in the @code{gdbm} distribution. +If these functions are modified by someone else and passed on, we want +their recipients to know that what they have is not what we distributed, +so that any problems introduced by others will not reflect on our +reputation.@refill + +@code{gdbm} is currently distributed under the terms of the GNU General +Public License, Version 2. (@emph{NOT} under the GNU General Library +Public License.) A copy the GNU General Public License is included with +the distribution of @code{gdbm}. + +@node Intro, List, Copying, Top +@chapter Introduction to GNU @code{dbm}. + +GNU @code{dbm} (@code{gdbm})is a library of database functions that use +extendible hashing and works similar to the standard UNIX @code{dbm} +functions. These routines are provided to a programmer needing to +create and manipulate a hashed database. (@code{gdbm} is @emph{NOT} a +complete database package for an end user.) + +The basic use of @code{gdbm} is to store key/data pairs in a data file. +Each key must be unique and each key is paired with only one data item. +The keys can not be directly accessed in sorted order. The basic unit +of data in @code{gdbm} is the structure: + +@example + typedef struct @{ + char *dptr; + int dsize; + @} datum; +@end example + +This structure allows for arbitrary sized keys and data items. + +The key/data pairs are stored in a @code{gdbm} disk file, called a +@code{gdbm} database. An application must open a @code{gdbm} database +to be able manipulate the keys and data contained in the database. +@code{gdbm} allows an application to have multiple databases open at the +same time. When an application opens a @code{gdbm} database, it is +designated as a @code{reader} or a @code{writer}. A @code{gdbm} +database opened by at most one writer at a time. However, many readers +may open the database open simultaneously. Readers and writers can not +open the @code{gdbm} database at the same time. + +@node List, Open, Intro, Top +@chapter List of functions. + +The following is a quick list of the functions contained in the @code{gdbm} +library. The include file @code{gdbm.h}, that can be included by the user, +contains a definition of these functions. + +@example +#include <gdbm.h> + +GDBM_FILE gdbm_open(name, block_size, flags, mode, fatal_func); +void gdbm_close(dbf); +int gdbm_store(dbf, key, content, flag); +datum gdbm_fetch(dbf, key); +int gdbm_delete(dbf, key); +datum gdbm_firstkey(dbf); +datum gdbm_nextkey(dbf, key); +int gdbm_reorganize(dbf); +void gdbm_sync(dbf); +int gdbm_exists(dbf, key); +char *gdbm_strerror(errno); +int gdbm_setopt(dbf, option, value, size); +int gdbm_fdesc(dbf); +@end example + +The @code{gdbm.h} include file is often in the @file{/usr/local/include} +directory. (The actual location of @code{gdbm.h} depends on your local +installation of @code{gdbm}.) + +@node Open, Close, List, Top +@chapter Opening the database. + +Initialize @code{gdbm} system. If the file has a size of zero bytes, a file +initialization procedure is performed, setting up the initial structure in the +file. + +The procedure for opening a @code{gdbm} file is: + +@example +GDBM_FILE dbf; + +dbf = gdbm_open(name, block_size, flags, mode, fatal_func); +@end example + +The parameters are: + +@table @asis +@item char *name +The name of the file (the complete name, @code{gdbm} does not append any +characters to this name). +@item int block_size +It is used during initialization to determine the size of various constructs. It +is the size of a single transfer from disk to memory. This parameter is ignored +if the file has been previously initialized. The minimum size is 512. +If the value is less than 512, the file system blocksize is used, otherwise the +value of @code{block_size} is used. +@item int flags +If @code{flags} is set to GDBM_READER, the user wants to just read the +database and any call to @code{gdbm_store} or @code{gdbm_delete} will fail. +Many readers can access the database at the same time. If @code{flags} is +set to GDBM_WRITER, the user wants both read and write access to the database +and requires exclusive access. If @code{flags} is set to GDBM_WRCREAT, the +user wants both read and write access to the database and if the database does +not exist, create a new one. If @code{flags} is set to GDBM_NEWDB, the +user want a new database created, regardless of whether one existed, and wants +read and write access to the new database. The following may also be logically +or'd into the database flags: GDBM_SYNC, which causes all database operations +to be synchronized to the disk, and GDBM_NOLOCK, which prevents the library +from performing any locking on the database file. The option GDBM_FAST is +now obsolete, since @code{gdbm} defaults to no-sync mode. Any error detected +will cause a return value of NULL and an appropriate value will be in +@code{gdbm_errno} (see Variables). If no errors occur, a pointer to the +@code{gdbm} file descriptor will be returned. +@item int mode +File mode (see chmod(2) and open(2) if the file is created). +@item void (*fatal_func) () +A function for @code{gdbm} to call if it detects a fatal error. The only +parameter of this function is a string. If the value of NULL is provided, +@code{gdbm} will use a default function. +@end table + +The return value, @code{dbf}, is the pointer needed by all other functions to +access that @code{gdbm} file. If the return is the NULL pointer, +@code{gdbm_open} was not successful. The errors can be found in +@code{gdbm_errno} for @code{gdbm} errors and in @code{errno} for file system +errors (for error codes, see @code{gdbm.h}). + +In all of the following calls, the parameter @code{dbf} refers to the pointer +returned from @code{gdbm_open}. + +@node Close, Store, Open, Top +@chapter Closing the database. + +It is important that every file opened is also closed. This is needed to +update the reader/writer count on the file. This is done by: + +@example +gdbm_close(dbf); +@end example + +The parameter is: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@end table + +Closes the @code{gdbm} file and frees all memory associated with the file +@code{dbf}. + +@node Store, Fetch, Close, Top +@chapter Inserting and replacing records in the database. + +The function @code{gdbm_store} inserts or replaces records in the database. + +@example +ret = gdbm_store(dbf, key, content, flag); +@end example + +The parameters are: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@item datum key +The @code{key} data. +@item datum content +The data to be associated with the key. +@item int flag +Defines the action to take when the key is already in the database. The value +GDBM_REPLACE (defined in @code{gdbm.h}) asks that the old data be replaced by +the new @code{content}. The value GDBM_INSERT asks that an error be returned +and no action taken if the @code{key} already exists. +@end table + +The values returned in @code{ret} are: + +@table @asis +@item -1 +The item was not stored in the database because the caller was not an +official writer or either @code{key} or @code{content} have a NULL dptr field. +Both @code{key} and @code{content} must have the dptr field be a non-NULL value. +Since a NULL dptr field is used by other functions to indicate an error, a NULL +field cannot be valid data. +@item +1 +The item was not stored because the argument @code{flag} was GDBM_INSERT and +the @code{key} was already in the database. +@item 0 +No error. @code{content} is keyed by @code{key}. The file on disk is updated +to reflect the structure of the new database before returning from this +function. +@end table + +If you store data for a @code{key} that is already in the data base, +@code{gdbm} replaces the old data with the new data if called with +GDBM_REPLACE. You do not get two data items for the same @code{key} and you do +not get an error from @code{gdbm_store}. + +The size in @code{gdbm} is not restricted like @code{dbm} or @code{ndbm}. Your +data can be as large as you want. + +@node Fetch, Delete, Store,Top +@chapter Searching for records in the database. + +Looks up a given @code{key} and returns the information associated with that +key. The pointer in the structure that is returned is a pointer to dynamically +allocated memory block. To search for some data: + +@example +content = gdbm_fetch(dbf, key); +@end example + +The parameters are: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@item datum key +The @code{key} data. +@end table + +The datum returned in @code{content} is a pointer to the data found. If the +dptr is NULL, no data was found. If dptr is not NULL, then it points +to data allocated by malloc. @code{gdbm} does not automatically free this data. +The user must free this storage when done using it. This eliminates the +need to copy the result to save it for later use (you just save the pointer). + +You may also search for a particular key without retrieving it, using: + +@example +ret = gdbm_exists(dbf, key); +@end example + +The parameters are: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@item datum key +The @code{key} data. +@end table + +Unlike @code{gdbm_fetch}, this routine does not allocate any memory, and +simply returns true or false, depending on whether the @code{key} exists, +or not. + +@node Delete, Sequential, Fetch, Top +@chapter Removing records from the database. + +To remove some data from the database: + +@example +ret = gdbm_delete(dbf, key); +@end example + +The parameters are: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@item datum key +The @code{key} data. +@end table + +The ret value is -1 if the item is not present or the requester is a reader. +The ret value is 0 if there was a successful delete. + +@code{gdbm_delete} removes the keyed item and the @code{key} from the database +@code{dbf}. The file on disk is updated to reflect the structure of the new +database before returning from this function. + +@node Sequential, Reorganization, Delete, Top +@chapter Sequential access to records. + +The next two functions allow for accessing all items in the database. This +access is not @code{key} sequential, but it is guaranteed to visit every +@code{key} in the database once. The order has to do with the hash values. +@code{gdbm_firstkey} starts the visit of all keys in the database. +@code{gdbm_nextkey} finds and reads the next entry in the hash structure for +@code{dbf}. + +@example +key = gdbm_firstkey(dbf); + +nextkey = gdbm_nextkey(dbf, key); +@end example + +The parameters are: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@item datum @code{key} +@item datum nextkey +The @code{key} data. +@end table + +The return values are both datum. If @code{key}.dptr or nextkey.dptr is NULL, +there is no first @code{key} or next @code{key}. Again notice that dptr points to +data allocated by malloc and @code{gdbm} will not free it for you. + +These functions were intended to visit the database in read-only algorithms, +for instance, to validate the database or similar operations. + +File @code{visiting} is based on a @code{hash table}. @code{gdbm_delete} +re-arranges the hash table to make sure that any collisions in the table do not +leave some item @code{un-findable}. The original key order is NOT guaranteed to +remain unchanged in ALL instances. It is possible that some key will not be +visited if a loop like the following is executed: + +@example +@group + key = gdbm_firstkey ( dbf ); + while ( key.dptr ) @{ + nextkey = gdbm_nextkey ( dbf, key ); + if ( some condition ) @{ + gdbm_delete ( dbf, key ); + free ( key.dptr ); + @} + key = nextkey; + @} +@end group +@end example + +@node Reorganization, Sync, Sequential, Top +@chapter Database reorganization. + +The following function should be used very seldom. + +@example +ret = gdbm_reorganize(dbf); +@end example + +The parameter is: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@end table + +If you have had a lot of deletions and would like to shrink the space +used by the @code{gdbm} file, this function will reorganize the database. +@code{gdbm} will not shorten the length of a @code{gdbm} file (deleted file space will be +reused) except by using this reorganization. + +This reorganization requires creating a new file and inserting all the elements +in the old file @code{dbf} into the new file. The new file is then renamed to +the same name as the old file and @code{dbf} is updated to contain all the +correct information about the new file. If an error is detected, the return +value is negative. The value zero is returned after a successful +reorganization. + +@node Sync, Errors, Reorganization, Top +@chapter Database Synchronization + +Unless your database was opened with the GDBM_SYNC flag, @code{gdbm} does not +wait for writes to be flushed to the disk before continuing. This allows +faster writing of databases at the risk of having a corrupted database if +the application terminates in an abnormal fashion. The following function +allows the programmer to make sure the disk version of the +database has been completely updated with all changes to the current time. + +@example +gdbm_sync(dbf); +@end example + +The parameter is: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@end table + +This would usually be called after a complete set of changes have been +made to the database and before some long waiting time. +@code{gdbm_close} automatically calls the equivalent of @code{gdbm_sync} +so no call is needed if the database is to be closed immediately after +the set of changes have been made. + +@node Errors, Options, Sync, Top +@chapter Error strings. + +To convert a @code{gdbm} error code into English text, use this routine: + +@example +ret = gdbm_strerror(errno) +@end example + +The parameter is: + +@table @asis +@item gdbm_error errno +The @code{gdbm} error code, usually @code{gdbm_errno}. +@end table + +The appropiate phrase for reading by humans is returned. + +@node Options, Locking, Errors, top +@chapter Seting options. + +@code{Gdbm} supports the ability to set certain options on an already +open database. + +@example +ret = gdbm_setopt(dbf, option, value, size); +@end example + +The parameters are: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@item int option +The option to be set. +@item int *value +A pointer to the value to which @code{option} will be set. +@item int size +The length of the data pointed to by @code{value}. +@end table + +The valid options are: + + GDBM_CACHESIZE - Set the size of the internal bucket cache. This + option may only be set once on each GDBM_FILE descriptor, and + is set automatically to 100 upon the first access to the database. + + GDBM_FASTMODE - Set fast mode to either on or off. This allows + fast mode to be toggled on an already open and active database. + value (see below) should be set to either TRUE or FALSE. + @emph{This option is now obsolete.} + + GDBM_SYNCMODE - Turn on or off file system synchronization operations. This + setting defaults to off; value (see below) should be set to either TRUE or + FALSE. + + GDBM_CENTFREE - Set central free block pool to either on or off. + The default is off, which is how previous versions of @code{Gdbm} + handled free blocks. If set, this option causes all subsequent free + blocks to be placed in the @emph{global} pool, allowing (in theory) + more file space to be reused more quickly. value (see below) should + be set to either TRUE or FALSE. + @emph{NOTICE: This feature is still under study.} + + GDBM_COALESCEBLKS - Set free block merging to either on or off. + The default is off, which is how previous versions of @code{Gdbm} + handled free blocks. If set, this option causes adjacent free blocks + to be merged. This can become a CPU expensive process with time, though, + especially if used in conjunction with GDBM_CENTFREE. value (see below) + should be set to either TRUE or FALSE. + @emph{NOTICE: This feature is still under study.} + +The return value will be -1 upon failure, or 0 upon success. The global +variable @code{gdbm_errno} will be set upon failure. + +For instance, to set a database to use a cache of 10, after opening it +with @code{gdbm_open}, but prior to accessing it in any way, the following +code could be used: + +@example +int value = 10; +ret = gdbm_setopt(dbf, GDBM_CACHESIZE, &value, sizeof(int)); +@end example + +@node Locking, testgdbm, Options, Top +@chapter File Locking. + +With locking disabled (if @code{gdbm_open} was called with GDBM_NOLOCK), +the user may want to perform their own file locking on the database file +in order to prevent multiple writers operating on the same file +simultaneously. + +In order to support this, the @code{gdbm_fdesc} routine is provided. + +@example +ret = gdbm_fdesc(dbf); +@end example + +The single valid parameter is: + +@table @asis +@item GDBM_FILE dbf +The pointer returned by @code{gdbm_open}. +@end table + +The return value will be the file descriptor of the database. + +@node testgdbm, gdbmexport, Locking, Top +@chapter Test and modify a GDBM database. + +The @command{testgdbm} utility allows you to view and modify an +existing @acronym{GDBM} database or to create a new one. + +@cindex default database, @command{testgdbm} +@cindex @option{-g}, @command{testgdbm} option +When invoked without options, it tries to open a database file called +@file{junk.gdbm}, located in the current working directory. You can +change this default using the @option{-g} command line option. This +option takes a single argument, specifying a file name to open, e.g.: + +@example +$ testgdbm -g file.db +@end example + +@cindex read-only mode, @command{testgdbm} +@cindex @option{-r}, @command{testgdbm} option +The database will be opened in read-write mode, unless the @option{-r} +option is specified, in which case it will be opened only for reading. + +@cindex creating a database, @command{testgdbm} +@cindex @option{-n}, @command{testgdbm} option +If the database does not exist, @command{testgdbm} will create it. +There is a special option @option{-n}, which instructs the utility to +create a new database. If it is used and if the database already +exists, it will be deleted, so use it sparingly. + +@menu +* invocation:: +* shell:: +@end menu + +@node invocation +@section testgdbm invocation + +The following table summarizes all @command{testgdbm} command line +options: + +@table @option +@item -b @var{size} +Set block size. +@item -c @var{size} +Set cache size. +@item -g @var{file} +Operate on @var{file} instead of the default @file{junk.gdbm}. +@item -h +Print a concise help summary. +@item -n +Create the database. +@item -r +Open the database in read-only mode. +@item -s +Synchronize to the disk after each write. +@item -v +Print program version and licensing information and exit. +@end table + +@node shell +@section testgdbm interactive mode +After successful startup, @command{testgdbm} starts a loop, in which +it reads commands from the user, executes them and prints the results +on the standard output. If the standard input is attached to a console, +@command{testgdbm} runs in interactive mode, which is indicated by its +@dfn{prompt}: + +@example +com -> _ +@end example + +The utility finishes when it reads the @samp{q} command (see below) or +it detects end-of-file on its standard input, whichever occurs first. + +A @command{testgdbm} command consists of a @dfn{command letter}, +optionally followed by one or two @dfn{arguments}, separated by any +amount of white space. An argument is any sequence of non-whitespace +characters. Notice, that currently there is no way to enter arguments +containing white space. This limitation will be removed in future +releases. + +Each command letter takes at most two @dfn{formal parameters}, which can be +optional or mandatory. If the number of actual arguments is less than the +number of mandatory parameters, @command{testgdbm} will prompt you to +supply missing arguments. For example, the @samp{s} command takes two +mandatory parameters, so if you invoked it with no arguments, you +would be prompted twice to supply the necessary data, as shown in +example below: + +@example +com -> @kbd{s} +key -> @kbd{three} +data -> @kbd{3} +@end example + +However, such prompting is possible only in interactive mode. In +non-interactive mode (e.g. when running a script), all arguments must +be supplied with each command, otherwise @command{testgdbm} reports an +error and exits immediately. + +@anchor{pager} +@cindex pager, @command{testgdbm} +@cindex @env{PAGER}. +Some commands produce excessive amounts of output. To help you follow +it, @command{testgdbm} will use a pager utility to display such +output. The name of the pager utility is taken from the environment +variable @env{PAGER}. The pager is ivoked only in interactive mode +and only if the estimated number of output lines is greater then the +number of lines on your screen. + +@anchor{nul-termination} +Many of the @command{testgdbm} commands operate on database key and +data values. The utility assumes that both keys and data are +@acronym{ASCII} strings, either nul-terminated or not. By default, +it is assumed that strings are nul-terminated. You can change this +by using @code{z} (for keys) and @code{Z} (for data) commands. + +The following table summarizes all available commands: + +@table @code +@item c +Print the number of entries in the database. +@item d @var{key} +Delete entry with a given @var{key} +@item e @var{file-name} [truncate] +Export the database (similar to @command{gdbmexport}, +@pxref{gdbmexport}) to file @var{file-name}. This command will not +overwrite an existing file, unless the word @samp{truncate} is given +as its second argument. + +@item f @var{key} +Fetch and display a record with the given @var{key}. + +@item i @var{file-name} [replace] +@anchor{import} +Import data from a flat dump file @var{file-name} +(@pxref{gdbmexport}). If the word @samp{replace} is given +as the second argument, any records with the same keys as the already +existing ones will replace them. + +@item l +List the contents of the database (@pxref{pager}). + +@item n [@var{key}] +@itemx 2 +Sequential access: fetch and display a next record. If @var{key} is +given, a record following one with this key will be fetched. +Otherwise, the key supplied by the latest @code{1}, @code{2} or +@var{n} command will be used. + +The second form, @code{2} is a synonym for @code{n} without arguments. + +See also @code{1}, below. + +@xref{Sequential}, for more information on sequential access. + +@item q +Close the database and quit the utility. + +@item s @var{key} @var{data} +Store the @var{data} with @var{key} in the database. If @var{key} +already exists, its data will be replaced. + +@item 1 +Fetch and display the first record in the database. Subsequent +records can be fetched using @code{n} (or @code{2}) command (see above). +@xref{Sequential}, for more information on sequential access. + +@item < @var{file} [replace] +Read entries from @var{file} and store them in the database. If the +word @samp{replace} is given as the second argument, any existing +records with matching keys will be replaced. + +@item r +Reorganize the database (@pxref{Reorganization}). + +@item z +Toggle key nul-termination. Use @code{S} to inspect the current +state. @xref{nul-termination}. + +@item A +Print avail list. + +@item B @var{num} +Print a bucket number @var{num}. This command uses pager +(@pxref{pager}). + +@item C +Print current bucket. This command uses pager (@pxref{pager}). + +@item D +Print hash directory. Uses pager (@pxref{pager}). + +@item F +Print file header. + +@item H @var{key} +Compute and display the hash value for the given @var{key}. + +@item K +Print the bucket cache. Uses pager (@pxref{pager}). + +@item S +Print current program status. The following example shows the +information displayed: + +@example +Database file: junk.gdbm +Zero terminated keys: yes +Zero terminated data: yes +@end example + +@item V +Print version of @command{gdbm}. + +@item Z +Toggle data nul-termination. Use @command{S} to examine the current +status. + +@xref{nul-termination}. + +@item ? +Print a concise command summary, showing each command letter with its +parameters and a short description of what it does. Optional +arguments are enclosed in square brackets. + +@item q +Quit the program. +@end table + +@node gdbmexport, Variables, testgdbm, Top +@chapter Export a database into a portable format. + +The @command{gdbmexport} utility converts the database into a portable +``flat'' format. Files in this format can be used to populate +databases using the @code{i} command of @command{testgdbm} utility +(@pxref{import}). In many cases files in this format are suitable for +sending over the network to populate the database on another machine. +The only exception to this are databases whose records contain +non-@acronym{ASCII} data (e.g. @acronym{C} structures, integers +etc.). For such databases you will be better off by writing a +specialized utility to convert them to an architecture-independent +format. + +If @command{gdbmexport} is linked with @file{libgdbm} +version 1.8.3, it can be used to convert databases from old to new +format. + +The utiity takes two mandatory arguments: the name of the database +file to convert and the output file name, e.g.: + +@example +$ gdbmexport junk.gdbm junk.flat +@end example + +In addition two options are understood: + +@table @option +@item -h +Display short usage summary and exit. + +@item -v +Display program version and licensing information, and exit. +@end table + +@node Variables, Compatibility, gdbmexport, Top +@chapter Two useful variables. + +The following two variables are variables that may need to be used: + +@table @asis +@item gdbm_error gdbm_errno +The variable that contains more information about @code{gdbm} errors +(@code{gdbm.h} has the definitions of the error values). +@item char * gdbm_version +The string containing the version information. +@end table + +@node Compatibility, Bugs, Variables, Top +@chapter Compatibility with standard @code{dbm} and @code{ndbm}. + +GNU @code{dbm} files are not @code{sparse}. You can copy them with the UNIX +@code{cp} command and they will not expand in the copying process. + +There is a compatibility mode for use with programs that already use UNIX +@code{dbm} and UNIX @code{ndbm}. + +GNU @code{dbm} has compatibility functions for @code{dbm}. For @code{dbm} +compatibility functions, you need the include file @code{dbm.h}. + +In this compatibility mode, no @code{gdbm} file pointer is required +by the user, and Only one file may be opened at a time. All users in +compatibility mode are assumed to be writers. If the @code{gdbm} file is a +read only, it will fail as a writer, but will also try to open it as a reader. +All returned pointers in datum structures point to data that @code{gdbm} WILL +free. They should be treated as static pointers (as standard UNIX @code{dbm} +does). The compatibility function names are the same as the UNIX @code{dbm} +function names. Their definitions follow: + +@example +int dbminit(name); +int store(key, content); +datum fetch(key); +int delete(key); +datum firstkey(); +datum nextkey(key); +int dbmclose(); +@end example + +Standard UNIX @code{dbm} and GNU @code{dbm} do not have the same data +format in the file. You cannot access a standard UNIX @code{dbm} file with GNU +@code{dbm}! If you want to use an old database with GNU @code{dbm}, you must +use the @code{conv2gdbm} program. + +Also, GNU @code{dbm} has compatibility functions for @code{ndbm}. For +@code{ndbm} compatibility functions, you need the include file @code{ndbm.h}. + +Again, just like @code{ndbm}, any returned datum can be assumed to be static +storage. You do not have to free that memory, the @code{ndbm} compatibility +functions will do it for you. + +The functions are: + +@example +DBM *dbm_open(name, flags, mode); +void dbm_close(file); +datum dbm_fetch(file, key); +int dbm_store(file, key, @code{content}, flags); +int dbm_delete(file, key); +datum dbm_firstkey(file); +datum dbm_nextkey(file); +int dbm_error(file); +int dbm_clearerr(file); +int dbm_dirfno(file); +int dbm_pagfno(file); +int dbm_rdonly(file); +@end example + +If you want to compile an old C program that used UNIX @code{dbm} or @code{ndbm} +and want to use @code{gdbm} files, execute the following @code{cc} command: + +@example +cc ... -L/usr/local/lib -lgdbm -lgdbm_compat +@end example + +@node Bugs, , Compatibility, Top +@chapter Problems and bugs. + +If you have problems with GNU @code{dbm} or think you've found a bug, +please report it. Before reporting a bug, make sure you've actually +found a real bug. Carefully reread the documentation and see if it +really says you can do what you're trying to do. If it's not clear +whether you should be able to do something or not, report that too; it's +a bug in the documentation! + +Before reporting a bug or trying to fix it yourself, try to isolate it +to the smallest possible input file that reproduces the problem. Then +send us the input file and the exact results @code{gdbm} gave you. Also +say what you expected to occur; this will help us decide whether the +problem was really in the documentation. + +Once you've got a precise problem, send e-mail to: + +@example +Internet: @file{bug-gnu-utils@@prep.ai.mit.edu}. +UUCP: @file{mit-eddie!prep.ai.mit.edu!bug-gnu-utils}. +@end example + +Please include the version number of GNU @code{dbm} you are using. You can get +this information by printing the variable @code{gdbm_version} (see Variables). + +Non-bug suggestions are always welcome as well. If you have questions +about things that are unclear in the documentation or are just obscure +features, please report them too. + +You may contact the author by: +@example + e-mail: phil@@cs.wwu.edu + us-mail: Philip A. Nelson + Computer Science Department + Western Washington University + Bellingham, WA 98226 +@end example |