COHERENT manpages
This page displays the COHERENT manpage for libgdbm [Library for GNU DBM functions].
List of available manpages
Index
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.