gdbm - phpMan

File: gdbm.info,  Node: Top,  Next: Copying,  Up: (dir)
The GNU database manager.
*************************
GNU `dbm' is a library of functions implementing a hashed database on a
disk file.  This manual documents GNU `dbm' Version 1.10 (`gdbm').  The
software was originally written by Philip A.  Nelson.  This document
was originally written by Pierre Gaumond from texts written by Phil.
* 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.
* Flat files::                 Export and import to Flat file format.
* 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:
* Error codes::                Error codes returned by `gdbm' calls.
* Variables::                  Two useful variables.
* Compatibility::              Compatibility with UNIX dbm and ndbm.
* Bugs::                       Problems and bugs.
* Resources::                  Additional resources,
* GNU Free Documentation License::      Document license.
* Index::                       Index
File: gdbm.info,  Node: Copying,  Next: Intro,  Prev: Top,  Up: Top
1 Copying Conditions.
*********************
This library is "free"; this means that everyone is free to use it and
free to redistribute it on a free basis.  GNU `dbm' (`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 `gdbm'
that they might get from you.
   Specifically, we want to make sure that you have the right to give
away copies `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.
   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 `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.
   Also, for our own protection, we must make certain that everyone
finds out that there is no warranty for anything in the `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.
   `Gdbm' is currently distributed under the terms of the GNU General
Public License, Version 3.  (_NOT_ under the GNU General Library Public
License.)  A copy the GNU General Public License is included with the
distribution of `gdbm'.
File: gdbm.info,  Node: Intro,  Next: List,  Prev: Copying,  Up: Top
2 Introduction to GNU `dbm'.
****************************
GNU `dbm' (`gdbm') is a library of database functions that use
extensible hashing and works similar to the standard UNIX `dbm'
functions.  These routines are provided to a programmer needing to
create and manipulate a hashed database. (`gdbm' is _NOT_ a complete
database package for an end user.)
   The basic use of `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 `gdbm' is the structure:
       typedef struct {
                  char *dptr;
                  int  dsize;
               } datum;
   This structure allows for arbitrary sized keys and data items.
   The key/data pairs are stored in a `gdbm' disk file, called a `gdbm'
database.  An application must open a `gdbm' database to be able
manipulate the keys and data contained in the database.  `gdbm' allows
an application to have multiple databases open at the same time.  When
an application opens a `gdbm' database, it is designated as a `reader'
or a `writer'.  A `gdbm' database can be opened by at most one writer
at a time.  However, many readers may open the database simultaneously.
Readers and writers can not open the `gdbm' database at the same time.
File: gdbm.info,  Node: List,  Next: Open,  Prev: Intro,  Up: Top
3 List of functions.
********************
The following is a quick list of the functions contained in the `gdbm'
library.  The include file `gdbm.h', that can be included by the user,
contains a definition of these functions.
     #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);
   The `gdbm.h' include file is often in the `/usr/local/include'
directory. (The actual location of `gdbm.h' depends on your local
installation of `gdbm'.)
File: gdbm.info,  Node: Open,  Next: Close,  Prev: List,  Up: Top
4 Opening the database.
***********************
 -- gdbm interface: GDBM_FILE gdbm_open (const char *NAME, int
          BLOCK_SIZE, int FLAGS, int MODE, void (*fatal_func)(const
          char *))
     Initializes `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 arguments are:
    NAME
          The name of the file (the complete name, `gdbm' does not
          append any characters to this name).
    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 block size is
          used, otherwise the value of BLOCK_SIZE is used.
    FLAGS
          If `flags' is set to `GDBM_READER', the user wants to just
          read the database and any call to `gdbm_store' or
          `gdbm_delete' will fail.  Many readers can access the
          database at the same time.  If `flags' is set to
          `GDBM_WRITER', the user wants both read and write access to
          the database and requires exclusive access.  If `flags' is set
          to `GDBM_WRCREAT', the user wants both read and write access
          to the database and wants it created if it does not already
          exist.  If `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, `GDBM_NOLOCK', which prevents the
          library from performing any locking on the database file, and
          `GDBM_NOMMAP', which disables the memory mapping mechanism.
          The option `GDBM_FAST' is now obsolete, since `gdbm' defaults
          to no-sync mode.
          If the host `open' call (*note open: (open(2))open.)
          supports the `O_CLOEXEC' flag, the `GDBM_CLOEXEC' can be or'd
          into the flags, to enable the close-on-exec flag for the
          database file descriptor.
    MODE
          File mode (see *note change permissions of a file:
          (chmod(2))chmod, and *note open a file: (open(2))open.),
          which is used if the file is created).
    FATAL_FUNC
          A function for `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, `gdbm' will use a default
          function.
     The return value, is the pointer needed by all other functions to
     access that `gdbm' file.  If the return is the `NULL' pointer,
     `gdbm_open' was not successful.  The errors can be found in
     `gdbm_errno' variable (*note gdbm_errno: Variables.).  Available
     error codes are discussed in *note Error codes::.
     In all of the following calls, the parameter DBF refers to the
     pointer returned from `gdbm_open'.
File: gdbm.info,  Node: Close,  Next: Store,  Prev: Open,  Up: Top
5 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:
 -- gdbm interface: void gdbm_close (GDBM_FILE DBF)
     This function closes the `gdbm' file and frees all memory
     associated with it.  The parameter is:
    DBF
          The pointer returned by `gdbm_open'.
File: gdbm.info,  Node: Store,  Next: Fetch,  Prev: Close,  Up: Top
6 Inserting and replacing records in the database.
**************************************************
 -- gdbm interface: int gdbm_store (GDBM_FILE DBF, datum KEY, datum
          CONTENT, int FLAG)
     The function `gdbm_store' inserts or replaces records in the
     database.
     The parameters are:
    DBF
          The pointer returned by `gdbm_open'.
    KEY
          The search key.
    CONTENT
          The data to be associated with the key.
    FLAG
          Defines the action to take when the key is already in the
          database.  The value `GDBM_REPLACE' (defined in `gdbm.h')
          asks that the old data be replaced by the new CONTENT.  The
          value `GDBM_INSERT' asks that an error be returned and no
          action taken if the KEY already exists.
     This function can return the following values:
    -1
          The item was not stored in the database because the caller
          was not an official writer or either KEY or CONTENT have a
          `NULL' `dptr' field.
          Both KEY and 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, it cannot be valid data.
    +1
          The item was not stored because the argument FLAG was
          `GDBM_INSERT' and the KEY was already in the database.
    0
          No error.  The value of CONTENT is keyed by KEY.  The file on
          disk is updated to reflect the structure of the new database
          before returning from this function.
If you store data for a KEY that is already in the data base, `gdbm'
replaces the old data with the new data if called with `GDBM_REPLACE'.
You do not get two data items for the same `key' and you do not get an
error from `gdbm_store'.
   The size in `gdbm' is not restricted like `dbm' or `ndbm'.  Your
data can be as large as you want.
File: gdbm.info,  Node: Fetch,  Next: Delete,  Prev: Store,  Up: Top
7 Searching for records in the database.
****************************************
 -- gdbm interface: datum gdbm_fetch (GDBM_FILE DBF, datum KEY)
     Looks up a given KEY and returns the information associated with
     it.  The `dptr' field in the structure that is returned points to a
     memory block allocated by `malloc'.  It is the caller's
     responsibility to free it when no longer needed.
     If the `dptr' is `NULL', no data was found.
     The parameters are:
    DBF
          The pointer returned by `gdbm_open'.
    KEY
          The search key.
An example of using this function:
     content = gdbm_fetch (dbf, key);
     if (content.dptr == NULL)
       {
         fprintf(stderr, "key not found\n");
       }
     else
       {
         /* do something with content.dptr */
       }
   You may also search for a particular key without retrieving it:
 -- gdbm interface: int gdbm_exists (GDBM_FILE DBF, datum KEY)
     Returns `true' (`1') if the KEY exists in DBF and `false' (`0')
     otherwise.
     The parameters are:
    DBF
          The pointer returned by `gdbm_open'.
    KEY
          The search key.
File: gdbm.info,  Node: Delete,  Next: Sequential,  Prev: Fetch,  Up: Top
8 Removing records from the database.
*************************************
To remove some data from the database, use the `gdbm_delete' function.
 -- gdbm interface: int gdbm_delete (GDBM_FILE DBF, datum KEY)
     Deletes the data associated with the given KEY, if it exists in
     the database DBF.  The file on disk is updated to reflect the
     structure of the new database before returning from this function.
     The parameters are:
    DBF
          The pointer returned by `gdbm_open'.
    DATUM KEY
          The search key.
     The function returns `-1' if the item is not present or the
     requester is a reader.  The return of `0' marks a successful
     delete.
File: gdbm.info,  Node: Sequential,  Next: Reorganization,  Prev: Delete,  Up: Top
9 Sequential access to records.
*******************************
The next two functions allow for accessing all items in the database.
This access is not `key' sequential, but it is guaranteed to visit every
`key' in the database once.  The order has to do with the hash values.
`gdbm_firstkey' starts the visit of all keys in the database.
`gdbm_nextkey' finds and reads the next entry in the hash structure for
`dbf'.
 -- gdbm interface: datum gdbm_firstkey (GDBM_FILE DBF)
     Initiate sequential access to the database DBF.  The returned
     value is the first key accessed in the database.  If the `dptr'
     field in the returned datum is `NULL', the database contains no
     data.
     Otherwise, `dptr' points to a memory block obtained from `malloc',
     which holds the key value.  The caller is responsible for freeing
     this memory block when no longer needed.
 -- gdbm interface: datum gdbm_nextkey (GDBM_FILE DBF, datum PREV)
     This function continues the iteration over the keys in DBF,
     initiated by `gdbm_firstkey'.  The parameter PREV holds the value
     returned from a previous call to `gdbm_nextkey' or `gdbm_firstkey'.
     The function returns next key from the database.  If the `dptr'
     field in the returned datum is `NULL', all keys in the database
     has been visited.
     Otherwise, `dptr' points to a memory block obtained from `malloc',
     which holds the key value.  The caller is responsible for freeing
     this memory block when no longer needed.
   These functions were intended to visit the database in read-only
algorithms, for instance, to validate the database or similar
operations.  The usual algorithm for sequential access is:
        key = gdbm_firstkey (dbf);
        while (key.dptr)
          {
             datum nextkey;
             /* do something with the key */
             ...
             /* Obtain the next key */
             nextkey = gdbm_nextkey (dbf, key);
             /* Reclaim the memory used by the key */
             free (key.dptr);
             /* Use nextkey in the next iteration. */
             key = nextkey;
          }
   Care should be taken when the `gdbm_delete' function is used in such
a loop.  File visiting is based on a "hash table".  The `gdbm_delete'
function re-arranges the hash table to make sure that any collisions in
the table do not leave some item "un-findable".  The original key order
is _not_ guaranteed to remain unchanged in all instances.  So it is
possible that some key will not be visited if a loop like the following
is executed:
        key = gdbm_firstkey (dbf);
        while (key.dptr)
          {
             datum nextkey;
             if (some condition)
               {
                  gdbm_delete (dbf, key);
               }
              nextkey = gdbm_nextkey (dbf, key);
              free (key.dptr);
              key = nextkey;
           }
File: gdbm.info,  Node: Reorganization,  Next: Sync,  Prev: Sequential,  Up: Top
10 Database reorganization.
***************************
The following function should be used very seldom.
 -- gdbm interface: int gdbm_reorganize (GDBM_FILE DBF)
     Reorganizes the database.
     The parameter is:
    DBF
          The pointer returned by `gdbm_open'.
   If you have had a lot of deletions and would like to shrink the space
used by the `gdbm' file, this function will reorganize the database.
This results, in particular, in shortening the length of a `gdbm' file
by removing the space occupied by deleted records.
   This reorganization requires creating a new file and inserting all
the elements in the old file DBF into the new file.  The new file is
then renamed to the same name as the old file and 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.
File: gdbm.info,  Node: Sync,  Next: Flat files,  Prev: Reorganization,  Up: Top
11 Database Synchronization
***************************
Unless your database was opened with the `GDBM_SYNC' flag, `gdbm' does
not wait for writes to be flushed to the disk before continuing.  This
allows for 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.
 -- gdbm interface: void gdbm_sync (GDBM_FILE DBF)
     Synchronizes the changes in DBF with its disk file.  The parameter
     is a pointer returned by `gdbm_open'.
     This function would usually be called after a complete set of
     changes have been made to the database and before some long
     waiting time.  The `gdbm_close' function automatically calls the
     equivalent of `gdbm_sync' so no call is needed if the database is
     to be closed immediately after the set of changes have been made.
File: gdbm.info,  Node: Flat files,  Next: Errors,  Prev: Sync,  Up: Top
12 Export and Import
********************
`Gdbm' databases can be converted into a portable "flat format".  This
format can be used, for example, to migrate between the different
versions of `gdbm' databases.  Generally speaking, flat files are safe
to send over the network, and can be used to recreate the database on
another machine.  The recreated database is guaranteed to be a
byte-to-byte equivalent of the database from which the flat file was
created.  This does not necessarily mean, however, that this file can
be used in the same way as the original one.  For example, if the
original database contained non-ASCII data (e.g.  C structures,
integers etc.), the recreated database can be of any use only if the
target machine has the same integer size and byte ordering as the
source one and if its C compiler uses the same packing conventions as
the one which generated C which populated the original database.  In
general, such binary databases are not portable between machines,
unless you follow some stringent rules on what data is written to them
and how it is interpreted.
 -- gdbm interface: int gdbm_export (GDBM_FILE DBF, const char
          *EXPORTFILE, int FLAG, int MODE)
     Create a flat file from the `gdbm' database.  The parameters are:
    DBF
          A pointer to the source database, returned by a call to
          `gdbm_open'.  The database must be open in `GDBM_WRITER' mode.
    EXPORTFILE
          The name of the output file.
    FLAG
          How to create the output file.  If FLAG is `GDBM_WRCREAT',
          the file will be created if it does not exist already.
          Otherwise, if it is `GDBM_NEWDB', it will be created if it
          does not exist, and truncated otherwise.
    MODE
          The permissions to use when creating the output file.  See
          *note open a file: (open(2))open, for a detailed discussion.
 -- gdbm interface: int gdbm_import (GDBM_FILE DBF, const char
          *IMPORTFILE, int FLAG)
     Populates the database from an existing flat file.
    DBF
          A pointer to the source database, returned by a call to
          `gdbm_open'.  The database must be open in `GDBM_WRITER' mode.
    IMPORTFILE
          The name of the input flat file.  The file must exist.
    FLAG
          The FLAG argument to be passed to `gdbm_store' function when
          adding new records.  *Note Store::, for a description of its
          effect.
   See also *note gdbmexport::, *note testgdbm export::, and *note
testgdbm import::.
File: gdbm.info,  Node: Errors,  Next: Options,  Prev: Flat files,  Up: Top
13 Error strings.
*****************
To convert a `gdbm' error code into English text, use this routine:
 -- gdbm interface: const char * gdbm_strerror (gdbm_error ERRNO)
     Converts ERRNO (which is an integer value) into a human-readable
     descriptive text.  Returns a pointer to a static string.  The
     caller must not alter or free the returned pointer.
     The ERRNO argument is usually the value of the global variable
     `gdbm_errno'.  *Note gdbm_errno: Variables.
File: gdbm.info,  Node: Options,  Next: Locking,  Prev: Errors,  Up: Top
14 Setting options
******************
`Gdbm' supports the ability to set certain options on an already open
database.
 -- gdbm interface: int gdbm_setopt (GDBM_FILE DBF, int OPTION, void
          *VALUE, int SIZE)
     Sets an option on the database or returns the value of an option.
     The parameters are:
    DBF
          The pointer returned by `gdbm_open'.
    OPTION
          The option to be set or retreived.
    VALUE
          A pointer to the value to which OPTION will be set or where to
          place the option value (depending on the option).
    SIZE
          The length of the data pointed to by VALUE.
   The valid options are:
GDBM_SETCACHESIZE
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.  The VALUE should point
     to a `size_t' holding the desired cache size.
     The `GDBM_CACHESIZE' option is provided for compatibility with
     earlier versions.
GDBM_GETCACHESIZE
     Return the size of the internal bucket cache.  The VALUE should
     point to a `size_t' variable, where the size will be stored.
GDBM_GETFLAGS
     Return the flags describing the state of the database.  The VALUE
     should point to a `int' variable where to store the flags.  The
     return is the same as the flags used when opening the database
     (*note gdbm_open: Open.), except that it reflects the current
     state (which may have been altered by another calls to
     `gdbm_setopt'.
GDBM_FASTMODE
     Enable or disable the "fast writes mode", i.e. writes without
     subsequent synchronization.  The VALUE should point to an integer:
     `TRUE' to enable fast mode, and `FALSE' to disable it.
     This option is retained for compatibility with previous versions of
     `gdbm'.  Its effect is the reverse of `GDBM_SETSYNCMODE' (see
     below).
GDBM_SETSYNCMODE
GDBM_SYNCMODE
     Turn on or off file system synchronization operations.  This
     setting defaults to off.  The VALUE should point to an integer:
     `TRUE' to turn synchronization on, and `FALSE' to turn it off.
     Note, that this option is a reverse of `GDBM_FASTMODE', i.e.
     calling `GDBM_SETSYNCMODE' with `TRUE' has the same effect as
     calling `GDBM_FASTMODE' with `FALSE'.
     The `GDBM_SYNCMODE' option is provided for compatibility with
     earlier versions.
GDBM_GETSYNCMODE
     Return the current synchronization status.  The VALUE should point
     to an `int' where the status will be stored.
GDBM_SETCENTFREE
GDBM_CENTFREE
     _NOTICE: This feature is still under study._
     Set central free block pool to either on or off.  The default is
     off, which is how previous versions of `gdbm' handled free blocks.
     If set, this option causes all subsequent free blocks to be placed
     in the _global_ pool, allowing (in theory) more file space to be
     reused more quickly.  The VALUE should point to an integer: `TRUE'
     to turn central block pool on, and `FALSE' to turn it off.
     The `GDBM_CENTFREE' option is provided for compatibility with
     earlier versions.
GDBM_SETCOALESCEBLKS
GDBM_COALESCEBLKS
     _NOTICE: This feature is still under study._
     Set free block merging to either on or off.  The default is off,
     which is how previous versions of `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.  The VALUE should point to
     an integer: `TRUE' to turn free block merging on, and `FALSE' to
     turn it off.
GDBM_GETCOALESCEBLKS
     Return the current status of free block merging.  The VALUE should
     point to an `int' where the status will be stored.
GDBM_SETMAXMAPSIZE
     Sets maximum size of a memory mapped region.  The VALUE should
     point to a value of type `size_t', `unsigned long' or `unsigned'.
     The actual value is rounded to the nearest page boundary (the page
     size is obtained from `sysconf(_SC_PAGESIZE)').
GDBM_GETMAXMAPSIZE
     Return the maximum size of a memory mapped region.  The VALUE
     should point to a value of type `size_t' where to return the data.
GDBM_SETMMAP
     Enable or disable memory mapping mode.  The VALUE should point to
     an integer: `TRUE' to enable memory mapping or `FALSE' to disable
     it.
GDBM_GETMMAP
     Check whether memory mapping is enabled.  The VALUE should point
     to an integer where to return the status.
GDBM_GETDBNAME
     Return the name of the database disk file.  The VALUE should point
     to a variable of type `char**'.  A pointer to the newly allocated
     copy of the file name will be placed there.  The caller is
     responsible for freeing this memory when no longer needed.  For
     example:
          char *name;
          if (gdbm_setopt (dbf, GDBM_GETDBNAME, &name, sizeof (name)))
            {
               fprintf (stderr, "gdbm_setopt failed: %s\n",
          	      gdbm_strerror (gdbm_errno));
            }
          else
            {
              printf ("database name: %s\n", name);
              free (name);
            }

   The return value will be `-1' upon failure, or `0' upon success.
The global variable `gdbm_errno' will be set upon failure.
   For instance, to set a database to use a cache of 10, after opening
it with `gdbm_open', but prior to accessing it in any way, the following
code could be used:
     int value = 10;
     ret = gdbm_setopt (dbf, GDBM_CACHESIZE, &value, sizeof (int));
File: gdbm.info,  Node: Locking,  Next: testgdbm,  Prev: Options,  Up: Top
15 File Locking.
****************
With locking disabled (if `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 `gdbm_fdesc' routine is provided.
 -- gdbm interface: int gdbm_fdesc (GDBM_FILE DBF)
     Returns the file descriptor of the database DBF.  This value can
     be used as an argument to `flock', `lockf' or similar calls.
File: gdbm.info,  Node: testgdbm,  Next: gdbmexport,  Prev: Locking,  Up: Top
16 Test and modify a GDBM database.
***********************************
The `testgdbm' utility allows you to view and modify an existing GDBM
database or to create a new one.
   When invoked without options, it tries to open a database file called
`junk.gdbm', located in the current working directory.  You can change
this default using the `-g' command line option.  This option takes a
single argument, specifying the file name to open, e.g.:
     $ testgdbm -g file.db
   The database will be opened in read-write mode, unless the `-r'
option is specified, in which case it will be opened only for reading.
   If the database does not exist, `testgdbm' will create it.  There is
a special 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::
File: gdbm.info,  Node: invocation,  Next: shell,  Up: testgdbm
16.1 testgdbm invocation
========================
The following table summarizes all `testgdbm' command line options:
`-b SIZE'
     Set block size.
`-c SIZE'
     Set cache size.
`-g FILE'
     Operate on FILE instead of the default `junk.gdbm'.
`-h'
     Print a concise help summary.
`-n'
     Create the database.
`-r'
     Open the database in read-only mode.
`-s'
     Synchronize to the disk after each write.
`-v'
     Print program version and licensing information and exit.
File: gdbm.info,  Node: shell,  Prev: invocation,  Up: testgdbm
16.2 testgdbm interactive mode
==============================
After successful startup, `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,
`testgdbm' runs in interactive mode, which is indicated by its "prompt":
     testgdbm> _
   The utility finishes when it reads the `quit' command (see below) or
detects end-of-file on its standard input, whichever occurs first.
   A `testgdbm' command consists of a "command verb", optionally
followed by one or two "arguments", separated by any amount of white
space.  A command verb can be entered either in full or in an
abbreviated form, as long as that abbreviation does not match any other
verb.  For example, `co' can be used instead of `count' and `ca'
instead of `cache'.  Furthermore, many command verbs also have
single-letter forms, called "command letters".
   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 takes at most two "formal parameters", which can be
optional or mandatory.  If the number of actual arguments is less than
the number of mandatory parameters, `testgdbm' will prompt you to
supply missing arguments.  For example, the `store' 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:
     testgdbm> store
     key> three
     data> 3
   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 `testgdbm' will report an
error and exit immediately.
   Some commands produce excessive amounts of output.  To help you
follow it, `testgdbm' uses a pager utility to display such output.  The
name of the pager utility is taken from the environment variable
`PAGER'.  The pager is invoked only in interactive mode and only if the
estimated number of output lines is greater then the number of lines on
your screen.
   Many of the `testgdbm' commands operate on database key and data
values.  The utility assumes that both keys and data are ASCII strings,
either nul-terminated or not.  By default, it is assumed that strings
are nul-terminated.  You can change this by using `z' (`key-zero', for
keys) and `Z' (`data-zero', for data) commands.
   The following table summarizes all available commands:
 -- command verb: count
 -- command abbrev: co
 -- command letter: c
     Print the number of entries in the database.
 -- command verb: delete KEY
 -- command abbrev: de KEY
 -- command letter: d KEY
     Delete entry with a given KEY
 -- command verb: export FILE-NAME [truncate]
 -- command abbrev: e FILE-NAME [truncate]
     Export the database to the flat file FILE-NAME.  *Note Flat
     files::, for a description of the flat file format and its
     purposes.  This command will not overwrite an existing file,
     unless the word `truncate' is given as its second argument.
     See also *note gdbmexport::.
 -- command verb: fetch KEY
 -- command abbrev: fe KEY
 -- command letter: f KEY
     Fetch and display a record with the given KEY.
 -- command verb: import FILE-NAME [replace]
 -- command abbrev: i FILE-NAME [replace]
     Import data from a flat dump file FILE-NAME (*note Flat files::).
     If the word `replace' is given as the second argument, any records
     with the same keys as the already existing ones will replace them.
 -- command verb: list
 -- command abbrev: l
     List the contents of the database (*note pager::).
 -- command verb: next [KEY]
 -- command abbrev: n [KEY]
     Sequential access: fetch and display a next record.  If KEY is
     given, a record following one with this key will be fetched.
     Otherwise, the key supplied by the latest `1', `2' or N command
     will be used.
     See also `first', below.
     *Note Sequential::, for more information on sequential access.
 -- command verb: quit
 -- command abbrev: q
     Close the database and quit the utility.
 -- command verb: store KEY DATA
 -- command abbrev: sto KEY DATA
 -- command letter: s KEY DATA
     Store the DATA with KEY in the database.  If KEY already exists,
     its data will be replaced.
 -- command verb: first
 -- command abbrev: fi
 -- command letter: 1
     Fetch and display the first record in the database.  Subsequent
     records can be fetched using `next' command (see above).  *Note
     Sequential::, for more information on sequential access.
 -- command verb: read FILE [replace]
 -- command abbrev: rea FILE [replace]
 -- command letter: < FILE [replace]
     Read entries from FILE and store them in the database.  If the
     word `replace' is given as the second argument, any existing
     records with matching keys will be replaced.
 -- command verb: reorganize
 -- command abbrev: reo
 -- command letter: r
     Reorganize the database (*note Reorganization::).
 -- command verb: key-zero
 -- command abbrev: k
 -- command letter: z
     Toggle key nul-termination.  Use `status' to inspect the current
     state.  *Note nul-termination::.
 -- command verb: avail
 -- command abbrev: a
 -- command letter: A
     Print the "avail list".
 -- command verb: bucket
 -- command abbrev: b
 -- command letter: B
     Print the bucket number NUM.
 -- command verb: current
 -- command abbrev: cu
 -- command letter: C
     Print the current bucket.
 -- command verb: dir
 -- command abbrev: di
 -- command letter: D
     Print hash directory.
 -- command verb: header
 -- command abbrev: hea
 -- command letter: F
     Print file header.
 -- command verb: hash KEY
 -- command abbrev: ha KEY
 -- command letter: H KEY
     Compute and display the hash value for the given KEY.
 -- command verb: cache
 -- command abbrev: ca
 -- command letter: K
     Print the bucket cache.
 -- command verb: status
 -- command abbrev: sta
 -- command letter: S
     Print current program status.  The following example shows the
     information displayed:
          Database file: junk.gdbm
          Zero terminated keys: yes
          Zero terminated data: yes
 -- command verb: version
 -- command abbrev: v
     Print the version of `gdbm'.
 -- command verb: data-zero
 -- command abbrev: da
 -- command letter: Z
     Toggle data nul-termination.  Use `status' to examine the current
     status.
     *Note nul-termination::.
 -- command verb: help
 -- command abbrev: hel
 -- command letter: ?
     Print a concise command summary, showing each command letter and
     verb with its parameters and a short description of what it does.
     Optional arguments are enclosed in square brackets.
File: gdbm.info,  Node: gdbmexport,  Next: Error codes,  Prev: testgdbm,  Up: Top
17 Export a database into a portable format.
********************************************
The `gdbmexport' utility converts the database into a portable "flat
format".  Files in this format can be used to populate databases using
the `gdbm_import' function (*note gdbm_import: Flat files.) or the `i'
command of `testgdbm' utility (*note testgdbm 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-ASCII data (e.g.  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 `gdbmexport' is linked with `libgdbm' version 1.8.3, it can be
used to convert databases from old to new format.
   The utility takes two mandatory arguments: the name of the database
file to convert and the output file name, e.g.:
     $ gdbmexport junk.gdbm junk.flat
   In addition two options are understood:
`-h'
     Display short usage summary and exit.
`-v'
     Display program version and licensing information, and exit.
File: gdbm.info,  Node: Error codes,  Next: Variables,  Prev: gdbmexport,  Up: Top
19 Error codes
**************
This chapter summarizes the error codes which can be set by the
functions in `gdbm' library.
GDBM_NO_ERROR
     No error occurred.
GDBM_MALLOC_ERROR
     Memory allocation failed.  Not enough memory.
GDBM_BLOCK_SIZE_ERROR
     This error is set by the `gdbm_open' function (*note Open::), if
     the value of its BLOCK_SIZE argument is incorrect.
GDBM_FILE_OPEN_ERROR
     The library was not able to open a disk file.  This can be set by
     `gdbm_open' (*note Open::), `gdbm_export' and `gdbm_import'
     functions (*note Flat files::).
     Inspect the value of the system `errno' variable to get more
     detailed diagnostics.
GDBM_FILE_WRITE_ERROR
     Writing to a disk file failed.  This can be set by `gdbm_open'
     (*note Open::), `gdbm_export' and `gdbm_import' functions.
     Inspect the value of the system `errno' variable to get more
     detailed diagnostics.
GDBM_FILE_SEEK_ERROR
     Positioning in a disk file failed.  This can be set by `gdbm_open'
     (*note Open::) function.
     Inspect the value of the system `errno' variable to get a more
     detailed diagnostics.
GDBM_FILE_READ_ERROR
     Reading from a disk file failed.  This can be set by `gdbm_open'
     (*note Open::), `gdbm_export' and `gdbm_import' functions.
     Inspect the value of the system `errno' variable to get a more
     detailed diagnostics.
GDBM_BAD_MAGIC_NUMBER
     The file given as argument to `gdbm_open' function is not a valid
     `gdbm' file: it has a wrong magic number.
GDBM_EMPTY_DATABASE
     The file given as argument to `gdbm_open' function is not a valid
     `gdbm' file: it has zero length.
GDBM_CANT_BE_READER
     This error code is set by the `gdbm_open' function if it is not
     able to lock file when called in `GDBM_READER' mode (*note
     GDBM_READER: Open.).
GDBM_CANT_BE_WRITER
     This error code is set by the `gdbm_open' function if it is not
     able to lock file when called in writer mode (*note Open::).
GDBM_READER_CANT_DELETE
     Set by the `gdbm_delete' (*note Delete::) if it attempted to
     operate on a database that is open in read-only mode (*note
     GDBM_READER: Open.).
GDBM_READER_CANT_STORE
     Set by the `gdbm_store' (*note Store::) if it attempted to operate
     on a database that is open in read-only mode (*note GDBM_READER:
     Open.).
GDBM_READER_CANT_REORGANIZE
     Set by the `gdbm_reorganize' (*note Reorganization::) if it
     attempted to operate on a database that is open in read-only mode
     (*note GDBM_READER: Open.).
GDBM_UNKNOWN_UPDATE
     Currently unused.  Reserved for future uses.
GDBM_ITEM_NOT_FOUND
     Requested item was not found.  This error is set by `gdbm_delete'
     (*note Delete::) and `gdbm_fetch' (*note Fetch::) when the
     requested KEY value is not found in the database.
GDBM_REORGANIZE_FAILED
     The `gdbm_reorganize' function is not able to create a temporary
     database.  *Note Reorganization::.
GDBM_CANNOT_REPLACE
     Cannot replace existing item.  This error is set by the
     `gdbm_store' if the requested KEY value is found in the database
     and the FLAG parameter is not `GDBM_REPLACE'.  *Note Store::, for
     a detailed discussion.
GDBM_ILLEGAL_DATA
     Either KEY or CONTENT parameter was wrong in a call to to
     `gdbm_store' (*note Store::).
GDBM_OPT_ALREADY_SET
     Requested option can be set only once and was already set.  This
     error is returned by the `gdbm_setopt' function.  *Note
     GDBM_CACHESIZE: Options.
GDBM_OPT_ILLEGAL
     The OPTION argument is not valid or the VALUE argument points to
     an invalid value in a call to `gdbm_setopt' function.  *Note
     Options::.
GDBM_BYTE_SWAPPED
     The `gdbm_open' function (*note Open::) attempts to open a
     database which is created on a machine with different byte
     ordering.
GDBM_BAD_FILE_OFFSET
     The `gdbm_open' function (*note Open::) sets this error code if
     the file it tries to open has a wrong magic number.
GDBM_BAD_OPEN_FLAGS
     Set by the `gdbm_export' function if supplied an invalid FLAGS
     argument.  *Note Flat files::.
GDBM_FILE_STAT_ERROR
     Getting information about a disk file failed.  The system `errno'
     will give more details about the error.
     This error can be set by the following functions: `gdbm_open',
     `gdbm_reorganize'.
GDBM_FILE_EOF
     End of file was encountered where more data was expected to be
     present.  This error can occur when fetching data from the database
     and usually means that the database is truncated or otherwise
     corrupted.
     This error can be set by any GDBM function that does I/O.  Some of
     these functions are: `gdbm_delete', `gdbm_exists', `gdbm_fetch',
     `gdbm_export', `gdbm_import', `gdbm_reorganize', `gdbm_firstkey',
     `gdbm_nextkey', `gdbm_store'.
File: gdbm.info,  Node: Variables,  Next: Compatibility,  Prev: Error codes,  Up: Top
18 Useful global variables.
***************************
The following global variables and constants are available:
 -- Variable: gdbm_error gdbm_errno
     This variable contains error code from the last failed `gdbm'
     call.  *Note Error codes::, for a list of available error codes and
     their descriptions.
     Use `gdbm_strerror' (*note Errors::) to convert it to a
     descriptive text.
 -- Variable: const char * gdbm_errlist[]
     This variable is an array of error descriptions, which is used by
     `gdbm_strerror' to convert error codes to human-readable text
     (*note Errors::).  You can access it directly, if you wish so.  It
     contains `_GDBM_MAX_ERRNO + 1' elements and can be directly
     indexed by the error code to obtain a corresponding descriptive
     text.
 -- Constant: _GDBM_MIN_ERRNO
     The minimum error code used by `gdbm'.
 -- Constant: _GDBM_MAX_ERRNO
     The maximum error code used by `gdbm'.
 -- Variable: const char * gdbm_version
     A string containing the version information.
 -- Variable: int const gdbm_version_number[3]
     This variable contains the `gdbm' version numbers:
     Index                       Meaning
     ---------------------------------------------------------------
     0                           Major number
     1                           Minor number
     2                           Patchlevel number
     Additionally, the following constants are defined in the `gdbm.h'
     file:
    GDBM_VERSION_MAJOR
          Major number.
    GDBM_VERSION_MINOR
          Minor number.
    GDBM_VERSION_PATCH
          Patchlevel number.
     These can be used to verify whether the header file matches the
     library.
   To compare two split-out version numbers, use the following function:
 -- gdbm interface: int gdbm_version_cmp (int const A[3], int const
          B[3])
     Compare two version numbers.  Return `-1' if A is less than B, `1'
     if A is greater than B and `0' if they are equal.
     Comparison is done from left to right, so that:
          a = { 1, 8, 3 };
          b = { 1, 8, 3 };
          gdbm_version_cmp (a, b) => 0
          a = { 1, 8, 3 };
          b = { 1, 8, 2 };
          gdbm_version_cmp (a, b) => 1
          a = { 1, 8, 3 };
          b = { 1, 9. 0 };
          gdbm_version_cmp (a, b) => -1
File: gdbm.info,  Node: Compatibility,  Next: Bugs,  Prev: Variables,  Up: Top
20 Compatibility with standard `dbm' and `ndbm'.
************************************************
`Gdbm' includes a compatibility layer, which provides traditional
`ndbm' and older `dbm' functions.  The layer is compiled and installed
if the `--enable-libgdbm-compat' option is used when configuring the
package.
   The compatibility layer consists of two header files: `ndbm.h' and
`dbm.h' and the `libgdbm_compat' library.
   Older programs using `ndbm' or `dbm' interfaces can use
`libgdbm_compat' without any changes.  To link a program with the
compatibility library, add the following two options to the `cc'
invocation: `-lgdbm -lgdbm_compat'.  The `-L' option may also be
required, depending on where `gdbm' is installed, e.g.:
     cc ... -L/usr/local/lib -lgdbm -lgdbm_compat
   Databases created and manipulated by the compatibility interfaces
consist of two different files: `FILE.dir' and `FILE.pag'.  This is
required by the POSIX specification and corresponds to the traditional
usage.  Note, however, that despite the similarity of the naming
convention, actual data stored in these files has not the same format as
in the databases created by other `dbm' or `ndbm' libraries.  In other
words, you cannot access a standard UNIX `dbm' file with GNU `dbm'!
   GNU `dbm' files are not `sparse'.  You can copy them with the usual
`cp' command and they will not expand in the copying process.
* Menu:
* ndbm::  NDBM interface functions.
* dbm::   DBM interface functions.
File: gdbm.info,  Node: ndbm,  Next: dbm,  Up: Compatibility
20.1 NDBM interface functions.
==============================
The functions below implement the POSIX `ndbm' interface:
 -- ndbm: DBM * dbm_open (char *FILE, int FLAGS, int MODE)
     Opens a database.  The FILE argument is the full name of the
     database file to be opened.  The function opens two files:
     `FILE.pag' and `FILE.dir'.  The FLAGS and MODE arguments have the
     same meaning as the second and third arguments of `open' (*note
     open a file: (open(2))open.), except that a database opened for
     write-only access opens the files for read and write access and
     the behavior of the `O_APPEND' flag is unspecified.
     The function returns a pointer to the `DBM' structure describing
     the database.  This pointer is used to refer to this database in
     all operations described below.
     Any error detected will cause a return value of `NULL' and an
     appropriate value will be stored in `gdbm_errno' (*note
     Variables::).
 -- ndbm: void dbm_close (DBM *DBF)
     Closes the database.  The DBF argument must be a pointer returned
     by an earlier call to `dbm_open'.
 -- ndbm: datum dbm_fetch (DBM *DBF, datum KEY)
     Reads a record from the database with the matching key.  The KEY
     argument supplies the key that is being looked for.
     If no matching record is found, the `dptr' member of the returned
     datum is `NULL'.  Otherwise, the `dptr' member of the returned
     datum points to the memory managed by the compatibility library.
     The application should never free it.
 -- ndbm: int dbm_store (DBM *DBF, datum KEY, datum CONTENT, int MODE)
     Writes a key/value pair to the database.  The argument DBF is a
     pointer to the `DBM' structure returned from a call to `dbm_open'.
     The KEY and CONTENT provide the values for the record key and
     content.  The MODE argument controls the behavior of `dbm_store'
     in case a matching record already exists in the database.  It can
     have one of the following two values:
    `DBM_REPLACE'
          Replace existing record with the new one.
    `DBM_INSERT'
          The existing record is left unchanged, and the function
          returns `1'.
     If no matching record exists in the database, new record will be
     inserted no matter what the value of the MODE is.
 -- ndbm: int dbm_delete (DBM *DBF, datum KEY)
     Deletes the record with the matching key from the database.  If the
     function succeeds, `0' is returned.  Otherwise, if no matching
     record is found or if an error occurs, `-1' is returned.
 -- ndbm: datum dbm_firstkey (DBM *DBF)
     Initializes iteration over the keys from the database and returns
     the first key.  Note, that the word `first' does not imply any
     specific ordering of the keys.
     If there are no records in the database, the `dptr' member of the
     returned datum is `NULL'.  Otherwise, the `dptr' member of the
     returned datum points to the memory managed by the compatibility
     library.  The application should never free it.
 -- ndbm: datum dbm_nextkey (DBM *DBF)
     Continues the iteration started by `dbm_firstkey'.  Returns the
     next key in the database.  If the iteration covered all keys in the
     database, the `dptr' member of the returned datum is `NULL'.
     Otherwise, the `dptr' member of the returned datum points to the
     memory managed by the compatibility library.  The application
     should never free it.
     The usual way of iterating over all the records in the database is:
          for (key = dbm_firstkey (dbf);
               key.ptr;
               key = dbm_nextkey (dbf))
            {
              /* do something with the key */
            }
     The loop above should not try to delete any records from the
     database, otherwise the iteration is not guaranteed to cover all
     the keys.  *Note Sequential::, for a detailed discussion of this.
 -- ndbm: int dbm_error (DBM *DBF)
     Returns the error condition of the database: `0' if no errors
     occurred so far while manipulating the database, and a non-zero
     value otherwise.
 -- ndbm: void dbm_clearerr (DBM *DBF)
     Clears the error condition of the database.
 -- ndbm: int dbm_dirfno (DBM *DBF)
     Returns the file descriptor of the `dir' file of the database.  It
     is guaranteed to be different from the descriptor returned by the
     `dbm_pagfno' function (see below).
     The application can lock this descriptor to serialize accesses to
     the database.
 -- ndbm: int dbm_pagfno (DBM *DBF)
     Returns the file descriptor of the `pag' file of the database.
     See also `dbm_dirfno'.
 -- ndbm: int dbm_rdonly (DBM *DBF)
     Returns `1' if the database DBF is open in a read-only mode and
     `0' otherwise.
File: gdbm.info,  Node: dbm,  Prev: ndbm,  Up: Compatibility
20.2 DBM interface functions.
=============================
The functions below are provided for compatibility with the old UNIX
`DBM' interface.  Only one database at a time can be manipulated using
them.
 -- dbm: int dbminit (char *FILE)
     Opens a database.  The FILE argument is the full name of the
     database file to be opened.  The function opens two files:
     `FILE.pag' and `FILE.dir'.  If any of them does not exist, the
     function fails.  It never attempts to create the files.
     The database is opened in the read-write mode, if its disk
     permissions permit.
     The application must ensure that the functions described below in
     this section are called only after a successful call to `dbminit'.
 -- dbm: int dbmclose (void)
     Closes the database opened by an earlier call to `dbminit'.
 -- dbm: datum fetch (datum KEY)
     Reads a record from the database with the matching key.  The KEY
     argument supplies the key that is being looked for.
     If no matching record is found, the `dptr' member of the returned
     datum is `NULL'.  Otherwise, the `dptr' member of the returned
     datum points to the memory managed by the compatibility library.
     The application should never free it.
 -- dbm: int store (datum KEY, datum CONTENT)
     Stores the key/value pair in the database.  If a record with the
     matching key already exists, its content will be replaced with the
     new one.
     Returns `0' on success and `-1' on error.
 -- dbm: int delete (datum KEY)
     Deletes a record with the matching key.
     If the function succeeds, `0' is returned.  Otherwise, if no
     matching record is found or if an error occurs, `-1' is returned.
 -- dbm: datum firstkey (void)
     Initializes iteration over the keys from the database and returns
     the first key.  Note, that the word `first' does not imply any
     specific ordering of the keys.
     If there are no records in the database, the `dptr' member of the
     returned datum is `NULL'.  Otherwise, the `dptr' member of the
     returned datum points to the memory managed by the compatibility
     library.  The application should never free it.
 -- dbm: datum nextkey (datum KEY)
     Continues the iteration started by a call to `firstkey'.  Returns
     the next key in the database.  If the iteration covered all keys
     in the database, the `dptr' member of the returned datum is `NULL'.
     Otherwise, the `dptr' member of the returned datum points to the
     memory managed by the compatibility library.  The application
     should never free it.
File: gdbm.info,  Node: Bugs,  Next: Resources,  Prev: Compatibility,  Up: Top
21 Problems and bugs.
*********************
If you have problems with GNU `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 `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 <bug-gdbm AT gnu.org>.
   Please include the version number of GNU `dbm' you are using.  You
can get this information by printing the variable `gdbm_version' (*note
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 authors and maintainers by e-mail:
     <phil AT cs.edu>, <downsj AT downsj.com>, <gray AT gnu.ua>
File: gdbm.info,  Node: Resources,  Next: GNU Free Documentation License,  Prev: Bugs,  Up: Top
22 Additional resources
***********************
For the latest updates and pointers to additional resources, visit
`http://www.gnu.org/software/gdbm'.
   In particular, a copy of `gdbm' documentation in various formats is
available online at `http://www.gnu.org/software/gdbm/manual'.
   Latest versions of `gdbm' can be downloaded from anonymous FTP:
`ftp://ftp.gnu.org/gnu/gdbm', or via HTTP from
`http://ftp.gnu.org/gnu/gdbm', or from any GNU mirror worldwide.  See
`http://www.gnu.org/order/ftp.html', for a list of mirrors.
   To track `gdbm' development, visit
`http://puszcza.gnu.org.ua/projects/gdbm'.
File: gdbm.info,  Node: GNU Free Documentation License,  Next: Index,  Prev: Resources,  Up: Top
Appendix A GNU Free Documentation License
*****************************************
                     Version 1.3, 3 November 2008
     Copyright (C) 2000, 2001, 2002, 2007, 2008, 2011 Free Software
     Foundation, Inc.
     `http://fsf.org/'
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.
  0. PREAMBLE
     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.
     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.
     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.
  1. APPLICABILITY AND DEFINITIONS
     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it
     can be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You
     accept the license if you copy, modify or distribute the work in a
     way requiring permission under copyright law.
     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.
     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.
     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.  If a section does not fit the above definition of
     Secondary then it is not allowed to be designated as Invariant.
     The Document may contain zero Invariant Sections.  If the Document
     does not identify any Invariant Sections then there are none.
     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.
     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup, or absence of
     markup, has been arranged to thwart or discourage subsequent
     modification by readers is not Transparent.  An image format is
     not Transparent if used for any substantial amount of text.  A
     copy that is not "Transparent" is called "Opaque".
     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML, PostScript or PDF designed for
     human modification.  Examples of transparent image formats include
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
     can be read and edited only by proprietary word processors, SGML or
     XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML, PostScript or PDF
     produced by some word processors for output purposes only.
     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.
     The "publisher" means any person or entity that distributes copies
     of the Document to the public.
     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.
     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.
  2. VERBATIM COPYING
     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.
     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.
  3. COPYING IN QUANTITY
     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.
     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.
     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a computer-network location from
     which the general network-using public has access to download
     using public-standard network protocols a complete Transparent
     copy of the Document, free of added material.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.
     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.
  4. MODIFICATIONS
     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:
       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.
       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.
       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.
       D. Preserve all the copyright notices of the Document.
       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.
       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.
       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.
       H. Include an unaltered copy of this License.
       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section Entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.
       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.
       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the
          section all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.
       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.
       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.
       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.
       O. Preserve any Warranty Disclaimers.
     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.
     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.
     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.
     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.
  5. COMBINING DOCUMENTS
     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.
     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.
     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."
  6. COLLECTIONS OF DOCUMENTS
     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.
     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.
  7. AGGREGATION WITH INDEPENDENT WORKS
     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.
     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.
  8. TRANSLATION
     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.
     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.
  9. TERMINATION
     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense, or distribute it is void,
     and will automatically terminate your rights under this License.
     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly
     and finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.
     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.
     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from
     you under this License.  If your rights have been terminated and
     not permanently reinstated, receipt of a copy of some or all of
     the same material does not give you any rights to use it.
 10. FUTURE REVISIONS OF THIS LICENSE
     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.
     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.  If the Document specifies that a proxy
     can decide which future versions of this License can be used, that
     proxy's public statement of acceptance of a version permanently
     authorizes you to choose that version for the Document.
 11. RELICENSING
     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
     World Wide Web server that publishes copyrightable works and also
     provides prominent facilities for anybody to edit those works.  A
     public wiki that anybody can edit is an example of such a server.
     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
     site means any set of copyrightable works thus published on the MMC
     site.
     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
     license published by Creative Commons Corporation, a not-for-profit
     corporation with a principal place of business in San Francisco,
     California, as well as future copyleft versions of that license
     published by that same organization.
     "Incorporate" means to publish or republish a Document, in whole or
     in part, as part of another Document.
     An MMC is "eligible for relicensing" if it is licensed under this
     License, and if all works that were first published under this
     License somewhere other than this MMC, and subsequently
     incorporated in whole or in part into the MMC, (1) had no cover
     texts or invariant sections, and (2) were thus incorporated prior
     to November 1, 2008.
     The operator of an MMC Site may republish an MMC contained in the
     site under CC-BY-SA on the same site at any time before August 1,
     2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents
====================================================
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:
       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.3
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.
   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:
         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.
   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.
File: gdbm.info,  Node: Index,  Prev: GNU Free Documentation License,  Up: Top
Index
*****
[index]
* Menu:
* -g, testgdbm option:                   testgdbm.            (line   9)
* -n, testgdbm option:                   testgdbm.            (line  19)
* -r, testgdbm option:                   testgdbm.            (line  16)
* 1:                                     shell.               (line 118)
* <:                                     shell.               (line 125)
* ?:                                     shell.               (line 200)
* _GDBM_MAX_ERRNO:                       Variables.           (line  28)
* _GDBM_MIN_ERRNO:                       Variables.           (line  25)
* A:                                     shell.               (line 143)
* a:                                     shell.               (line 142)
* avail:                                 shell.               (line 141)
* B:                                     shell.               (line 148)
* b:                                     shell.               (line 147)
* bucket:                                shell.               (line 146)
* C:                                     shell.               (line 153)
* c:                                     shell.               (line  63)
* ca:                                    shell.               (line 172)
* cache:                                 shell.               (line 171)
* close-on-exec:                         Open.                (line  48)
* closing database:                      Close.               (line   6)
* co:                                    shell.               (line  62)
* command line options, testgdbm:        invocation.          (line   6)
* compatibility layer:                   Compatibility.       (line   6)
* count:                                 shell.               (line  61)
* creating a database, testgdbm:         testgdbm.            (line  19)
* cu:                                    shell.               (line 152)
* current:                               shell.               (line 151)
* D:                                     shell.               (line 158)
* d:                                     shell.               (line  68)
* da:                                    shell.               (line 191)
* data-zero:                             shell.               (line 190)
* database options:                      Options.             (line   6)
* database reorganization:               Reorganization.      (line   6)
* database synchronization:              Sync.                (line   6)
* database, closing:                     Close.               (line   6)
* database, opening or creating:         Open.                (line   6)
* DBM functions:                         dbm.                 (line   6)
* dbm.h:                                 Compatibility.       (line  11)
* dbm_clearerr:                          ndbm.                (line  98)
* dbm_close:                             ndbm.                (line  26)
* dbm_delete:                            ndbm.                (line  57)
* dbm_dirfno:                            ndbm.                (line 101)
* dbm_error:                             ndbm.                (line  93)
* dbm_fetch:                             ndbm.                (line  30)
* dbm_firstkey:                          ndbm.                (line  62)
* DBM_INSERT:                            ndbm.                (line  49)
* dbm_nextkey:                           ndbm.                (line  72)
* dbm_open:                              ndbm.                (line   9)
* dbm_pagfno:                            ndbm.                (line 109)
* dbm_rdonly:                            ndbm.                (line 113)
* DBM_REPLACE:                           ndbm.                (line  46)
* dbm_store:                             ndbm.                (line  39)
* dbmclose:                              dbm.                 (line  23)
* dbminit:                               dbm.                 (line  11)
* de:                                    shell.               (line  67)
* default database, testgdbm:            testgdbm.            (line   9)
* delete <1>:                            dbm.                 (line  42)
* delete:                                shell.               (line  66)
* deleting records:                      Delete.              (line   6)
* deletion in iteration loops:           Sequential.          (line  56)
* di:                                    shell.               (line 157)
* dir:                                   shell.               (line 156)
* dir file:                              Compatibility.       (line  22)
* e:                                     shell.               (line  72)
* error codes:                           Error codes.         (line   6)
* error strings:                         Errors.              (line   6)
* export <1>:                            shell.               (line  71)
* export:                                Flat files.          (line   6)
* F:                                     shell.               (line 163)
* f:                                     shell.               (line  82)
* fe:                                    shell.               (line  81)
* fetch <1>:                             dbm.                 (line  26)
* fetch:                                 shell.               (line  80)
* fetching records:                      Fetch.               (line   6)
* fi:                                    shell.               (line 117)
* first:                                 shell.               (line 116)
* firstkey:                              dbm.                 (line  48)
* Flat file format:                      Flat files.          (line   6)
* GDBM_BAD_FILE_OFFSET:                  Error codes.         (line 117)
* GDBM_BAD_MAGIC_NUMBER:                 Error codes.         (line  48)
* GDBM_BAD_OPEN_FLAGS:                   Error codes.         (line 121)
* GDBM_BLOCK_SIZE_ERROR:                 Error codes.         (line  15)
* GDBM_BYTE_SWAPPED:                     Error codes.         (line 112)
* GDBM_CACHESIZE:                        Options.             (line  30)
* GDBM_CANNOT_REPLACE:                   Error codes.         (line  92)
* GDBM_CANT_BE_READER:                   Error codes.         (line  56)
* GDBM_CANT_BE_WRITER:                   Error codes.         (line  61)
* GDBM_CENTFREE:                         Options.             (line  78)
* GDBM_CLOEXEC:                          Open.                (line  48)
* gdbm_close:                            Close.               (line  10)
* GDBM_COALESCEBLKS:                     Options.             (line  92)
* gdbm_delete:                           Delete.              (line   9)
* gdbm_delete and sequential access:     Sequential.          (line  56)
* GDBM_EMPTY_DATABASE:                   Error codes.         (line  52)
* gdbm_errlist:                          Variables.           (line  17)
* gdbm_errno:                            Variables.           (line   9)
* gdbm_exists:                           Fetch.               (line  37)
* gdbm_export:                           Flat files.          (line  25)
* GDBM_FASTMODE:                         Options.             (line  52)
* gdbm_fdesc:                            Locking.             (line  14)
* gdbm_fetch:                            Fetch.               (line   7)
* GDBM_FILE_EOF:                         Error codes.         (line 132)
* GDBM_FILE_OPEN_ERROR:                  Error codes.         (line  19)
* GDBM_FILE_READ_ERROR:                  Error codes.         (line  41)
* GDBM_FILE_SEEK_ERROR:                  Error codes.         (line  34)
* GDBM_FILE_STAT_ERROR:                  Error codes.         (line 125)
* GDBM_FILE_WRITE_ERROR:                 Error codes.         (line  27)
* gdbm_firstkey:                         Sequential.          (line  14)
* GDBM_GETCACHESIZE:                     Options.             (line  40)
* GDBM_GETCOALESCEBLKS:                  Options.             (line 104)
* GDBM_GETDBNAME:                        Options.             (line 127)
* GDBM_GETFLAGS:                         Options.             (line  44)
* GDBM_GETMAXMAPSIZE:                    Options.             (line 114)
* GDBM_GETMMAP:                          Options.             (line 123)
* GDBM_GETSYNCMODE:                      Options.             (line  74)
* GDBM_ILLEGAL_DATA:                     Error codes.         (line  98)
* gdbm_import:                           Flat files.          (line  46)
* GDBM_INSERT:                           Store.               (line  23)
* GDBM_ITEM_NOT_FOUND:                   Error codes.         (line  83)
* GDBM_MALLOC_ERROR:                     Error codes.         (line  12)
* GDBM_NEWDB <1>:                        Flat files.          (line  35)
* GDBM_NEWDB:                            Open.                (line  28)
* gdbm_nextkey:                          Sequential.          (line  24)
* GDBM_NO_ERROR:                         Error codes.         (line   9)
* GDBM_NOLOCK <1>:                       Locking.             (line   6)
* GDBM_NOLOCK:                           Open.                (line  40)
* GDBM_NOMMAP:                           Open.                (line  40)
* gdbm_open:                             Open.                (line   9)
* GDBM_OPT_ALREADY_SET:                  Error codes.         (line 102)
* GDBM_OPT_ILLEGAL:                      Error codes.         (line 107)
* GDBM_READER:                           Open.                (line  28)
* GDBM_READER_CANT_DELETE:               Error codes.         (line  65)
* GDBM_READER_CANT_REORGANIZE:           Error codes.         (line  75)
* GDBM_READER_CANT_STORE:                Error codes.         (line  70)
* gdbm_reorganize:                       Reorganization.      (line   9)
* GDBM_REORGANIZE_FAILED:                Error codes.         (line  88)
* GDBM_REPLACE:                          Store.               (line  23)
* GDBM_SETCACHESIZE:                     Options.             (line  30)
* GDBM_SETCENTFREE:                      Options.             (line  78)
* GDBM_SETCOALESCEBLKS:                  Options.             (line  92)
* GDBM_SETMAXMAPSIZE:                    Options.             (line 108)
* GDBM_SETMMAP:                          Options.             (line 118)
* gdbm_setopt:                           Options.             (line  11)
* GDBM_SETSYNCMODE:                      Options.             (line  61)
* gdbm_store:                            Store.               (line   8)
* gdbm_strerror:                         Errors.              (line   9)
* gdbm_sync:                             Sync.                (line  15)
* GDBM_SYNC <1>:                         Sync.                (line   6)
* GDBM_SYNC:                             Open.                (line  40)
* GDBM_SYNCMODE:                         Options.             (line  61)
* GDBM_UNKNOWN_UPDATE:                   Error codes.         (line  80)
* gdbm_version:                          Variables.           (line  31)
* gdbm_version_cmp:                      Variables.           (line  61)
* GDBM_VERSION_MAJOR:                    Variables.           (line  45)
* GDBM_VERSION_MINOR:                    Variables.           (line  48)
* gdbm_version_number:                   Variables.           (line  34)
* GDBM_VERSION_PATCH:                    Variables.           (line  51)
* GDBM_WRCREAT <1>:                      Flat files.          (line  35)
* GDBM_WRCREAT:                          Open.                (line  28)
* GDBM_WRITER:                           Open.                (line  28)
* gdbmexport:                            gdbmexport.          (line   6)
* H:                                     shell.               (line 168)
* ha:                                    shell.               (line 167)
* hash:                                  shell.               (line 166)
* hea:                                   shell.               (line 162)
* header:                                shell.               (line 161)
* hel:                                   shell.               (line 199)
* help:                                  shell.               (line 198)
* i:                                     shell.               (line  86)
* import <1>:                            shell.               (line  85)
* import:                                Flat files.          (line   6)
* interactive mode, testgdbm:            shell.               (line   6)
* iterating over records:                Sequential.          (line   6)
* iteration and gdbm_delete:             Sequential.          (line  56)
* iteration loop:                        Sequential.          (line  36)
* iteration loop, using NDBM:            ndbm.                (line  79)
* junk.gdbm:                             testgdbm.            (line   9)
* K:                                     shell.               (line 173)
* k:                                     shell.               (line 136)
* key-zero:                              shell.               (line 135)
* l:                                     shell.               (line  92)
* libgdbm_compat:                        Compatibility.       (line  11)
* list:                                  shell.               (line  91)
* locking:                               Locking.             (line   6)
* looking up records:                    Fetch.               (line   6)
* n:                                     shell.               (line  96)
* NDBM functions:                        ndbm.                (line   6)
* ndbm.h:                                Compatibility.       (line  11)
* next:                                  shell.               (line  95)
* nextkey:                               dbm.                 (line  58)
* opening the database:                  Open.                (line   6)
* options, database:                     Options.             (line   6)
* pag file:                              Compatibility.       (line  22)
* PAGER:                                 shell.               (line  45)
* pager, testgdbm:                       shell.               (line  45)
* q:                                     shell.               (line 107)
* quit:                                  shell.               (line 106)
* r:                                     shell.               (line 132)
* rea:                                   shell.               (line 124)
* read:                                  shell.               (line 123)
* read-only mode, testgdbm:              testgdbm.            (line  16)
* record, deleting:                      Delete.              (line   6)
* record, fetching:                      Fetch.               (line   6)
* records, iterating over:               Sequential.          (line   6)
* records, storing:                      Store.               (line   6)
* records, testing existence:            Fetch.               (line  34)
* reo:                                   shell.               (line 131)
* reorganization, database:              Reorganization.      (line   6)
* reorganize:                            shell.               (line 130)
* S:                                     shell.               (line 178)
* s:                                     shell.               (line 112)
* sequential access:                     Sequential.          (line   6)
* sequential access, using NDBM:         ndbm.                (line  79)
* sta:                                   shell.               (line 177)
* status:                                shell.               (line 176)
* sto:                                   shell.               (line 111)
* store <1>:                             dbm.                 (line  35)
* store:                                 shell.               (line 110)
* storing records:                       Store.               (line   6)
* synchronization, database:             Sync.                (line   6)
* testgdbm:                              testgdbm.            (line   6)
* v:                                     shell.               (line 187)
* version:                               shell.               (line 186)
* version number:                        Variables.           (line  30)
* Z:                                     shell.               (line 192)
* z:                                     shell.               (line 137)