33.6. 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 :OPTIONS :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

:OPTIONS is a combination of

:FAST
:SYNC
:NOLOCK
:NOMMAP
:CLOEXEC
:BSEXACT

:MODE is the numeric file permission mode (cf. open), use POSIX:CONVERT-MODE to extract it from a list of keywords.

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 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-PATH db)

Return the original filename passed to .

(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: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-OPT db :DEFAULT-VALUE-TYPE)))
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-OPT db :DEFAULT-KEY-TYPE)))
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-OPT db :DEFAULT-KEY-TYPE)))
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-OPT db option)
(SETF (GDBM:GDBM-OPT db option) value)

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

:FLAGS
Retrieve the :READ-WRITE and :OPTIONS passed to GDBM:GDBM-OPEN (read-only).
:CACHESIZE
Retrieve and set the size of the internal bucket cache.
:MAXMAPSIZE
Retrieve and set the maximum size of a memory mapped region.
:BLOCKSIZE
Retrieve the block size in bytes (read-only).
:MMAP
Retrieve and enable or disable memory mapping mode.
:SYNCMODE
Retrieve or set file system synchronization mode.
:CENTFREE
Retrieve or set central free block pool handling.
:COALESCEBLKS
Retrieve or set free block merging.
:DBNAME
Retrieve the namestring of the database (read-only).
:DEFAULT-VALUE-TYPE
:DEFAULT-KEY-TYPE
The default data conversion types, see GDBM:GDBM-OPEN.
(GDBM:GDBM-FILE-SIZE db)
Return the underlying file size using lseek.
(GDBM:GDBM-COUNT db)
Return the number of records in the database.
(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.49.93+Last modified: 2018-02-19