libgdbm -- Library

Library for GNU DBM functions
/usr/lib/libgdbm.a

Archive  libgdbm  contains   GNU  data-base  management  (DBM)  library  of
functions.  These  functions implement a  version of the  standard UNIX DBM
functions, which let you create and manipulate a simple hashed data base.

What is a Hashed Data Base?

A hashed data base consists of a set of records.  Each record, in turn, has
two elements:  a key  that uniquely  identifies the record,  and a  mass of
data. For example, if you were creating a data base of the persons who have
accounts  on your  system, the  key  would be  the user's  login identifier
(because that must be unique), and the data could be the user's full name.

When the GDBM routines add a record to a data base, they do the following:

1. They write the record within a file.

2. They note the size of the record, and its offset within the file.

3. They ``hash'' each key into a  unique number, then write that hash index
   within a  separate index  file, along  with the offset  and size  of its
   associated record.  (For a further explanation of hashing and an example
   implementation, see the Lexicon entry for strtoul().)

By indexing  a text file in  this manner, a program can  find a record much
more quickly  than it could  by simply reading  the file from  beginning to
end.  For example, when you mail a message via the mail program smail, that
program reads  a set of aliases  to ensure that the message  is sent to the
right person.  If the aliases were kept in a text file, smail would have to
open  the file  and read  its entire  contents every time  you sent  a mail
message; and on a busy system  that has a large number of aliases, this can
cause a noticeable delay in  dispatching a message.  By keeping its aliases
within a hashed  index data base, smail greatly reduces  the time needed to
look up an alias, and so speeds the dispatching of your mail.

Sets of Routines

Library libgdbm contains three sets of functions.

-> The ``GNU DBM'' (GDBM) routines.  Each of these functions has the prefix
   gdbm_, and is declared in the header file <gdbm.h>.

-> DBM routines.  These  re-implement the original UNIX DBM routines.  They
   are declared in header file <dbm.h>.

-> ``New DBM'' (NDBM) routines.  These re-implement the extended version of
   the UNIX DBM routines.  Each of these functions has the prefix dbm_, and
   is declared in the header file <ndbm.h>.

Each  set  implements  a  hashed  data  base,  but  each  has  a  different
provenance,  and somewhat  different properties  and syntax.   This library
includes all three sets to support the widest possible range of third-party
software.  If you are writing new software, however, we urge you to use the
GDBM routines.

Note that you cannot mix routines  from the three sets -- you must pick one
set, and stick  with it.  Please note, too, that  although this library re-
creates  the  DBM and  NDBM  sets  of routines  with  regard their  calling
conventions and return  values, internally these re-creations work somewhat
different  than  the  UNIX  originals;  thus,  you cannot  expect  programs
compiled with these routines to read  binary data bases created by the UNIX
originals.

GDBM Routines

The following summarizes the GDBM routines:

gdbm_close()...Close a GDBM data base
gdbm_delete()..Delete a record from a GDBM data base
gdbm_exists()..Check whether a GDBM data base contains a given record
gdbm_fetch()...Retrieve a record from a GDBM data base
gdbm_firstkey()Return the first record from a GDBM data base
gdbm_nextkey().Return the next record from a GDBM data base
gdbm_open()....Open a GDBM data base
gdbm_reorganize()Reorganize a GDBM data base
gdbm_setopt()..Set GDBM options
gdbm_store()...Add records to a GDBM data base
gdbm_strerror()Translate a GDBM error code into text
gdbm_sync()....Flush buffered GDBM data into its data base

As noted above, these  routines are declared in header file <gdbm.h>.
This header  file also defines  two structures that the  GDBM routines use.
The first, datum, defines the structure  of a data element, either a key or
its associated data set:

    typedef struct {
        char *dptr;
        int dsize;
    } datum;

This structure lets you have a  key and a data element of unlimited length.
This is  a departure  from the  orthodox UNIX DBM  functions, in  which the
sizes of the key and the datum are both static.

The  other  structure,  GDBM_FILE,  holds  the  information that  the  GDBM
routines use to access a GDBM data base:

    typedef struct {int dummy[10];} *GDBM_FILE;

Error codes are written into global variable gdbm_errno, and are defined in
header file <gdbmerrno.h>.

DBM Routines

The following summarizes the DBM routines:

dbmclose().....Close a DBM data base
dbminit()......Open a DBM data base
delete().......Delete a record from a DBM data base
fetch()........Fetch a record from a DBM data base
firstkey().....Retrieve the first record from a DBM data base
nextkey()......Retrieve the next record from a DBM data base
store()........Write a record into a DBM data base

As noted  above, these routines are declared  in header file <dbm.h>.
It also defines  the structure datum, which holds a  data element, either a
key or its associated data set:

    typedef struct {
        char *dptr;
        int dsize;
    } datum;

The sizes  of the key and  its datum together cannot  exceed BSIZE bytes --
that is,  the size of  one file-system block.   BSIZE is defined  in header
file <sys/buf.h>; at present, it equals 512 bytes.

Please note  that the function  dbmclose() is non-standard.   Programs that
use it cannot be recompiled on an orthodox UNIX system.

NDBM Routines

The following summarizes the NDBM routines:

dbm_close()....Close an NDBM data base
dbm_delete()...Delete records from an NDBM data base
dbm_dirfno()...Return the file descriptor for an NDBM .dir file
dbm_fetch()....Fetch a record from an NDBM data base
dbm_firstkey().Retrieve the first key from an NDBM data base
dbm_nextkey()..Retrieve the next key from an NDBM data base
dbm_open().....Open an NDBM data base
dbm_pagfno()...Return the file descriptor for an NDBM .pag file
dbm_rdonly()...Set an NDBM data base into read-only mode
dbm_store()....Store a record into an NDBM data base

As noted above, these  routines are declared in header file <ndbm.h>.
This header  file also defines  two structures that the  NDBM routines use.
The first, datum, defines the structure  of a data element, either a key or
its associated data set:

    typedef struct {
        char *dptr;
        int dsize;
    } datum;

This structure lets you have a key and a data element of unlimited length.

The other structure, DBM, holds  the information that the NDBM routines use
to access a NDBM data base:

    typedef struct {int dummy[10];} DBM;

See Also

libraries,
Programming COHERENT

Notes

libgdbm was written by Philip A. Nelson of the Computer Science Department,
Western Washington University,  Bellingham (phil@cs.wwu.edu).  This Lexicon
entry is based on an info  file written by Pierre Gaumond.  libgdbm and its
documentation  are   copyright  ©  1989-1993  by   the  Free  Software
Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual
provided the  copyright notice and this permission  notice are preserved on
all copies.

Permission  is granted  to copy  and distribute  modified versions  of this
manual under  the conditions for  verbatim copying, provided  also that the
entire  resulting  derived  work  is  distributed  under  the  terms  of  a
permission notice identical to this one.

For a full statement of the rights and obligations attached to libgdbm, see
the file COPYING that accompanies the source code to this library.

© 2012 by Stephen A. Ness