![[CLISP home]](clisp.png){kind=small} | ![[Support CLISP]](https://sourceforge.net/images/project-support.jpg){kind=small} |
This interface to Berkeley DB from Sleepycat Software/Oracle exports most functions in the official C API. Supported versions:
| 4.2 |
| 4.3 |
| 4.4 |
| 4.5 |
| 4.6 |
| 4.7 |
| 4.8 |
| 5.3 |
When this module is present, *FEATURES* contains the
symbol :BERKELEY-DB.
See modules/berkeley-db/test.tst
for sample usage.
The symbol names do evolve with new Berkeley DB releases.
E.g., version 4.3 introduced DB_DSYNC_LOG which
was renamed to DB_LOG_DSYNC in version 4.7.
The corresponding Lisp symbol was renamed from
:DSYNC-LOG to :LOG-DSYNC
when support for version 4.7 was added.
This means that we always use Lisp names which correspond to the
C names in the latest Berkeley DB release,
even though we keep suport for older releases.
This is convenient because the online documentation to which this
manual refers documents the latest Berkeley DB release.
Thie module exports the following opaque STRUCTURE-OBJECT types:
They contain the internal handle (a FFI:FOREIGN-POINTER), the LIST
of parents, and the LIST of dependents.
CLOSE will close (or commit, in the case of a
transaction, or
put, in the case of a lock)
the Berkeley-DB handle objects. The garbage-collector will also call CLOSE.
Closing an object will CLOSE all its dependents and remove the object
itself from the dependents lists of its parents (but see
BDB:LOCK-CLOSE).
(BDB:DB-VERSION &OPTIONAL
subsystems-too)Return version information as multiple values:
STRING
(from db_version)FIXNUM)FIXNUM)FIXNUM)When the optional argument is non-NIL, returns the
association list of the subsystem versions as the 5th value.
(BDB:DBE-CREATE &KEY
PASSWORD ENCRYPT)db_env_create),
possibly using encryption with password
(DB_ENV->set_encrypt).
(BDB:DBE-CLOSE dbe)DB_ENV->close).
You can also call CLOSE.(BDB:DBE-MESSAGES dbe)(BDB:DBREMOVE dbe file
database &KEY TRANSACTION AUTO-COMMIT)DB_ENV->dbremove).
(BDB:DBREMOVE dbe file
database newname &KEY TRANSACTION AUTO-COMMIT)DB_ENV->dbrename).
(BDB:DBE-OPEN dbe &KEY
FLAGS HOME JOIN INIT-CDB INIT-LOCK INIT-LOG INIT-MPOOL INIT-TXN
RECOVER RECOVER-FATAL USE-ENVIRON USE-ENVIRON-ROOT CREATE
LOCKDOWN PRIVATE SYSTEM-MEM THREAD MODE)DB_ENV->open).
:FLAGS may be the value of a previous call
to (BDB:DBE-GET-OPTIONS dbe :OPEN).
(BDB:DBE-REMOVE dbe &KEY
HOME FORCE USE-ENVIRON USE-ENVIRON-ROOT)DB_ENV->remove).
(BDB:WITH-DBE (var &KEY
create options) &BODY body)body, close it.
create is a list of options to be passed to BDB:DBE-CREATE,
options is a list of options to be passed to BDB:DBE-SET-OPTIONS.
(BDB:DBE-SET-OPTIONS dbe
&KEY MSGFILE ERRFILE ERRPFX PASSWORD ENCRYPT LOCK-TIMEOUT TXN-TIMEOUT
SHM-KEY TAS-SPINS TX-TIMESTAMP TX-MAX DATA-DIR TMP-DIR
INTERMEDIATE-DIR-MODE LG-BSIZE LG-DIR
LG-MAX LG-REGIONMAX NCACHE CACHESIZE CACHE LK-CONFLICTS LK-DETECT
LK-MAX-LOCKERS LK-MAX-LOCKS LK-MAX-OBJECTS
LOG-DIRECT LOG-DSYNC LOG-AUTO-REMOVE LOG-IN-MEMORY LOG-ZERO
AUTO-COMMIT CDB-ALLDB DIRECT-DB NOLOCKING NOMMAP NOPANIC
OVERWRITE PANIC-ENVIRONMENT REGION-INIT TXN-NOSYNC TXN-WRITE-NOSYNC YIELDCPU
VERB-CHKPOINT VERB-DEADLOCK VERB-RECOVERY VERB-REPLICATION VERB-WAITSFOR
VERBOSE)Set some environment options using
(BDB:DBE-GET-OPTIONS dbe
&OPTIONAL what)Retrieve some environment options.
Values of what
NILLIST
:TX-TIMESTAMPDB_ENV->get_tx_timestamp)
:TX-MAXDB_ENV->set_tx_max)
:DATA-DIRDB_ENV->get_data_dir)
:TMP-DIRDB_ENV->get_tmp_dir).
May be NIL.:INTERMEDIATE-DIR-MODEDB_ENV->get_intermediate_dir_mode).
:VERBOSELIST of verbosity settings
(DB_ENV->get_verbose).
:AUTO-COMMIT:CDB-ALLDB:DIRECT-DB:LOG-DIRECT:LOG-DSYNC:LOG-AUTO-REMOVE:LOG-IN-MEMORY:LOG-ZERO:NOLOCKING:NOMMAP:NOPANIC:OVERWRITE:PANIC-ENVIRONMENT:REGION-INIT:TXN-NOSYNC:TXN-WRITE-NOSYNC:YIELDCPU:VERB-CHKPOINT:VERB-DEADLOCK:VERB-RECOVERY:VERB-REPLICATION:VERB-WAITSFORBOOLEAN indicator of whether this
option is set or not
(DB_ENV->get_verbose,
DB_ENV->get_flags, and
DB_ENV->log_get_config).
:LG-BSIZEDB_ENV->get_lg_bsize).
:LG-DIRDB_ENV->get_lg_dir).
:LG-MAXDB_ENV->get_lg_max).
:LG-REGIONMAXDB_ENV->get_lg_regionmax).
:NCACHE:CACHESIZE:CACHEDB_ENV->get_cachesize).
:LK-CONFLICTSDB_ENV->get_lk_conflicts).
:LK-DETECTDB_ENV->get_lk_detect).
:LK-MAX-LOCKERSDB_ENV->get_lk_max_lockers).
:LK-MAX-LOCKSDB_ENV->get_lk_max_locks).
:LK-MAX-OBJECTSDB_ENV->get_lk_max_objects).
:TAS-SPINSDB_ENV->get_tas_spins).
:SHM-KEYDB_ENV->get_shm_key).
:LOCK-TIMEOUT:TXN-TIMEOUTDB_ENV->get_timeout).
:ENCRYPTDB_ENV->get_encrypt_flags).
:ERRFILENIL
(DB_ENV->get_errfile).
:MSGFILENIL
(DB_ENV->get_msgfile).
:ERRPFXSTRING or NIL
(DB_ENV->get_errpfx).
:DB-GID-SIZELENGTH of the globally unique
(VECTOR (UNSIGNED-BYTE 8)) which must be passed to
DB_TXN->prepare.
:HOMEDB_ENV->get_home).
:OPENLIST of flags passed to BDB:DBE-OPEN
(DB_ENV->get_open_flags).
:CACHEDB_ENV->get_cachesize).
(BDB:DB-CREATE dbe)db_create).
(BDB:DB-CLOSE db &KEY NOSYNC)DB->close).
You can also call CLOSE.(BDB:DB-DEL dbe key &KEY
TRANSACTION AUTO-COMMIT)DB->del).
(BDB:DB-FD db)DB->fd).
(BDB:DB-GET db key &KEY ACTION AUTO-COMMIT
DEGREE-2 DIRTY-READ MULTIPLE RMW TRANSACTION (ERROR T))Get items from a database
(DB->get).
If :ERROR is NIL and the record is not found, no ERROR is SIGNALed,
instead :NOTFOUND is returned.
:ACTION should be one of
:CONSUME | :GET-BOTH |
:CONSUME-WAIT | :SET-RECNO |
(BDB:DB-PUT db key val
&KEY AUTO-COMMIT ACTION TRANSACTION)Store items into a database
(DB->put).
:ACTION should be one of
:APPEND | :NODUPDATA | :NOOVERWRITE |
(BDB:DB-STAT db &KEY FAST-STAT
TRANSACTION)DB->get_byteswapped,
DB->get_type,
DB->stat).
(BDB:DB-OPEN db file &KEY
DATABASE TYPE MODE FLAGS CREATE DIRTY-READ EXCL NOMMAP RDONLY
THREAD TRUNCATE AUTO-COMMIT TRANSACTION)Open a database (DB->open).
:TYPE should be one of
:BTREE | :RECNO |
:HASH | :UNKNOWN (default) |
:QUEUE |
:FLAGS may be the value of a previous call
to (
BDB:DB-GET-OPTIONS db :OPEN)
(BDB:DB-SYNC db)DB->sync).
(BDB:DB-TRUNCATE db &KEY
TRANSACTION AUTO-COMMIT)DB->truncate).
(BDB:DB-UPGRADE db file
&KEY DUPSORT)DB->upgrade).
(BDB:DB-RENAME db file database newname)DB->rename).
(BDB:DB-REMOVE db file database)DB->remove).
(BDB:DB-JOIN db cursor-sequence
&KEY JOIN-NOSORT)DB->join).
(BDB:DB-KEY-RANGE db key
&KEY TRANSACTION)DB->key_range).
The underlying database must be of type Btree.
(BDB:DB-VERIFY db file &KEY
DATABASE SALVAGE AGGRESSIVE PRINTABLE NOORDERCHK)DB->verify).
:SALVAGE, if supplied, should be the output
file name. :DATABASE, if supplied,
will force DB_ORDERCHKONLY.
(BDB:WITH-DB (var dbe file
&KEY create options open) &BODY body)body, close it.
create is a list of options to be passed to BDB:DB-CREATE,
options is a list of options to be passed to BDB:DB-SET-OPTIONS,
open is a list of options to be passed to BDB:DB-OPEN.
(BDB:DB-COMPACT db &KEY
TRANSACTION START STOP FREE FILL TIMEOUT PAGES TYPE)DB->compact.
:FREE is either :LIST-ONLY
or :SPACE.
:FILL, :TIMEOUT,
:PAGES are passed in DB_COMPACT.
:TYPE is how the end is returned.
The second return value is a BDB:DB-COMPACT.
(BDB:DB-SET-OPTIONS db
&KEY ERRFILE MSGFILE ERRPFX PASSWORD ENCRYPTION NCACHE CACHESIZE CACHE
LORDER PAGESIZE BT-MINKEY H-FFACTOR H-NELEM Q-EXTENTSIZE
RE-DELIM RE-LEN RE-PAD RE-SOURCE
CHKSUM ENCRYPT TXN-NOT-DURABLE DUP DUPSORT INORDER RECNUM REVSPLITOFF
RENUMBER SNAPSHOT)Set some database options using
(BDB:DB-GET-OPTIONS db
&OPTIONAL what)Retrieve some database options.
Values of what
NILLIST
:FLAGSDB_ENV->get_flags).
:CHKSUM:ENCRYPT:TXN-NOT-DURABLE:DUP:DUPSORT:INORDER:RECNUM:REVSPLITOFF:RENUMBER:SNAPSHOTBOOLEAN indicator of whether this
option is set or not
(DB_ENV->get_verbose and
DB_ENV->get_flags).
:CACHEDB->get_cachesize or
DB_ENV->get_cachesize if the
database was created within an environment).
:ENCRYPTIONDB_ENV->get_encrypt_flags).
:ERRFILENIL
(DB_ENV->get_errfile).
:MSGFILENIL
(DB_ENV->get_msgfile).
:ERRPFXSTRING or NIL
(DB_ENV->get_errpfx).
:PAGESIZEDB->get_pagesize).
:BT-MINKEY:BTREE leaf page
underlying source file
(DB->get_bt_minkey).
:H-FFACTOR:HASH table
(DB->get_h_ffactor).
:H-NELEM:HASH table
(DB->get_h_nelem).
:Q-EXTENTSIZE:QUEUE database
(DB->get_q_extentsize).
:RE-DELIM:RECNO databases
(DB->get_re_delim).
:RE-LENDB->get_re_len).
:RE-PADDB->get_re_pad).
:RE-SOURCE:RECNO databases
(DB->get_re_source).
:LORDERDB->get_lorder).
:DBNAMEDB->get_dbname)
:TRANSACTIONALDB->get_transactional).
:OPENBDB:DB-OPEN
(DB->get_open_flags).
Once you call a method for one type of access method,
the handle can only be used for that type.
The methods DB->get_re_delim
and DB->get_re_source are for
a :RECNO database so you cannot call them
(by passing :RE-DELIM
or :RE-SOURCE to this function)
and then use the database handle to open a database of different type
(e.g., :QUEUE).
(BDB:MAKE-DBC db &KEY
DEGREE-2 DIRTY-READ WRITECURSOR TRANSACTION)DB->cursor).
(BDB:DBC-CLOSE cursor)DBCursor->close).
You can also call CLOSE.(BDB:DBC-COUNT cursor)DBCursor->count).
(BDB:DBC-DEL cursor &KEY CONSUME)DBCursor->del).
(BDB:DBC-DUP cursor &KEY POSITION)DBCursor->dup).
(BDB:DBC-GET cursor key data action
&KEY DEGREE-2 DIRTY-READ MULTIPLE (ERROR T))Retrieve by cursor
(DBCursor->get).
If :ERROR is NIL and the record is not found, no ERROR is SIGNALed,
:NOTFOUND or :KEYEMPTY
is returned instead, as appropriate.
action should be one of
:CURRENT | :GET-RECNO | :NEXT-DUP | :SET |
:FIRST | :JOIN-ITEM | :NEXT-NODUP | :SET-RANGE |
:GET-BOTH | :LAST | :PREV | :SET-RECNO |
:GET-BOTH-RANGE | :NEXT | :PREV-NODUP |
(BDB:DBC-PUT cursor key data flag)DBCursor->put).
(BDB:WITH-DBC (var &REST
options) &BODY body))body, close it.
options are passed to BDB:MAKE-DBC.
(BDB:LOCK-DETECT dbe action)DB_ENV->lock_detect).
(BDB:LOCK-ID dbe)DB_ENV->lock_id).
(BDB:LOCK-ID-FREE dbe id)DB_ENV->lock_id_free).
All associated locks should be released first.
(BDB:LOCK-GET dbe object locker
mode &KEY NOWAIT)DB_ENV->lock_get).
The BDB:DBLOCK object returned by this function will
not be released when the environment is closed.
This permits long-lived locks.(BDB:LOCK-PUT dbe lock)DB_ENV->lock_put).
(BDB:LOCK-CLOSE lock)Release a lock
(DB_ENV->lock_put) using the
environment with which it has been acquired.
This is used to EXT:FINALIZE BDB:DBLOCK objects.
If that environment has already been closed, you are in a big trouble (segfault), so you better release your locks or do not drop them.
(BDB:LOCK-STAT dbe &KEY
STAT-CLEAR)DB_ENV->lock_stat).
(BDB:LOG-ARCHIVE dbe
&KEY ARCH-ABS ARCH-DATA ARCH-LOG ARCH-REMOVE)DB_ENV->log_archive).
(BDB:LOG-FILE dbe lsn)lsn
(DB_ENV->log_file).
(BDB:LOG-FLUSH dbe lsn)DB_ENV->log_flush).
(BDB:LOG-PUT dbe data
&KEY :FLUSH)DB_ENV->log_put).
(BDB:LOG-STAT dbe
&KEY STAT-CLEAR)DB_ENV->log_stat).
(BDB:LOG-CURSOR dbe)DB_ENV->log_cursor).
(BDB:LOGC-CLOSE logc)DB_LOGC->close).
(BDB:LOGC-GET logc action
&KEY TYPE ERROR)Retrieve a log record
(DB_LOGC->get).
If :ERROR is NIL and the record is not found, no ERROR is SIGNALed,
:NOTFOUND is returned instead.
Valid actions
:CURRENT:FIRST:LAST:NEXT:PREVDB_SET.
Returns two values: the datum of type specified by the :TYPE
argument and the DB:LSN value of the record retrieved
(when action is a DB:LSN, it
is returned unchanged).
Use EQUALP to check similarity of BDB:LSN objects.
(BDB:LOG-COMPARE lsn1 lsn2)log_compare).
(BDB:TXN-BEGIN dbe &KEY
DEGREE-2 PARENT DIRTY-READ NOSYNC NOWAIT SYNC)DB_ENV->txn_begin).
(BDB:TXN-ABORT txn)DB_TXN->abort).
(BDB:TXN-COMMIT txn &KEY
NOSYNC SYNC)DB_TXN->commit).
(BDB:TXN-DISCARD txn)DB_TXN->discard).
(BDB:TXN-ID txn)DB_TXN->id).
(BDB:TXN-CHECKPOINT dbe
&KEY KBYTE MIN FORCE)DB_ENV->txn_checkpoint).
(BDB:TXN-PREPARE txn id)DB_TXN->prepare).
(BDB:TXN-RECOVER dbe &KEY
FIRST NEXT)DB_ENV->txn_recover).
(BDB:TXN-SET-TIMEOUT txn
timeout which)DB_TXN->set_timeout).
(BDB:TXN-STAT dbe &KEY
STAT-CLEAR)DB_ENV->txn_stat).
| These notes document CLISP version 2.49.93+ | Last modified: 2018-02-19 |
| |