33.5. GDBM - The GNU database manager

This is an interface to the GNU DataBase Manager, which extends the standard UNIX <ndbm.h>.

When this module is present, *FEATURES* contains the symbol :GDBM.

See modules/gdbm/test.tst for sample usage.

GDBM module API

(GDBM:GDBM-VERSION)

Return the version string.

(GDBM:GDBM-OPEN filename &KEY :BLOCKSIZE :READ-WRITE :OPTION :MODE :DEFAULT-KEY-TYPE :DEFAULT-VALUE-TYPE)

Open filename database file. The return value is a GDBM structure. :READ-WRITE can have one of following values:

:READER
:WRITER
:WRCREAT
:NEWDB

and :OPTION is one of

:SYNC
:NOLOCK
:FAST

CLISP can store and retrieve values of the following types:

STRING
VECTOR (meaning anything that can be COERCEd to (VECTOR (UNSIGNED-BYTE 8)))
EXT:32BIT-VECTOR (meaning (VECTOR (UNSIGNED-BYTE 32)))
INTEGER
SINGLE-FLOAT
DOUBLE-FLOAT

and :DEFAULT-KEY-TYPE and :DEFAULT-VALUE-TYPE-TYPE should be one of those. If not specified (or NIL), the :TYPE argument is required in the access functions below.

If filename is actually an existing GDBM structure, then it is re-opened (if it has been closed), and returned as is.

The return value is EXT:FINALIZEd with GDBM-CLOSE.

(GDBM:GDBM-DEFAULT-KEY-TYPE db)
(GDBM:GDBM-DEFAULT-VALUE-TYPE db)

Return the default data conversion types.

(GDBM:GDBM-CLOSE db)
Close the database.
(GDBM:GDBM-OPEN-P db)

Check whether db has been already closed.

Warning

Only the above functions accept closed databases, the following functions SIGNALs an ERROR when passed a closed database.

(GDBM:GDBM-STORE db key contents &KEY :FLAG)

db is the GDBM structure returned by GDBM-OPEN. key is the key datum. contents is the data to be associated with the key. :FLAG can have one of following values:

:INSERT
:REPLACE

(GDBM:GDBM-FETCH db key &KEY (TYPE (GDBM:GDBM-DEFAULT-VALUE-TYPE db)))
Search the database. The :TYPE argument specifies the return type.
(GDBM:GDBM-DELETE db key)
Delete key and its contents.
(GDBM:GDBM-EXISTS db key)
Search data without retrieving it.
(GDBM:GDBM-FIRSTKEY db &KEY (TYPE (GDBM:GDBM-DEFAULT-KEY-TYPE db)))
Return the key of the first entry, as :TYPE. If the database has no entries, the return value is NIL.
(GDBM:GDBM-NEXTKEY db key &KEY (TYPE (GDBM:GDBM-DEFAULT-KEY-TYPE db)))
Return the key that follows key, as :TYPE, or NIL if there are no further entries.
(GDBM:GDBM-REORGANIZE db)
Reorganize the database.
(GDBM:GDBM-SYNC db)
Syncronize the in-memory state of the database to the disk file.
(GDBM:GDBM-SETOPT db option value)

Set options on an already open database. option is one of following:

:CACHESIZE
set the size of the internal bucket cache. (default is 100)
:FASTMODE
T or NIL (obsolete)
:SYNCMODE
T or NIL
:CENTFREE
T or NIL
:COALESCEBLKS
T or NIL
:DEFAULT-VALUE-TYPE
:DEFAULT-KEY-TYPE
see GDBM-OPEN
(GDBM:GDBM-FILE-SIZE db)
Return the underlying file size using lseek.
(GDBM:DO-DB (key db &REST options) &BODY body)
Iterate over the database keys, options are passed to GDBM-FIRSTKEY and GDBM-NEXTKEY. body is passed to LOOP, so you can use all the standard loop contructs, e.g., (do-db (k db) :collect (list k (gdbm-fetch k))) will convert the database to an association list.
(GDBM:WITH-OPEN-DB (db filename &REST options) &BODY body)
Open the filename, execute the body, close the database.

These notes document CLISP version 2.49Last modified: 2010-07-07