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 |
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 HOST CLIENT-TIMEOUT SERVER-TIMEOUT)
db_env_create
),
possibly connecting to a remote host
(DB_ENV->set_rpc_server
)
and 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
NIL
LIST
:TX-TIMESTAMP
DB_ENV->get_tx_timestamp
)
:TX-MAX
DB_ENV->set_tx_max
)
:DATA-DIR
DB_ENV->get_data_dir
)
:TMP-DIR
DB_ENV->get_tmp_dir
).
May be NIL
.:INTERMEDIATE-DIR-MODE
DB_ENV->get_intermediate_dir_mode
).
:VERBOSE
LIST
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-WAITSFOR
BOOLEAN
indicator of whether this
option is set or not
(DB_ENV->get_verbose
,
DB_ENV->get_flags
, and
DB_ENV->log_get_config
).
:LG-BSIZE
DB_ENV->get_lg_bsize
).
:LG-DIR
DB_ENV->get_lg_dir
).
:LG-MAX
DB_ENV->get_lg_max
).
:LG-REGIONMAX
DB_ENV->get_lg_regionmax
).
:NCACHE
:CACHESIZE
:CACHE
DB_ENV->get_cachesize
).
:LK-CONFLICTS
DB_ENV->get_lk_conflicts
).
:LK-DETECT
DB_ENV->get_lk_detect
).
:LK-MAX-LOCKERS
DB_ENV->get_lk_max_lockers
).
:LK-MAX-LOCKS
DB_ENV->get_lk_max_locks
).
:LK-MAX-OBJECTS
DB_ENV->get_lk_max_objects
).
:TAS-SPINS
DB_ENV->get_tas_spins
).
:SHM-KEY
DB_ENV->get_shm_key
).
:LOCK-TIMEOUT
:TXN-TIMEOUT
DB_ENV->get_timeout
).
:ENCRYPT
DB_ENV->get_encrypt_flags
).
:ERRFILE
NIL
(DB_ENV->get_errfile
).
:MSGFILE
NIL
(DB_ENV->get_msgfile
).
:ERRPFX
STRING
or NIL
(DB_ENV->get_errpfx
).
:DB-GID-SIZE
LENGTH
of the globally unique
(VECTOR
(UNSIGNED-BYTE
8))
which must be passed to
DB_TXN->prepare
.
:HOME
DB_ENV->get_home
).
:OPEN
LIST
of flags passed to BDB:DBE-OPEN
(DB_ENV->get_open_flags
).
:CACHE
DB_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 SIGNAL
ed,
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-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
NIL
LIST
:FLAGS
DB_ENV->get_flags
).
:CHKSUM
:ENCRYPT
:TXN-NOT-DURABLE
:DUP
:DUPSORT
:INORDER
:RECNUM
:REVSPLITOFF
:RENUMBER
:SNAPSHOT
BOOLEAN
indicator of whether this
option is set or not
(DB_ENV->get_verbose
and
DB_ENV->get_flags
).
:CACHE
DB->get_cachesize
or
DB_ENV->get_cachesize
if the
database was created within an environment).
:ENCRYPTION
DB_ENV->get_encrypt_flags
).
:ERRFILE
NIL
(DB_ENV->get_errfile
).
:MSGFILE
NIL
(DB_ENV->get_msgfile
).
:ERRPFX
STRING
or NIL
(DB_ENV->get_errpfx
).
:PAGESIZE
DB->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-LEN
DB->get_re_len
).
:RE-PAD
DB->get_re_pad
).
:RE-SOURCE
:RECNO
databases
(DB->get_re_source
).
:LORDER
DB->get_lorder
).
:DBNAME
DB->get_dbname
)
:TRANSACTIONAL
DB->get_transactional
).
:OPEN
BDB: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 SIGNAL
ed,
: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 SIGNAL
ed,
:NOTFOUND
is returned instead.
Valid action
s
:CURRENT
:FIRST
:LAST
:NEXT
:PREV
DB_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 | Last modified: 2010-07-07 |