ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import BSDDB 4.7.25 (as of svn r89086)

Browse Source
This commit is contained in:
Zachary Ware
2017-09-04 13:40:25 -05:00
parent 4b29e0458f
commit 8f590873d0
4781 changed files with 2241032 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs_src/api/Makefile Normal file
View File

@@ -0,0 +1,4 @@
# $Id: Makefile,v 10.5 2006/10/05 01:06:03 bostic Exp $
COMMON= frame.html \
object.html

20
docs_src/api/frame.so Normal file
View File

@@ -0,0 +1,20 @@
<!--$Id: frame.so,v 10.9 2006/10/05 01:06:03 bostic Exp $-->
<html>
<head>
<title>
m4_db API (Version: M4MAJOR.M4MINOR.M4PATCH)
</title>
m4_meta
</head>
<frameset cols="20%,80%">
<frame src="object.html" name="object" title="Objects">
<frame
name="method"
src="api_core.html"
title="m4_db API (Version: M4MAJOR.M4MINOR.M4PATCH)">
<noframes>
<meta http-equiv="refresh" content="0;url=api_index.html">
</noframes>
</frameset>
</html>

38
docs_src/api/object.so Normal file
View File

@@ -0,0 +1,38 @@
<!--$Id: object.so,v 10.19 2006/10/05 01:06:03 bostic Exp $-->
<html>
<head>
<title>m4_db API</title>
m4_meta
</head>
<body bgcolor=white>
<a target="_top" href="../index.html">Home</a><br>
<a target="method"
ifelse(M4API, C_API,
href="../api_c/c_pindex.html", href="../api_cxx/cxx_pindex.html")
>Permuted Index</a><br>
<a target="method" href="../utility/index.html">Utilities</a><br>
<p>
<b>m4_db</b><br>
<a target="method" href="api_core.html">All Methods</a><br>
<a target="method" href="../ref/toc.html">Reference Guide</a><br>
<p>
<a target="method" href="dbc_list.html">Cursors</a><br>
<a target="method" href="db_list.html">Databases</a><br>
<a target="method" href="env_list.html">Environments</a><br>
ifelse(M4API, C_API,, [<a target="method" href="exc_package.html">Exceptions</a><br>])
<a target="method" href="dbt_package.html">Key/Data Pairs</a><br>
<a target="method" href="lock_list.html">Locking</a><br>
<a target="method" href="log_list.html">Logging</a><br>
<a target="method" href="memp_list.html">Memory Pool</a><br>
<a target="method" href="mutex_list.html">Mutexes</a><br>
<a target="method" href="rep_list.html">Replication</a><br>
<a target="method" href="seq_list.html">Sequences</a><br>
<a target="method" href="txn_list.html">Transactions</a><br>
<p>
<b>Historic APIs</b><br>
<a target="method" href="../api_c/dbm.html">Dbm/Ndbm</a><br>
<a target="method" href="../api_c/hsearch.html">Hsearch</a><br>
</body>
</html>

208
docs_src/build Normal file
View File

@@ -0,0 +1,208 @@
#!/bin/sh
#
# Script to build the web-version of the Berkeley DB documentation.
#
# $Id: build,v 1.107 2008/02/07 17:12:18 mark Exp $
# The build script must be run from the document source directory.
MSG="build: build script must be run from the document source directory."
egrep "^MSG=\"$MSG\"" build > /dev/null 2>&1 || {
echo "$MSG"
exit 1
}
# Save the absolute path of the Berkeley DB document source directory.
DOCS_SRC=`pwd`
export DOCS_SRC
# Save the absolute path of the Berkeley DB source directory.
BDB_SRC=`dirname $DOCS_SRC`
export BDB_SRC
# Save the absolute path of the target Berkeley DB documents directory.
TARGET=$BDB_SRC/docs
export TARGET
# splash:
# splash page.
splash()
{
rm -f $TARGET/index.html
sed -e "s/DB_RELEASE_DATE/$DB_RELEASE_DATE/" \
-e "s/DB_VERSION_MAJOR/$DB_VERSION_MAJOR/" \
-e "s/DB_VERSION_MINOR/$DB_VERSION_MINOR/" \
-e "s/DB_VERSION_PATCH/$DB_VERSION_PATCH/" \
< index_db.html > $TARGET/index.html
}
# api_index:
# Build a sorted list of all methods.
api_index()
{
t=/tmp/__build.$$
cat <<END_OF_HEADER > $t
m4_comment([DO NOT EDIT: automatically built by build script.])
m4_page_title([m4_db: ifelse(M4API, C_API, C, C++) Handle Methods (version M4MAJOR.M4MINOR.M4PATCH)])
m4_table_begin(, _center)
m4_table_header(ifelse(M4API, C_API, C, C++) Handle Methods, Description)
END_OF_HEADER
d="db dbc env lock log memp mutex rep seq txn"
for i in $d; do
egrep m4_table_element $i/m4.methods
done | sort -u >> $t
cat <<END_OF_FOOTER >> $t
m4_table_end
m4_page_footer
END_OF_FOOTER
f=env/api_core.so
cmp $t $f > /dev/null 2>&1 || (echo "Building $f" && cp $t $f)
}
# reftoc:
# Berkeley DB Reference Guide table of contents.
reftoc()
{
rm -f $TARGET/ref/toc.html
sed -e "s/__EDIT_PRODUCT/Berkeley DB/" \
-e "s/__EDIT_VERSION_MAJOR/$DB_VERSION_MAJOR/" \
-e "s/__EDIT_VERSION_MINOR/$DB_VERSION_MINOR/" \
-e "s/__EDIT_VERSION_PATCH/$DB_VERSION_PATCH/" \
-e "s/__EDIT_RELEASE_DATE/$DB_RELEASE_DATE/" \
< ref/toc.html > $TARGET/ref/toc.html
}
# build:
# Build the Berkeley DB documents.
#
# $1: Directory to build.
# $2: API
# $3: Depth in tree
# $4: Source Directory
build()
{
f=$TARGET/$1
[ -d $f ] || mkdir -p $f
# Copy documents.
# Check for COPY in the Makefile first, some make programs have their
# own values for the "COPY" variable if it's not already set.
if egrep COPY $4/Makefile > /dev/null 2>&1; then
(cat $4/Makefile &&
echo &&
cat $DOCS_SRC/support/copy) > $f/Makefile
(cd $f && make BUILDDIR=$1 copy || exit 1)
fi
# Build documents.
(cat $DOCS_SRC/support/suffix &&
echo &&
echo "VPATH=\$(DOCS_SRC)/$4" &&
echo &&
cat $4/Makefile &&
case $2 in
C_API)
echo 'all: $(COMMON) $(C)';;
CXX_API)
echo 'all: $(COMMON) $(CXX)';;
NOAPI|UTILITY)
echo 'all: $(BUILD)';;
esac) > $f/Makefile
(cd $f &&
make ABSDIR=`pwd` \
API=$2 \
BUILDDIR=$1 \
RELDIR=$3 || exit 1)
rm -f $f/Makefile
}
# run
# Run any single command.
run()
{
case "$1" in
c)
for i in $APILIST; do
build api_c C_API .. $i
done;;
check)
shift
sh $DOCS_SRC/support/check $TARGET $*;;
clean)
(cd $TARGET && rm -rf api_c api_cxx \
api_tcl images index.html java license ref utility);;
cxx)
for i in $APILIST; do
build api_cxx CXX_API .. $i
done;;
index)
sh $DOCS_SRC/support/Xindex;;
javadoc)
javadoc $JAVADOC_ARGS -protected -d $TARGET/java \
-use -link http://java.sun.com/j2se/1.5.0/docs/api/ \
-link http://java.sun.com/javaee/5/docs/api/ \
-sourcepath $BDB_SRC/java/src \
-source 1.5 -stylesheetfile support/style.css \
-header '<b>Berkeley DB</b><br><font size="-1"> version '$DB_VERSION_MAJOR.$DB_VERSION_MINOR.$DB_VERSION_PATCH'</font>' \
-windowtitle 'Oracle - Berkeley DB Java API' -bottom '<font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>' \
com.sleepycat.db com.sleepycat.bind com.sleepycat.bind.serial com.sleepycat.bind.tuple com.sleepycat.collections com.sleepycat.persist com.sleepycat.persist.model com.sleepycat.persist.evolve com.sleepycat.persist.raw com.sleepycat.util \
-group 'Berkeley DB Core Package' com.sleepycat.db \
-group 'Berkeley DB Direct Persistence Layer (DPL) Packages' com.sleepycat.persist:com.sleepycat.persist.model:com.sleepycat.persist.evolve:com.sleepycat.persist.raw \
-group 'Berkeley DB Bind and Collections Packages' com.sleepycat.bind:com.sleepycat.bind.serial:com.sleepycat.bind.tuple:com.sleepycat.collections:com.sleepycat.util | \
egrep -v 'Generating|first sentence';;
ref)
[ -d $TARGET/ref ] || mkdir $TARGET/ref
reftoc
for i in $REFLIST; do
build ref/$i C_API ../.. ref/$i
done;;
tcl)
build api_tcl TCL_API .. tcl;;
util*)
build utility UTILITY .. utility;;
*)
echo "build: unknown command $1"
exit 1;;
esac
}
# Source the RELEASE file to get major/minor numbers.
. $BDB_SRC/dist/RELEASE
PRODUCT="CORE"
export DB_RELEASE_DATE
export DB_VERSION_MAJOR
export DB_VERSION_MINOR
export DB_VERSION_PATCH
version="$DB_VERSION_MAJOR.$DB_VERSION_MINOR.$DB_VERSION_PATCH"
APILIST="api db db_except dbc dbt env exc historic lock log memp mutex
rep rtc seq txn"
REFLIST="am am_conf am_misc apprec arch build_brew build_s60 build_unix
build_vxworks build_win build_wince cam changelog debug distrib dumpload
env ext install intro java lock log mp program refs rep rpc sequence tcl
test transapp txn upgrade upgrade.2.0 upgrade.3.0 upgrade.3.1
upgrade.3.2 upgrade.3.3 upgrade.4.0 upgrade.4.1 upgrade.4.2 upgrade.4.3
upgrade.4.4 upgrade.4.5 upgrade.4.6 upgrade.4.7 xa"
if [ $# = 0 ]; then
echo "Building Berkeley DB documentation ..."
[ -d $TARGET ] || mkdir $TARGET
splash
api_index
build images NOAPI .. images
build license NOAPI .. license
run c
run cxx
run ref
run tcl
run utility
run index
run javadoc
else
run $*
fi

66
docs_src/db/Makefile Normal file
View File

@@ -0,0 +1,66 @@
# $Id: Makefile,v 1.17 2007/07/12 18:27:42 bostic Exp $
COMMON= db_associate.html \
db_class.html \
db_close.html \
db_compact.html \
db_cursor.html \
db_del.html \
db_err.html \
db_exists.html \
db_get.html \
db_get_byteswapped.html \
db_get_mpf.html \
db_get_type.html \
db_getenv.html \
db_join.html \
db_key_range.html \
db_list.html \
db_open.html \
db_put.html \
db_remove.html \
db_rename.html \
db_set_append_recno.html \
db_set_bt_compare.html \
db_set_bt_minkey.html \
db_set_bt_prefix.html \
db_set_cachesize.html \
db_set_dup_compare.html \
db_set_encrypt.html \
db_set_errcall.html \
db_set_errpfx.html \
db_set_feedback.html \
db_set_flags.html \
db_set_h_compare.html \
db_set_h_ffactor.html \
db_set_h_hash.html \
db_set_h_nelem.html \
db_set_lorder.html \
db_set_msgcall.html \
db_set_pagesize.html \
db_set_priority.html \
db_set_q_extentsize.html \
db_set_re_delim.html \
db_set_re_len.html \
db_set_re_pad.html \
db_set_re_source.html \
db_stat.html \
db_sync.html \
db_truncate.html \
db_upgrade.html \
db_verify.html \
dbt_class.html
C= db_fd.html \
db_set_alloc.html \
db_set_errfile.html \
db_set_msgfile.html \
dbt_bulk.html
CXX= db_fd.html \
db_set_alloc.html \
db_set_errfile.html \
db_set_error_stream.html \
db_set_msg_stream.html \
db_set_msgfile.html \
dbt_bulk_class.html

185
docs_src/db/db_associate.so Normal file
View File

@@ -0,0 +1,185 @@
m4_comment([$Id: db_associate.so,v 10.47 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL,
[dbh_associate, DB_DBT_APPMALLOC, DB_DBT_MULTIPLE, DB_DONOTINDEX,
DB_IMMUTABLE_KEY])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_associate),
ifelse(M4API, C_API, [dnl
int
DB-__GT__associate(DB *primary, DB_TXN *txnid, DB *secondary,
int (*callback)(DB *secondary,
const DBT *key, const DBT *data, DBT *result), u_int32_t flags);])
ifelse(M4API, CXX_API, [dnl
int
Db::associate(DbTxn *txnid, Db *secondary,
int (*callback)(Db *secondary,
const Dbt *key, const Dbt *data, Dbt *result), u_int32_t flags);])
)
m4_p([dnl
The m4_ref(dbh_associate) function is used to declare one database a
secondary index for a primary database. After a secondary database has
been "associated" with a primary database, all updates to the primary
will be automatically reflected in the secondary and all reads from the
secondary will return corresponding data from the primary. Note that
as primary keys must be unique for secondary indices to work, the
primary database must be configured without support for duplicate data
items. See m4_link(M4RELDIR/ref/am/second, [Secondary indices]) for
more information.])
m4_return(dbh_associate, std)
m4_parambegin
m4_param(callback, [dnl
The m4_arg(callback) parameter is a callback function that creates the
set of secondary keys corresponding to a given primary key and data
pair.
m4_p([dnl
The callback parameter may be NULL if both the primary and secondary
database handles were opened with the m4_ref(DB_RDONLY) flag.])
m4_p([dnl
The callback takes four arguments:])
m4_tagbegin
m4_tag(m4_arg(secondary), [dnl
The m4_arg(secondary) parameter is the database handle for the secondary.])
m4_tag(m4_arg(key), [dnl
The m4_arg(key) parameter is a m4_ref(Dbt) referencing the primary key.])
m4_tag(m4_arg(data), [dnl
The m4_arg(data) parameter is a m4_ref(Dbt) referencing the primary data
item.])
m4_tag(m4_arg(result), [dnl
The m4_arg(result) parameter is a zeroed m4_ref(Dbt) in which the callback
function should fill in m4_arg(data) and m4_arg(size) fields that describe
the secondary key or keys.])
m4_tagend
m4_p([dnl
The callback optionally returns some special values:])
m4_tagbegin
m4_tag(m4_idef(DB_DBT_APPMALLOC), [dnl
If the callback function needs to allocate memory for the m4_arg(result)
data field (rather than simply pointing into the primary key or datum),
m4_ref(DB_DBT_APPMALLOC) should be set in the m4_arg(flags) field of the
m4_arg(result) m4_ref(Dbt), which indicates that m4_db should free the
memory when it is done with it.])
m4_tag(m4_idef(DB_DBT_MULTIPLE), [dnl
To return multiple secondary keys, m4_ref(DB_DBT_MULTIPLE) should be set
in the m4_arg(flags) field of the m4_arg(result) m4_ref(Dbt), which
indicates m4_db should treat the m4_arg(size) field as the number of
secondary keys (zero or more), and the m4_arg(data) field as a pointer
to an array of that number of m4_ref(Dbt)s describing the set of
secondary keys.
m4_p([dnl
m4_bold([When multiple secondary keys are returned, keys may not be repeated]).
In other words, there must be no repeated record numbers in the array
for Recno and Queue databases, and keys must not compare equally using
the secondary database's comparison function for Btree and Hash
databases. If keys are repeated, operations may fail and the secondary
may become inconsistent with the primary.])
m4_p([dnl
The m4_ref(DB_DBT_APPMALLOC) flag may be set for any m4_ref(Dbt) in the
array of returned m4_ref(Dbt)'s to indicate that m4_db should free the
memory referenced by that particular m4_ref(Dbt)'s data field when it
is done with it.])
m4_p([dnl
The m4_ref(DB_DBT_APPMALLOC) flag may be combined with
m4_ref(DB_DBT_MULTIPLE) in the m4_arg(result) m4_ref(Dbt)'s m4_arg(flag)
field to indicate that m4_db should free the array once it is done with
all of the returned keys.])])
m4_tag(m4_idef(DB_DONOTINDEX), [dnl
If any key/data pair in the primary yields a null secondary key and
should be left out of the secondary index, the callback function may
optionally return m4_ref(DB_DONOTINDEX). Otherwise, the callback
function should return 0 in case of success or an error outside of the
m4_db name space in case of failure; the error code will be returned
from the m4_db call that initiated the callback.
m4_p([dnl
If the callback function returns m4_ref(DB_DONOTINDEX) for any key/data
pairs in the primary database, the secondary index will not contain any
reference to those key/data pairs, and such operations as cursor
iterations and range queries will reflect only the corresponding subset
of the database. If this is not desirable, the application should
ensure that the callback function is well-defined for all possible
values and never returns m4_ref(DB_DONOTINDEX).])
m4_p([dnl
Returning m4_ref(DB_DONOTINDEX) is equivalent to setting
m4_ref(DB_DBT_MULTIPLE) on the m4_arg(result) m4_ref(Dbt) and setting
the m4_arg(size) field to zero.])])
m4_tagend
m4_not_reentrant])
m4_param(flags, [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_CREATE), [dnl
If the secondary database is empty, walk through the primary and create
an index to it in the empty secondary. This operation is potentially
very expensive.
m4_p([dnl
If the secondary database has been opened in an environment configured
with transactions, each put necessary for its creation will be done in
the context of a transaction created for the purpose.])
m4_p([dnl
Care should be taken not to use a newly-populated secondary database in
another thread of control until the m4_ref(dbh_associate) call has
returned successfully in the first thread.])
m4_p([dnl
If transactions are not being used, care should be taken not to modify
a primary database being used to populate a secondary database, in
another thread of control, until the m4_ref(dbh_associate) call has
returned successfully in the first thread. If transactions are being
used, m4_db will perform appropriate locking and the application need
not do any special operation ordering.])])
m4_tag(m4_idef(DB_IMMUTABLE_KEY), [dnl
Specifies the secondary key is immutable.
m4_p([dnl
This flag can be used to optimize updates when the secondary key in a
primary record will never be changed after the primary record is
inserted. For immutable secondary keys, a best effort is made to avoid
calling the secondary callback function when primary records are
updated. This optimization may reduce the overhead of update operations
significantly if the callback function is expensive.])
m4_p([dnl
Be sure to specify this flag only if the secondary key in the primary
record is never changed. If this rule is violated, the secondary index
will become corrupted, that is, it will become out of sync with the
primary.])])
m4_tagend])
m4_param(primary, [dnl
ifelse(M4API, C_API, [dnl
The m4_arg(primary) parameter should be a database handle for the primary
database that is to be indexed.],[dnl
The associate method called should be a method of a database handle for
the primary database that is to be indexed.])])
m4_param(secondary, [dnl
The m4_arg(secondary) parameter should be an open database handle of
either a newly created and empty database that is to be used to store
a secondary index, or of a database that was previously associated with
the same primary and contains a secondary index. Note that it is not
safe to associate as a secondary database a handle that is in use by
another thread of control or has open cursors. If the handle was opened
with the m4_ref(DB_THREAD) flag it is safe to use it in multiple threads
of control after the m4_refT(dbh_associate) has returned. Note also
that either secondary keys must be unique or the secondary database must
be configured with support for duplicate data items.])
m4_param_txn(dbh_associate)
m4_paramend
m4_err(dbh_associate, rephandle, replockout, einval,
[the secondary database handle has already been associated with this or
another database handle; the secondary database handle is not open; the
primary database has been configured to allow duplicates])
m4_seealso(Db)
m4_page_footer

153
docs_src/db/db_class.so Normal file
View File

@@ -0,0 +1,153 @@
m4_comment([$Id: db_class.so,v 10.53 2007/10/26 14:52:37 bostic Exp $])
define(M4PAGELOCAL, [dbh_create, Db, DB_CXX_NO_EXCEPTIONS])
include(m4/m4.seealso)
ifelse(M4API, C_API, [dnl
m4_pf_header(m4_ref(dbh_create), [dnl
typedef struct __db DB;
m4_blank
int
db_create(DB **dbp, DB_ENV *dbenv, u_int32_t flags);
])])
ifelse(M4API, CXX_API, [dnl
m4_pf_header(m4_ref(Db), [dnl
class Db {
public:
Db(DbEnv *dbenv, u_int32_t flags);
~Db();
m4_blank
DB *Db::get_DB();
const DB *Db::get_const_DB() const;
static Db *Db::get_Db(DB *db);
static const Db *Db::get_const_Db(const DB *db);
...
};])])
define(xa_create_tag, [dnl
m4_tag(m4_idef(DB_XA_CREATE), [dnl
Instead of creating a standalone database, create a database intended
to be accessed via applications running under an X/Open conformant
Transaction Manager. The database will be opened in the environment
specified by the OPENINFO parameter of the GROUPS section of the
ubbconfig file. See the m4_link(M4RELDIR/ref/xa/xa_intro, [XA
Introduction]) section in the m4_db Reference Guide for more information.])])
m4_p([dnl
The m4_ref(Db) handle is the handle for a m4_db database, which may or
may not be part of a database environment.])
m4_p([dnl
m4_ref(Db) handles are free-threaded if the m4_ref(DB_THREAD) flag is
specified to the m4_refT(dbh_open) when the database is opened or if the
database environment in which the database is opened is free-threaded.
The handle should not be closed while any other handle that refers to
the database is in use; for example, database handles must not be closed
while cursor handles into the database remain open, or transactions that
include operations on the database have not yet been committed or
aborted. Once the m4_ref(dbh_close), m4_ref(dbh_remove),
m4_ref(dbh_rename), or m4_refT(dbh_verify)s are called, the handle may
not be accessed again, regardless of the method's return.])
ifelse(M4API, C_API, [dnl
m4_p([dnl
The m4_ref(dbh_create) function creates a m4_ref(Db) structure that is
the handle for a m4_db database. This function allocates memory for the
structure, returning a pointer to the structure in the memory to which
m4_arg(dbp) refers. To release the allocated memory and discard the
handle, call the m4_ref(dbh_close), m4_ref(dbh_remove),
m4_ref(dbh_rename), or m4_refT(dbh_verify)s.])
m4_p([dnl
The m4_ref(Db) handle contains a special field, "app_private", which is
declared as type "void *". This field is provided for the use of the
application program. It is initialized to NULL and is not further used
by m4_db in any way.])
m4_return(dbh_create, std)
m4_parambegin
m4_param(dbp, [dnl
The m4_arg(dbp) parameter references the memory into which the returned
structure pointer is stored.])
m4_param(dbenv, [dnl
If the m4_arg(dbenv) parameter is NULL, the database is standalone; that
is, it is not part of any m4_db environment.
m4_p([dnl
If the m4_arg(dbenv) parameter is not NULL, the database is created
within the specified m4_db environment. The database access methods
automatically make calls to the other subsystems in m4_db, based on the
enclosing environment. For example, if the environment has been
configured to use locking, the access methods will automatically acquire
the correct locks when reading and writing pages of the database.])])
m4_param(flags, [dnl
m4_sf_zmust(0)
m4_tagbegin
xa_create_tag
m4_tagend])
m4_paramend
m4_err(dbh_create, einval)],[dnl
m4_p([dnl
The constructor creates a m4_ref(Db) object that is the handle for a
m4_db database. The constructor allocates memory internally; calling
the m4_ref(dbh_close), m4_ref(dbh_remove) or m4_refT(dbh_rename)s will
free that memory.])
m4_p([dnl
Each m4_ref(Db) object has an associated m4_refc(Db) struct, which is
used by the underlying implementation of m4_db and its C-language API.
The Db::get_DB method returns a pointer to this struct. Given a const
m4_ref(Db) object, Db::get_const_DB returns a const pointer to the
same struct.])
m4_p([dnl
Given a m4_refc(Db) struct, the Db::get_Db method returns the
corresponding m4_ref(Db) object, if there is one. If the m4_refc(Db)
object was not associated with a m4_ref(Db) (that is, it was not
returned from a call to Db::get_DB), then the result of Db::get_Db is
undefined. Given a const m4_refc(Db) struct, Db::get_const_Db returns
the associated const m4_ref(Db) object, if there is one.])
m4_p([dnl
These methods may be useful for m4_db applications including both C
and C++ language software. It should not be necessary to use these
calls in a purely C++ application.])
m4_parambegin
m4_param(dbenv, [dnl
If no m4_arg(dbenv) value is specified, the database is standalone; that
is, it is not part of any m4_db environment.
m4_p([dnl
If a m4_arg(dbenv) value is specified, the database is created within
the specified m4_db environment. The database access methods
automatically make calls to the other subsystems in m4_db based on the
enclosing environment. For example, if the environment has been
configured to use locking, the access methods will automatically acquire
the correct locks when reading and writing pages of the database.])])
m4_param(flags, [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_CXX_NO_EXCEPTIONS), [dnl
The m4_db C++ API supports two different error behaviors. By default,
whenever an error occurs, an exception is thrown that encapsulates the
error information. This generally allows for cleaner logic for
transaction processing because a try block can surround a single
transaction. However, if m4_ref(DB_CXX_NO_EXCEPTIONS) is specified,
exceptions are not thrown; instead, each individual function returns an
error code.
m4_p([dnl
If m4_arg(dbenv) is not null, this flag is ignored, and the error behavior
of the specified environment is used instead.])])
xa_create_tag
m4_tagend])
m4_paramend])
m4_seealso(Db)
m4_page_footer

76
docs_src/db/db_close.so Normal file
View File

@@ -0,0 +1,76 @@
m4_comment([$Id: db_close.so,v 10.55 2004/08/13 03:38:55 bostic Exp $])
define(M4PAGELOCAL, dbh_close)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_close),
ifelse(M4API, C_API, [dnl
int
DB-__GT__close(DB *db, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::close(u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_close) flushes any cached database information to disk,
closes any open cursors, frees any allocated resources, and closes any
underlying files.])
m4_p([dnl
The m4_ref(Db) handle should not be closed while any other handle that
refers to it is not yet closed; for example, database handles must not
be closed while cursor handles into the database remain open, or
transactions that include operations on the database have not yet been
committed or aborted. Specifically, this includes m4_ref(Dbc) and
m4_ref(DbTxn) handles.])
m4_p([dnl
Because key/data pairs are cached in memory, failing to sync the file
with the m4_ref(dbh_close) or m4_refT(dbh_sync) may result in
inconsistent or lost information.])
m4_p([dnl
When called on a database that is the primary database for a secondary
index, the primary database should be closed only after all secondary
indices which reference it have been closed.])
m4_p([dnl
When multiple threads are using the m4_ref(Db) concurrently, only a single
thread may call the m4_refT(dbh_close).])
m4_destructor(Db, dbh_close)
m4_return(dbh_close, std)
m4_parambegin
m4_param(flags, [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_NOSYNC), [dnl
Do not flush cached information to disk. The m4_ref(DB_NOSYNC) flag is
a dangerous option. It should be set only if the application is doing
logging (with transactions) so that the database is recoverable after
a system or application crash, or if the database is always generated
from scratch after any system or application crash.
m4_p([m4_bold([dnl
It is important to understand that flushing cached information to disk
only minimizes the window of opportunity for corrupted data.]) Although
unlikely, it is possible for database corruption to happen if a system
or application crash occurs while writing data to the database. To
ensure that database corruption never occurs, applications must either:
use transactions and logging with automatic recovery; use logging and
application-specific recovery; or edit a copy of the database, and once
all applications using the database have successfully called
m4_ref(dbh_close), atomically replace the original database with the
updated copy.])])
m4_tagend])
m4_paramend
m4_err(dbh_close, einval)
m4_seealso(Db)
m4_page_footer

123
docs_src/db/db_compact.so Normal file
View File

@@ -0,0 +1,123 @@
m4_comment([$Id: db_compact.so,v 1.8 2008/04/30 15:25:34 mbrey Exp $])
define(M4PAGELOCAL, dbh_compact)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_compact),
ifelse(M4API, C_API, [dnl
int
DB-__GT__compact(DB *db, DB_TXN *txnid,
DBT *start, DBT *stop, DB_COMPACT *c_data, u_int32_t flags, DBT *end);
])
ifelse(M4API, CXX_API, [dnl
int
Db::compact(DbTxn *txnid,
Dbt *start, Dbt *stop, DB_COMPACT *c_data, u_int32_t flags, Dbt *end);
]))
m4_p([dnl
The m4_refT(dbh_compact) compacts Btree and Recno access method
databases, and optionally returns unused Btree, Hash or Recno database
pages to the underlying filesystem.])
m4_return(dbh_compact, std)
m4_parambegin
m4_param(txnid, [dnl
If the operation is part of an application-specified transaction, the
m4_arg(txnid) parameter is a transaction handle returned from
m4_ref(txn_begin); otherwise NULL. If no transaction handle is
specified, but the operation occurs in a transactional database, the
operation will be implicitly transaction protected using multiple
transactions. These transactions will be periodically committed to
avoid locking large sections of the tree. Any deadlocks encountered
cause the compaction operation to retried from the point of the last
transaction commit.])
m4_param(start, [dnl
If non-NULL, the m4_arg(start) parameter is the starting point for
compaction in a Btree or Recno database. Compaction will start at the
smallest key greater than or equal to the specified key. If NULL,
compaction will start at the beginning of the database.])
m4_param(stop, [dnl
If non-NULL, the m4_arg(stop) parameter is the stopping point for
compaction in a Btree or Recno database. Compaction will stop at the
page with the smallest key greater than the specified key. If NULL,
compaction will stop at the end of the database.])
m4_param(c_data, [m4_p([dnl
If non-NULL, the m4_arg(c_data) parameter contains additional compaction
configuration parameters, and returns compaction operation statistics,
in a structure of type DB_COMPACT.])
m4_p([dnl
The following input configuration fields are available from the
DB_COMPACT structure:])
m4_tagbegin
m4_field(int, compact_fillpercent, [dnl
If non-zero, the goal for filling pages, specified as a percentage
between 1 and 100. Any page in a Btree or Recno databases not at or
above this percentage full will be considered for compaction. The
default behavior is to consider every page for compaction, regardless
of its page fill percentage.])
m4_field(int, compact_pages, [dnl
If non-zero, the call will return after that number of pages have been
freed.])
m4_field(db_timeout_t, compact_timeout, [dnl
If non-zero, and no m4_arg(txnid) parameter was specified, the lock
timeout set for implicit transactions, in microseconds.])
m4_tagend
m4_p([dnl
The following output statistics fields are available from the
DB_COMPACT structure:])
m4_tagbegin
m4_field(u_int32_t, compact_deadlock, [dnl
An output statistics parameter: if no m4_arg(txnid) parameter was
specified, the number of deadlocks which occurred.])
m4_field(u_int32_t, compact_pages_examine, [dnl
An output statistics parameter: the number of database pages reviewed
during the compaction phase.])
m4_field(u_int32_t, compact_pages_free, [dnl
An output statistics parameter: the number of database pages freed during
the compaction phase.])
m4_field(u_int32_t, compact_levels, [dnl
An output statistics parameter: the number of levels removed from the
Btree or Recno database during the compaction phase.])
m4_field(u_int32_t, compact_pages_truncated, [dnl
An output statistics parameter: the number of database pages returned
to the filesystem.])
m4_tagend])
m4_param(flags, [dnl
m4_sf_zmust
m4_tagbegin
m4_tag(m4_idef(DB_FREELIST_ONLY), [dnl
Do no page compaction, only returning pages to the filesystem that are
already free and at the end of the file. This flag must be set if the
database is a Hash access method database.])
m4_tag(m4_idef(DB_FREE_SPACE), [dnl
Return pages to the filesystem when possible.
If this flag is not specified, pages emptied as a result of compaction
will be placed on the free list for re-use, but never returned to the
filesystem.
m4_p([dnl
Note that only pages at the end of a file can be returned to the
filesystem. Because of the one-pass nature of the compaction algorithm,
any not emptied page near the end of the file inhibits returning pages to
the file system. A repeated call to the m4_refT(dbh_compact) with a low
m4_arg(compact_fillpercent) may be used to return pages in this case.])])
m4_tagend])
m4_param(end, [dnl
If non-NULL, the m4_arg(end) parameter will be filled in with the
database key marking the end of the compaction operation in a Btree or
Recno database. This is generally the first key of the page where the
operation stopped.])
m4_paramend
m4_err(dbh_compact, deadlock, rephandle, replockout, readonly, einval,,)
m4_seealso(Db)
m4_page_footer

76
docs_src/db/db_cursor.so Normal file
View File

@@ -0,0 +1,76 @@
m4_comment([$Id: db_cursor.so,v 10.55 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL, dbh_cursor)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_cursor),
ifelse(M4API, C_API, [dnl
int
DB-__GT__cursor(DB *db,
DB_TXN *txnid, DBC **cursorp, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::cursor(DbTxn *txnid, Dbc **cursorp, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_cursor) returns a created database cursor.])
m4_p([dnl
Cursors may span threads, but only serially, that is, the application
must serialize access to the cursor handle.])
m4_return(dbh_cursor, std)
m4_parambegin
m4_param_co(cursorp, allocated cursor, REF)
m4_param(flags, [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_READ_COMMITTED), [dnl
Configure a transactional cursor to have degree 2 isolation. This ensures
the stability of the current data item read by this cursor but permits data
read by this cursor to be modified or deleted prior to the commit of the
transaction for this cursor.])
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
Configure a transactional cursor to have degree 1 isolation. Read
operations performed by the cursor may return modified but not yet
committed data. Silently ignored if the m4_ref(DB_READ_UNCOMMITTED)
flag was not specified when the underlying database was opened.])
m4_tag(m4_idef(DB_WRITECURSOR), [dnl
Specify that the cursor will be used to update the database. The
underlying database environment must have been opened using the
m4_ref(DB_INIT_CDB) flag.])
m4_tag(m4_idef(DB_TXN_SNAPSHOT), [dnl
Configure a transactional cursor to operate with read-only
m4_link(M4RELDIR/ref/transapp/read, snapshot isolation). For databases
with the m4_ref(DB_MULTIVERSION) flag set, data values will be read as
they are when the cursor is opened, without taking read locks. This
flag implicitly begins a transaction that is committed when the cursor
is closed. Silently ignored if m4_ref(DB_MULTIVERSION) not set on the
underlying database or if a transaction is supplied in the m4_arg(txnid)
parameter.])
m4_tagend])
m4_param(txnid, [dnl
Cursor operations are not automatically transaction-protected, even if
the m4_ref(DB_AUTO_COMMIT) flag is specified to the
m4_ref(dbenv_set_flags) or m4_refT(dbh_open)s. If cursor operations are
to be transaction-protected, the m4_arg(txnid) parameter must be a
transaction handle returned from m4_ref(txn_begin); otherwise, NULL. To
transaction-protect cursor operations, cursors must be opened and closed
within the context of a transaction, and the m4_arg(txnid) parameter
specifies the transaction context in which the cursor may be used.])
m4_paramend
m4_err(dbh_cursor, rephandle, replockout, einval)
m4_seealso(Dbc)
m4_page_footer

43
docs_src/db/db_del.so Normal file
View File

@@ -0,0 +1,43 @@
m4_comment([$Id: db_del.so,v 10.51 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL, [dbh_del])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_del),
ifelse(M4API, C_API, [dnl
int
DB-__GT__del(DB *db, DB_TXN *txnid, DBT *key, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::del(DbTxn *txnid, Dbt *key, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_del) removes key/data pairs from the database. The
key/data pair associated with the specified m4_arg(key) is discarded from
the database. In the presence of duplicate key values, all records
associated with the designated key will be discarded.])
m4_p([dnl
When called on a database that has been made into a secondary index
using the m4_refT(dbh_associate), the m4_refT(dbh_del) deletes the
key/data pair from the primary database and all secondary indices.])
m4_return(dbh_del,
specific, DB_NOTFOUND, [if the specified key is not in the database],
specific, DB_KEYEMPTY, [if the database is a Queue or Recno database and
the specified key exists, but was never explicitly created by the
application or was later deleted], prev)
m4_parambegin
m4_unusedflags
m4_param_key
m4_param_txn(dbh_del)
m4_paramend
m4_err(dbh_del,
deadlock, rephandle, replockout, secondary_bad, readonly, einval)
m4_seealso(Db)
m4_page_footer

4
docs_src/db/db_err.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_err.so,v 1.3 2002/08/18 21:15:48 bostic Exp $])
define(M4INTERFACE, dbh_err)
include(env/env_err.so)

55
docs_src/db/db_exists.so Normal file
View File

@@ -0,0 +1,55 @@
m4_comment([$Id: db_exists.so,v 1.1 2007/07/12 18:27:42 bostic Exp $])
define(M4PAGELOCAL, dbh_exists)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_exists),
ifelse(M4API, C_API, [dnl
int
DB-__GT__exists(DB *db, DB_TXN *txnid, DBT *key, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::exists(DbTxn *txnid, Dbt *key, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_exists) returns if the specified key appears in the
database.])
m4_return(dbh_exists,
specific, DB_NOTFOUND, [if the specified key is not in the database],
specific, DB_KEYEMPTY, [if the database is a Queue or Recno database and
the specified key exists, but was never explicitly created by the
application or was later deleted], prev)
m4_parambegin
m4_param(flags, [dnl
m4_sf_zmust(1)
m4_sf_or_add(1)
m4_tagbegin
m4_tag(m4_idef(DB_READ_COMMITTED), [dnl
Configure a transactional read operation to have degree 2 isolation (the
read is not repeatable).])
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
Configure a transactional read operation to have degree 1 isolation,
reading modified but not yet committed data. Silently ignored if the
m4_ref(DB_READ_UNCOMMITTED) flag was not specified when the underlying
database was opened.])
m4_rmw_flag([Because the m4_refT(dbh_exists) will not hold locks across
m4_db calls in non-transactional operations, the m4_ref(DB_RMW) flag to
the m4_ref(dbh_exists) call is meaningful only in the presence of
transactions.])
m4_tagend])
m4_param_key
m4_param_txn(dbh_exists, ro)
m4_paramend
m4_seealso(Db)
m4_page_footer

37
docs_src/db/db_fd.so Normal file
View File

@@ -0,0 +1,37 @@
m4_comment([$Id: db_fd.so,v 10.31 2005/06/14 14:06:57 bostic Exp $])
define(M4PAGELOCAL, dbh_fd)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_fd),
ifelse(M4API, C_API, [dnl
int
DB-__GT__fd(DB *db, int *fdp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::fd(int *fdp);
]))
m4_p([dnl
The m4_refT(dbh_fd) provides access to a file descriptor representative
of the underlying database. A file descriptor referring to the same
file will be returned to all processes that call m4_ref(dbh_open) with
the same m4_arg(file) parameter.])
m4_p([dnl
This file descriptor may be safely used as a parameter to the
m4_manref(fcntl, 2) and m4_manref(flock, 2) locking functions.])
m4_p([dnl
The m4_refT(dbh_fd) only supports a coarse-grained form of locking.
Applications should instead use the m4_db lock manager where possible.])
m4_return(dbh_fd, std)
m4_parambegin
m4_param_co(fdp, current file descriptor)
m4_paramend
m4_seealso(Db)
m4_page_footer

178
docs_src/db/db_get.so Normal file
View File

@@ -0,0 +1,178 @@
m4_comment([$Id: db_get.so,v 10.95 2007/11/07 16:51:38 bostic Exp $])
define(M4PAGELOCAL,
[dbh_get, dbh_pget, DB_CONSUME, DB_CONSUME_WAIT, DB_GET_BOTH,
DB_IGNORE_LEASE, DB_MULTIPLE, DB_SET_RECNO])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_get),
ifelse(M4API, C_API, [dnl
int
DB-__GT__get(DB *db,
DB_TXN *txnid, DBT *key, DBT *data, u_int32_t flags);
m4_blank
int
DB-__GT__pget(DB *db,
DB_TXN *txnid, DBT *key, DBT *pkey, DBT *data, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::get(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);
m4_blank
int
Db::pget(DbTxn *txnid, Dbt *key, Dbt *pkey, Dbt *data, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_get) retrieves key/data pairs from the database. The
address and length of the data associated with the specified m4_arg(key)
are returned in the structure to which m4_arg(data) refers.])
m4_p([dnl
In the presence of duplicate key values, m4_ref(dbh_get) will return the
first data item for the designated key. Duplicates are sorted by insert
order, except where this order has been overridden by cursor operations.
m4_bold([Retrieval of duplicates requires the use of cursor operations.])
See m4_ref(dbc_get) for details.])
m4_p([dnl
When called on a database that has been made into a secondary index
using the m4_refT(dbh_associate), the m4_ref(dbh_get) and
m4_refT(dbh_pget)s return the key from the secondary index and the data
item from the primary database. In addition, the m4_refT(dbh_pget)
returns the key from the primary database. In databases that are not
secondary indices, the m4_refT(dbh_pget) will always fail.])
m4_return(dbh_get,
specific, DB_NOTFOUND, [if the specified key is not in the database],
specific, DB_KEYEMPTY, [if the database is a Queue or Recno database and
the specified key exists, but was never explicitly created by the
application or was later deleted], prev)
m4_parambegin
m4_param_data
m4_param(flags, [dnl
m4_sf_zmust(1)
m4_tagbegin
m4_tag(m4_idef(DB_CONSUME), [dnl
Return the record number and data from the available record closest to
the head of the queue, and delete the record. The record number will
be returned in m4_arg(key), as described in m4_ref(Dbt). The data will
be returned in the m4_arg(data) parameter. A record is available if it
is not deleted and is not currently locked. The underlying database
must be of type Queue for m4_ref(DB_CONSUME) to be specified.])
m4_tag(m4_idef(DB_CONSUME_WAIT), [dnl
The m4_ref(DB_CONSUME_WAIT) flag is the same as the m4_ref(DB_CONSUME)
flag, except that if the Queue database is empty, the thread of control
will wait until there is data in the queue before returning. The
underlying database must be of type Queue for m4_ref(DB_CONSUME_WAIT)
to be specified.
m4_p([dnl
If lock or transaction timeouts have been specified, the m4_refT(dbh_get)
with the m4_ref(DB_CONSUME_WAIT) flag
ifelse(M4EXCEPT, except_return, [dnl
may return m4_ref(DB_LOCK_NOTGRANTED) or throw a
m4_ref(DbLockNotGrantedException) exception.],
M4EXCEPT, except_err, [dnl
may throw a m4_ref(DbLockNotGrantedException) exception.],[dnl
may return m4_ref(DB_LOCK_NOTGRANTED).])
This failure, by itself, does not require the enclosing transaction be
aborted.])])
m4_tag(m4_idef(DB_GET_BOTH), [dnl
Retrieve the key/data pair only if both the key and data match the
arguments.
m4_p([dnl
When used with the m4_refT(dbh_pget) version of this method on a
secondary index handle, return the secondary key/primary key/data tuple
only if both the primary and secondary keys match the arguments. It is
an error to use the m4_ref(DB_GET_BOTH) flag with the m4_ref(dbh_get)
version of this method and a secondary index handle.])])
m4_tag(m4_idef(DB_SET_RECNO), [dnl
Retrieve the specified numbered key/data pair from a database. Upon
return, both the m4_arg(key) and m4_arg(data) items will have been
filled in.
m4_p([dnl
The m4_arg(data) field of the specified m4_arg(key) must be a pointer
to a logical record number (that is, a m4_arg(db_recno_t)). This record
number determines the record to be retrieved.])
m4_p([dnl
For m4_ref(DB_SET_RECNO) to be specified, the underlying database must be
of type Btree, and it must have been created with the DB_RECNUM flag.])])
m4_tagend
m4_sf_or_add(1)
m4_tagbegin
m4_tag(m4_idef(DB_IGNORE_LEASE), [dnl
Return the data item irrespective of the state of master leases. The
item will be returned under all conditions: if master leases are not
configured, if the request is made to a client, if the request is made
to a master with a valid lease, or if the request is made to a master
without a valid lease.])
m4_tag(m4_idef(DB_MULTIPLE), [dnl
Return multiple data items in the buffer to which the m4_arg(data)
parameter refers.
m4_p([dnl
In the case of Btree or Hash databases, all of the data items associated
with the specified key are entered into the buffer. In the case of
Queue or Recno databases, all of the data items in the database,
starting at, and subsequent to, the specified key, are entered into the
buffer.])
m4_p([dnl
m4_bulk_mem])
m4_p([dnl
The m4_ref(DB_MULTIPLE) flag may only be used alone, or with the
m4_ref(DB_GET_BOTH) and m4_ref(DB_SET_RECNO) options. The
m4_ref(DB_MULTIPLE) flag may not be used when accessing databases made
into secondary indices using the m4_refT(dbh_associate).])
m4_p([dnl
See
ifelse(M4API, C_API, m4_ref(DB_MULTIPLE_INIT), m4_ref(DbMultipleDataIterator))
for more information.])])
m4_tag(m4_idef(DB_READ_COMMITTED), [dnl
Configure a transactional get operation to have degree 2 isolation (the
read is not repeatable).])
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
Configure a transactional get operation to have degree 1 isolation,
reading modified but not yet committed data. Silently ignored if the
m4_ref(DB_READ_UNCOMMITTED) flag was not specified when the underlying
database was opened.])
m4_rmw_flag([Because the m4_refT(dbh_get) will not hold locks across
m4_db calls in non-transactional operations, the m4_ref(DB_RMW) flag
to the m4_ref(dbh_get) call is meaningful only in the presence of
transactions.])
m4_tagend])
m4_param_key
m4_param(pkey, [dnl
The m4_arg(pkey) parameter is the return key from the primary database.])
m4_param_txn(dbh_get)
m4_paramend
m4_err(dbh_get,
buffersmall,
[requested item could not be returned due to undersized buffer],
deadlock,
locknotgranted,
[m4_ref(DB_CONSUME_WAIT) flag was specified, lock or transaction
timers were configured and the],
rephandle, replease, replockout, secondary_bad, einval,
[a record number of 0 was specified;
the m4_ref(DB_THREAD) flag was specified to the m4_refT(dbh_open) and
none of the m4_ref(DB_DBT_MALLOC), m4_ref(DB_DBT_REALLOC) or
m4_ref(DB_DBT_USERMEM) flags were set in the m4_ref(Dbt);
the m4_refT(dbh_pget) was called with a m4_ref(Db) handle that does not
refer to a secondary index])
m4_seealso(Db)
m4_page_footer

41
docs_src/db/db_get_byteswapped.so Normal file
View File

@@ -0,0 +1,41 @@
m4_comment([$Id: db_get_byteswapped.so,v 10.24 2007/09/21 20:06:01 bostic Exp $])
define(M4PAGELOCAL, dbh_get_byteswapped)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_get_byteswapped),
ifelse(M4API, C_API, [dnl
int
DB-__GT__get_byteswapped(DB *db, int *isswapped);
])
ifelse(M4API, CXX_API, [dnl
int
Db::get_byteswapped(int *isswapped);
]))
m4_p([dnl
The m4_refT(dbh_get_byteswapped) returns if the underlying database
files were created on an architecture of the same byte order as the
current one, or if they were not (that is, big-endian on a little-endian
machine, or vice versa). This information may be used to determine
whether application data needs to be adjusted for this architecture or
not.])
m4_when(dbh_get_byteswapped, before, dbh_open)
m4_return(dbh_get_byteswapped, std)
m4_parambegin
m4_param(isswapped, [dnl
If the underlying database files were created on an architecture of the
same byte order as the current one. 0 is stored into the memory location
referenced by m4_arg(isswapped). If the underlying database files were
created on an architecture of a different byte order as the current one,
1 is stored into the memory location referenced by m4_arg(isswapped).])
m4_paramend
m4_err(dbh_get_byteswapped,
einval, [the method was called before m4_ref(dbh_open) was called])
m4_seealso(Db)
m4_page_footer

20
docs_src/db/db_get_mpf.so Normal file
View File

@@ -0,0 +1,20 @@
m4_comment([$Id: db_get_mpf.so,v 1.8 2005/07/20 16:22:18 bostic Exp $])
define(M4PAGELOCAL, dbh_get_mpf)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_get_mpf),
ifelse(M4API, C_API, [dnl
DB_MPOOLFILE *
DB-__GT__get_mpf(DB *db);
])
ifelse(M4API, CXX_API, [dnl
DbMpoolFile *
Db::get_mpf();
]))
m4_getter(dbh_get_mpf,
[handle for the cache file underlying the database])
m4_seealso(Db)
m4_page_footer

35
docs_src/db/db_get_type.so Normal file
View File

@@ -0,0 +1,35 @@
m4_comment([$Id: db_get_type.so,v 10.28 2007/09/21 20:06:01 bostic Exp $])
define(M4PAGELOCAL, dbh_get_type)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_get_type),
ifelse(M4API, C_API, [dnl
int
DB-__GT__get_type(DB *db, DBTYPE *type);
])
ifelse(M4API, CXX_API, [dnl
int
Db::get_type(DBTYPE *type);
]))
m4_p([dnl
The m4_refT(dbh_get_type) returns the type of the underlying access
method (and file format). The type value is one of DB_BTREE, DB_HASH,
DB_RECNO, or DB_QUEUE. This value may be used to determine the type of
the database after a return from m4_ref(dbh_open) with the m4_arg(type)
parameter set to DB_UNKNOWN.])
m4_when(dbh_get_type, before, dbh_open)
m4_return(dbh_get_type, std)
m4_parambegin
m4_param_co(type, [type of the underlying access method])
m4_paramend
m4_err(dbh_get_type,
einval, [the method was called before m4_ref(dbh_open) was called])
m4_seealso(Db)
m4_page_footer

20
docs_src/db/db_getenv.so Normal file
View File

@@ -0,0 +1,20 @@
m4_comment([$Id: db_getenv.so,v 10.9 2005/07/20 16:22:49 bostic Exp $])
define(M4PAGELOCAL, dbh_getenv)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_getenv),
ifelse(M4API, C_API, [dnl
DB_ENV *
DB-__GT__get_env(DB *db);
])
ifelse(M4API, CXX_API, [dnl
DbEnv *
Db::get_env();
]))
m4_getter(dbh_getenv,
[handle for the database environment underlying the database])
m4_seealso(Db)
m4_page_footer

116
docs_src/db/db_join.so Normal file
View File

@@ -0,0 +1,116 @@
m4_comment([$Id: db_join.so,v 10.60 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL, [dbh_join, DB_JOIN_NOSORT])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_join),
ifelse(M4API, C_API, [dnl
int
DB-__GT__join(DB *primary,
DBC **curslist, DBC **dbcp, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::join(Dbc **curslist, Dbc **dbcp, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_join) creates a specialized join cursor for use in
performing equality or natural joins on secondary indices. For
information on how to organize your data to use this functionality, see
m4_link(M4RELDIR/ref/am/join, [Equality join]).])
m4_p([dnl
The m4_refT(dbh_join) method is called using the m4_ref(Db) handle of
the primary database.])
m4_p([dnl
The join cursor supports only the m4_ref(dbc_get) and m4_arg(dbc_close)
cursor functions:])
m4_tagbegin
m4_tag(m4_ref(dbc_get), [dnl
Iterates over the values associated with the keys to which each item in
m4_arg(curslist) was initialized. Any data value that appears in all
items specified by the m4_arg(curslist) parameter is then used as a key
into the m4_arg(primary), and the key/data pair found in the
m4_arg(primary) is returned.
m4_sf_zmust(0)
m4_tagbegin
m4_tag(m4_idef(DB_JOIN_ITEM), [dnl
Do not use the data value found in all the cursors as a lookup key for
the m4_arg(primary), but simply return it in the key parameter instead.
The data parameter is left unchanged.])
m4_tagend
m4_sf_or_add(0)
m4_tagbegin
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
Configure a transactional join operation to have degree 1 isolation,
reading modified but not yet committed data. Silently ignored if the
m4_ref(DB_READ_UNCOMMITTED) flag was not specified when the underlying
database was opened.])
m4_rmw_flag()
m4_tagend])
m4_tag(m4_ref(dbc_close), [dnl
Close the returned cursor and release all resources. (Closing the cursors
in m4_arg(curslist) is the responsibility of the caller.)])
m4_tagend
m4_return(dbh_join, std)
m4_parambegin
m4_param(curslist, [dnl
The m4_arg(curslist) parameter contains a NULL terminated array of cursors.
Each cursor must have been initialized to refer to the key on which the
underlying database should be joined. Typically, this initialization is done
by a m4_ref(dbc_get) call with the m4_ref(DB_SET) flag specified. Once the
cursors have been passed as part of a m4_arg(curslist), they should not
be accessed or modified until the newly created join cursor has been closed,
or else inconsistent results may be returned.
m4_p([dnl
Joined values are retrieved by doing a sequential iteration over the first
cursor in the m4_arg(curslist) parameter, and a nested iteration over each
secondary cursor in the order they are specified in the m4_arg(curslist)
parameter. This requires database traversals to search for the current
datum in all the cursors after the first. For this reason, the best join
performance normally results from sorting the cursors from the one that
refers to the least number of data items to the one that refers to the
most. By default, m4_ref(dbh_join) does this sort on behalf of its caller.])
m4_p([dnl
For the returned join cursor to be used in a transaction-protected manner,
the cursors listed in m4_arg(curslist) must have been created within the
context of the same transaction.])])
m4_param(dbcp, [dnl
The newly created join cursor is returned in the memory location to
which m4_arg(dbcp) refers.])
m4_param(flags, [dnl
m4_sf_zmust(0)
m4_tagbegin
m4_tag(m4_idef(DB_JOIN_NOSORT), [dnl
Do not sort the cursors based on the number of data items to which they
refer. If the data are structured so that cursors with many data items
also share many common elements, higher performance will result from
listing those cursors before cursors with fewer data items; that is, a
sort order other than the default. The m4_ref(DB_JOIN_NOSORT) flag
permits applications to perform join optimization prior to calling
m4_ref(dbh_join).])
m4_tagend])
m4_paramend
m4_err(dbh_join, rephandle, replockout, secondary_bad, einval,
[cursor methods other than m4_ref(dbc_get) or m4_ref(dbc_close) were
called])
m4_seealso(Db)
m4_page_footer

71
docs_src/db/db_key_range.so Normal file
View File

@@ -0,0 +1,71 @@
m4_comment([$Id: db_key_range.so,v 10.24 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL, dbh_key_range)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_key_range),
ifelse(M4API, C_API, [dnl
int
DB-__GT__key_range(DB *db, DB_TXN *txnid,
DBT *key, DB_KEY_RANGE *key_range, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::key_range(DbTxn *txnid
Dbt *key, DB_KEY_RANGE *key_range, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_key_range) returns an estimate of the proportion of keys
that are less than, equal to, and greater than the specified key. The
underlying database must be of type Btree.])
m4_p([dnl
The m4_refT(dbh_key_range) fills in a structure of type DB_KEY_RANGE. The
following data fields are available from the DB_KEY_RANGE structure:])
m4_tagbegin
m4_field(double, less,
[A value between 0 and 1, the proportion of keys less than the specified
key.])
m4_field(double, equal,
[A value between 0 and 1, the proportion of keys equal to the specified
key.])
m4_field(double, greater,
[A value between 0 and 1, the proportion of keys greater than the
specified key.])
m4_tagend
m4_p([dnl
Values are in the range of 0 to 1; for example, if the field
m4_arg(less) is 0.05, 5% of the keys in the database are less than the
m4_arg(key) parameter. The value for m4_arg(equal) will be zero if
there is no matching key, and will be non-zero otherwise.])
m4_return(dbh_key_range, std)
m4_parambegin
m4_param_key
m4_param(key_range, [dnl
The estimates are returned in the m4_arg(key_range) parameter, which
contains three elements of type double: m4_arg(less), m4_arg(equal), and
m4_arg(greater). Values are in the range of 0 to 1; for example, if the
field m4_arg(less) is 0.05, 5% of the keys in the database are less than
the m4_arg(key) parameter. The value for m4_arg(equal) will be zero if
there is no matching key, and will be non-zero otherwise.])
m4_param_txn(dbh_key_range,, [dnl
The m4_refT(dbh_key_range) does not retain the locks it acquires for the
life of the transaction, so estimates may not be repeatable.])
m4_unusedflags
m4_paramend
m4_err(dbh_key_range, deadlock, rephandle, replockout,
einval, [the underlying database was not of type Btree])
m4_seealso(Db)
m4_page_footer

7
docs_src/db/db_list.so Normal file
View File

@@ -0,0 +1,7 @@
m4_comment([$Id: db_list.so,v 1.1 2002/08/30 20:00:48 bostic Exp $])
m4_page_title([m4_db: Databases and Related Methods])
include(db/m4.methods)
m4_page_footer

245
docs_src/db/db_open.so Normal file
View File

@@ -0,0 +1,245 @@
m4_comment([$Id: db_open.so,v 10.124 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL, [dnl
dbh_open, dbh_get_file, dbh_get_dbname, dbh_get_transactional,
dbh_get_open_flags, dbh_get_transactional, DB_BTREE, DB_CREATE,
DB_EXCL, DB_HASH, DB_MULTIVERSION, DB_QUEUE,
DB_READ_UNCOMMITTED, DB_RECNO, DB_TRUNCATE, DB_UNKNOWN])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_open),
ifelse(M4API, C_API, [dnl
int
DB-__GT__open(DB *db, DB_TXN *txnid, const char *file,
const char *database, DBTYPE type, u_int32_t flags, int mode);
m4_blank
int
DB-__GT__get_dbname(DB *db, const char **filenamep, const char **dbnamep);
m4_blank
int
DB-__GT__get_multiple(DB *db);
m4_blank
int
DB-__GT__get_open_flags(DB *db, u_int32_t *flagsp);
m4_blank
int
DB-__GT__get_transactional(DB *db);
])
ifelse(M4API, CXX_API, [dnl
int
Db::open(DbTxn *txnid, const char *file,
const char *database, DBTYPE type, u_int32_t flags, int mode);
m4_blank
int
Db::get_dbname(const char **filenamep, const char **dbnamep);
m4_blank
int
Db::get_multiple()
m4_blank
int
Db::get_open_flags(u_int32_t *flagsp);
m4_blank
int
Db::get_transactional()
]))
m4_p([dnl
The m4_refT(dbh_open) opens the database represented by the m4_arg(file)
and m4_arg(database) parameters for both reading and writing.])
m4_p([dnl
The currently supported m4_db file formats (or m4_italic(access
methods)) are Btree, Hash, Queue, and Recno. The Btree format is a
representation of a sorted, balanced tree structure. The Hash format
is an extensible, dynamic hashing scheme. The Queue format supports
fast access to fixed-length records accessed sequentially or by logical
record number. The Recno format supports fixed- or variable-length
records, accessed sequentially or by logical record number, and
optionally backed by a flat text file.])
m4_p([dnl
Storage and retrieval for the m4_db access methods are based on key/data
pairs; see m4_ref(Dbt) for more information.])
m4_p([dnl
Calling m4_ref(dbh_open) is a relatively expensive operation, and
maintaining a set of open databases will normally be preferable to
repeatedly opening and closing the database for each new query.])
m4_return(dbh_open, std, [dnl
If m4_ref(dbh_open) fails, the m4_refT(dbh_close) must be called to
discard the m4_ref(Db) handle.])
m4_parambegin
m4_param(database, [dnl
The m4_arg(database) parameter is optional, and allows applications to
have multiple databases in a single file. Although no m4_arg(database)
parameter needs to be specified, it is an error to attempt to open a
second database in a m4_arg(file) that was not initially created using
a m4_arg(database) name. Further, the m4_arg(database) parameter is not
supported by the Queue format. Finally, when opening multiple databases
in the same physical file, it is important to consider locking and
memory cache issues; see m4_link(M4RELDIR/ref/am/opensub, Opening
multiple databases in a single file) for more information.
m4_p([dnl
In-memory databases never intended to be preserved on disk may be
created by setting the m4_arg(file) parameter to NULL. If the
m4_arg(database) parameter is also NULL, the database is strictly
temporary and cannot be opened by any other thread of control, thus the
database can only be accessed by sharing the single database handle that
created it, in circumstances where doing so is safe. If the
m4_arg(database) parameter is not set to NULL, the database can be opened
by other threads of control and will be replicated to client sites in
any replication group.])])
m4_param_utf8(file, [dnl
The m4_arg(file) parameter is used as the name of an underlying file that
will be used to back the database; see m4_link(M4RELDIR/ref/env/naming,
File naming) for more information.
m4_p([dnl
In-memory databases never intended to be preserved on disk may be
created by setting the m4_arg(file) parameter to NULL.])])
m4_param(flags, [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_AUTO_COMMIT), [dnl
Enclose the m4_ref(dbh_open) call within a transaction. If the call
succeeds, the open operation will be recoverable and all subsequent
database modification operations based on this handle will be
transactionally protected. If the call fails, no database will have
been created.])
m4_tag(m4_idef(DB_CREATE), [dnl
Create the database. If the database does not already exist and the
DB_CREATE flag is not specified, the m4_ref(dbh_open) will fail.])
m4_tag(m4_idef(DB_EXCL), [dnl
Return an error if the database already exists. The m4_ref(DB_EXCL)
flag is only meaningful when specified with the m4_ref(DB_CREATE)
flag.])
m4_tag(m4_idef(DB_MULTIVERSION), [dnl
Open the database with support for m4_link(M4RELDIR/ref/transapp/read,
multiversion concurrency control). This will cause updates to the
database to follow a copy-on-write protocol, which is required to
support snapshot isolation. The m4_ref(DB_MULTIVERSION) flag requires
that the database be transactionally protected during its open and is
not supported by the queue format.])
m4_tag(m4_idef(DB_NOMMAP), [dnl
Do not map this database into process memory (see the
m4_refT(dbenv_set_mp_mmapsize) for further information).])
m4_tag(m4_idef(DB_RDONLY), [dnl
Open the database for reading only. Any attempt to modify items in the
database will fail, regardless of the actual permissions of any
underlying files.])
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
Support transactional read operations with degree 1 isolation. Read
operations on the database may request the return of modified but not
yet committed data. This flag must be specified on all m4_ref(Db)
handles used to perform dirty reads or database updates, otherwise
requests for dirty reads may not be honored and the read may block.])
m4_tag(m4_idef(DB_THREAD), [dnl
Cause the m4_ref(Db) handle returned by m4_ref(dbh_open) to be
m4_italic(free-threaded); that is, concurrently usable by multiple
threads in the address space.])
ifelse(dbh_open, dbh_open, [dnl
m4_tag(m4_idef(DB_TRUNCATE), [dnl
Physically truncate the underlying file, discarding all previous
databases it might have held. Underlying filesystem primitives are used
to implement this flag. For this reason, it is applicable only to the
file and cannot be used to discard databases within a file.
m4_p([dnl
The m4_ref(DB_TRUNCATE) flag cannot be lock or transaction-protected,
and it is an error to specify it in a locking or transaction-protected
environment.])])])
m4_tagend])
m4_param_filemode([the database open])
m4_param_txn(dbh_open, auto, [dnl
Note that transactionally protected operations on a m4_ref(Db) handle
requires the m4_ref(Db) handle itself be transactionally protected
during its open. Also note that the transaction must be committed before
the handle is closed; see m4_link(M4RELDIR/ref/program/scope, m4_db
handles) for more information.])
define(__m4_type, [dnl
The m4_arg(type) parameter is of type DBTYPE, and must be set to one of
m4_idef(DB_BTREE), m4_idef(DB_HASH), m4_idef(DB_QUEUE),
m4_idef(DB_RECNO), or m4_idef(DB_UNKNOWN). If m4_arg(type) is
DB_UNKNOWN, the database must already exist and m4_ref(dbh_open) will
automatically determine its type. The m4_refT(dbh_get_type) may be used
to determine the underlying type of databases opened using DB_UNKNOWN.])
m4_param(type, [dnl
__m4_type])
m4_paramend
m4_header([Environment Variables])
m4_data_location(dbh_open, 1)
m4_tagbegin
m4_tag(TMPDIR, [dnl
If the m4_arg(file) and m4_arg(dbenv) parameters to m4_ref(dbh_open) are
NULL, the environment variable m4_envvar(TMPDIR) may be used as a
directory in which to create temporary backing files])
m4_tagend
m4_err(dbh_open, deadlock, filenotfound,
DB_OLD_VERSION,
[The database cannot be opened without being first upgraded.],
EEXIST,
[m4_ref(DB_CREATE) and m4_ref(DB_EXCL) were specified and the database exists.],
einval,
[an unknown database type, page size, hash function, pad byte, byte
order, or a flag value or parameter that is incompatible with the
specified database was specified;
the m4_ref(DB_THREAD) flag was specified and fast mutexes are not
available for this architecture;
the m4_ref(DB_THREAD) flag was specified to m4_ref(dbh_open), but was
not specified to the m4_ref(dbenv_open) call for the environment in
which the m4_ref(Db) handle was created;
a backing flat text file was specified with either the m4_ref(DB_THREAD)
flag or the provided database environment supports transaction
processing],
ENOENT,
[A nonexistent m4_arg(re_source) file was specified.], rephandle, replockout)
m4_pf_description(m4_ref(dbh_get_dbname))
m4_p([dnl
The m4_refT(dbh_get_dbname) returns the current filename and database
name.])
m4_parambegin
m4_param_co(filenamep, current filename, REF)
m4_param_co(dbnamep, current database name, REF)
m4_paramend
m4_when_any(dbh_get_dbname)
m4_return(dbh_get_dbname, std)
m4_pf_description(m4_ref(dbh_get_multiple))
m4_p([dnl
The m4_refT(dbh_get_multiple) returns non-zero if the m4_ref(Db) handle
references a physical file supporting multiple databases.])
m4_p([dnl
In this case, the m4_ref(Db) handle is a handle on a database whose key
values are the names of the databases stored in the physical file and
whose data values are opaque objects. No keys or data values may be
modified or stored using the database handle.])
m4_when(dbh_get_multiple, before, dbh_open)
m4_pf_getter(dbh_get_open_flags, [current open method flags],, flagsp)
m4_pf_description(m4_ref(dbh_get_transactional))
m4_p([dnl
The m4_refT(dbh_get_transactional) returns non-zero if the m4_ref(Db)
handle has been opened in a transactional mode.])
m4_when_any(dbh_get_transactional)
m4_seealso(Db)
m4_page_footer

84
docs_src/db/db_put.so Normal file
View File

@@ -0,0 +1,84 @@
m4_comment([$Id: db_put.so,v 10.60 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL, [dbh_put, DB_APPEND, DB_NODUPDATA, DB_NOOVERWRITE])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_put),
ifelse(M4API, C_API, [dnl
int
DB-__GT__put(DB *db,
DB_TXN *txnid, DBT *key, DBT *data, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::put(DbTxn *txnid, Dbt *key, Dbt *data, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_put) stores key/data pairs in the database. The default
behavior of the m4_ref(dbh_put) function is to enter the new key/data
pair, replacing any previously existing key if duplicates are disallowed,
or adding a duplicate data item if duplicates are allowed. If the database
supports duplicates, the m4_refT(dbh_put) adds the new data value at the
end of the duplicate set. If the database supports sorted duplicates,
the new data value is inserted at the correct sorted location.])
m4_return(dbh_put, prev)
m4_parambegin
m4_param(flags, [dnl
m4_sf_zmust(1)
m4_tagbegin
m4_tag(m4_idef(DB_APPEND), [dnl
Append the key/data pair to the end of the database. For the
DB_APPEND flag to be specified, the underlying database must be
a Queue or Recno database. The record number allocated to the record is
returned in the specified m4_arg(key).
m4_p([dnl
There is a minor behavioral difference between the Recno and Queue access
methods for the m4_ref(DB_APPEND) flag. If a transaction enclosing a
m4_ref(dbh_put) operation with the m4_ref(DB_APPEND) flag aborts, the
record number may be decremented (and later reallocated by a subsequent
m4_ref(DB_APPEND) operation) by the Recno access method, but will not be
decremented or reallocated by the Queue access method.])])
m4_tag(m4_idef(DB_NODUPDATA), [dnl
In the case of the Btree and Hash access methods, enter the new key/data
pair only if it does not already appear in the database.
m4_p([dnl
The DB_NODUPDATA flag may only be specified if the underlying
database has been configured to support sorted duplicates. The
DB_NODUPDATA flag may not be specified to the Queue or Recno
access methods.])
m4_return(dbh_put, specific, DB_KEYEXIST,
[if m4_ref(DB_NODUPDATA) is set and the key/data pair already appears
in the database])])
m4_tag(m4_idef(DB_NOOVERWRITE), [dnl
Enter the new key/data pair only if the key does not already appear in the
database. The m4_refT(dbh_put) call with the DB_NOOVERWRITE flag
set will fail if the key already exists in the database, even if the database
supports duplicates.
m4_return(dbh_put, specific, DB_KEYEXIST,
[if m4_ref(DB_NOOVERWRITE) is set and the key already appears in the
database])])
m4_tagend])
m4_param_data
m4_param_key
m4_param_txn(dbh_put)
m4_paramend
m4_idefz(DB_REP_HANDLE_DEAD)
m4_idefz(DB_REP_LOCKOUT)
m4_err(dbh_put, deadlock, rephandle, replockout, readonly, einval,
[a record number of 0 was specified;
an attempt was made to add a record to a fixed-length database that was too
large to fit;
an attempt was made to do a partial put;
an attempt was made to add a record to a secondary index],
ENOSPC, [A btree exceeded the maximum btree depth (255).])
m4_seealso(Db)
m4_page_footer

4
docs_src/db/db_remove.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_remove.so,v 10.3 2002/08/18 21:15:51 bostic Exp $])
define(M4INTERFACE, dbh_remove)
include(env/env_dbremove.so)

4
docs_src/db/db_rename.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_rename.so,v 10.3 2002/08/18 21:15:51 bostic Exp $])
define(M4INTERFACE, dbh_rename)
include(env/env_dbrename.so)

4
docs_src/db/db_set_alloc.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_alloc.so,v 10.3 2002/08/18 21:15:51 bostic Exp $])
define(M4INTERFACE, dbh_set_alloc)
include(env/env_set_alloc.so)

72
docs_src/db/db_set_append_recno.so Normal file
View File

@@ -0,0 +1,72 @@
m4_comment([$Id: db_set_append_recno.so,v 1.24 2006/05/17 20:47:46 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_append_recno, DB_DBT_APPMALLOC])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_append_recno),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_append_recno(DB *,
int (*db_append_recno_fcn)(DB *dbp, DBT *data, db_recno_t recno));
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_append_recno(
int (*db_append_recno_fcn)(DB *dbp, Dbt *data, db_recno_t recno));
]))
define(__dbAppendRecno_param, [dnl
ifelse([$1], internal, [dnl
The m4_arg(db_append_recno_fcn) parameter is a function to call after
the record number has been selected but before the data has been stored
into the database. The function takes three parameters:
m4_tagbegin
m4_tag(m4_arg(db), [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_tag(m4_arg(dbt), [dnl
The m4_arg(dbt) parameter is the data m4_ref(Dbt) to be stored.])
m4_tag(m4_arg(recno), [dnl
The m4_arg(recno) parameter is the generated record number.])
m4_tagend],[dnl
m4_parambegin
m4_param(db, [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_param(data, [dnl
The m4_arg(data) parameter is the data m4_ref(Dbt) to be stored.])
m4_param(recno, [dnl
The m4_arg(recno) parameter is the generated record number.])
m4_paramend])
m4_p([dnl
The called function may modify the data m4_ref(Dbt). If the function
needs to allocate memory for the m4_arg(data) field, the m4_arg(flags)
field of the returned m4_ref(Dbt) should be set to
m4_ref(DB_DBT_APPMALLOC), which indicates that m4_db should free the
memory when it is done with it.])])
define(__dbAppendRecno_return, [dnl
The callback function must return 0 on success and m4_envvar(errno) or
a value outside of the m4_db error name space on failure.])
m4_p([dnl
When using the m4_ref(DB_APPEND) option of the m4_ref(dbh_put) method,
it may be useful to modify the stored data based on the generated key.
If a callback function is specified using the
m4_refT(dbh_set_append_recno), it will be called after the record number
has been selected, but before the data has been stored.])
m4_scope_dbh(dbh_set_append_recno)
m4_when_dbopen(dbh_set_append_recno)
m4_return(dbh_set_append_recno, std)
m4_parambegin
m4_param(db_append_recno_fcn, [dnl
__dbAppendRecno_param(internal)
m4_p([__dbAppendRecno_return])
m4_not_reentrant])
m4_paramend
m4_err(dbh_set_append_recno,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_seealso(Db)
m4_page_footer

70
docs_src/db/db_set_bt_compare.so Normal file
View File

@@ -0,0 +1,70 @@
m4_comment([$Id: db_set_bt_compare.so,v 10.50 2006/10/26 20:59:24 bostic Exp $])
define(M4PAGELOCAL, dbh_set_bt_compare)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_bt_compare),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_bt_compare(DB *db,
int (*bt_compare_fcn)(DB *db, const DBT *dbt1, const DBT *dbt2));
])
ifelse(M4API, CXX_API, [dnl
extern "C" {
typedef int (*bt_compare_fcn_type)(DB *db, const DBT *dbt1, const DBT *dbt2);
};
int
Db::set_bt_compare(bt_compare_fcn_type bt_compare_fcn);
]))
m4_p([dnl
Set the Btree key comparison function. The comparison function is
called whenever it is necessary to compare a key specified by the
application with a key currently stored in the tree.])
m4_p([dnl
If no comparison function is specified, the keys are compared lexically,
with shorter keys collating before longer keys.])
m4_scope_dbh(dbh_set_bt_compare)
m4_when_dbopen(dbh_set_bt_compare, corrupt)
m4_return(dbh_set_bt_compare, std)
m4_parambegin
m4_param(bt_compare_fcn, [dnl
The m4_arg(bt_compare_fcn) function is the application-specified Btree
comparison function. The comparison function takes three parameters:
m4_tagbegin
m4_tag(m4_arg(db), [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_tag(m4_arg(dbt1), [dnl
The m4_arg(dbt1) parameter is the m4_ref(Dbt) representing the
application supplied key.])
m4_tag(m4_arg(dbt2), [dnl
The m4_arg(dbt2) parameter is the m4_ref(Dbt) representing the
current tree's key.])
m4_tagend])
m4_p([dnl
The m4_arg(bt_compare_fcn) function must return an integer value less
than, equal to, or greater than zero if the first key parameter is
considered to be respectively less than, equal to, or greater than the
second key parameter. In addition, the comparison function must cause
the keys in the database to be m4_italic(well-ordered). The comparison
function must correctly handle any key values used by the application
(possibly including zero-length keys). In addition, when Btree key
prefix comparison is being performed (see m4_ref(dbh_set_bt_prefix) for
more information), the comparison routine may be passed a prefix of any
database key. The m4_arg(data) and m4_arg(size) fields of the
m4_ref(Dbt) are the only fields that may be used for the purposes of
this comparison, and no particular alignment of the memory to which by
the m4_arg(data) field refers may be assumed.])
m4_paramend
m4_err(dbh_set_bt_compare,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_seealso(Db)
m4_page_footer

54
docs_src/db/db_set_bt_minkey.so Normal file
View File

@@ -0,0 +1,54 @@
m4_comment([$Id: db_set_bt_minkey.so,v 10.38 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_bt_minkey, dbh_get_bt_minkey])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_bt_minkey),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_bt_minkey(DB *db, u_int32_t bt_minkey);
m4_blank
int
DB-__GT__get_bt_minkey(DB *db, u_int32_t *bt_minkeyp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_bt_minkey(u_int32_t bt_minkey);
m4_blank
int
Db::get_bt_minkey(u_int32_t *bt_minkeyp);
]))
m4_p([dnl
Set the minimum number of key/data pairs intended to be stored on any
single Btree leaf page.])
m4_p([dnl
This value is used to determine if key or data items will be stored on
overflow pages instead of Btree leaf pages. For more information on
the specific algorithm used, see m4_link(M4RELDIR/ref/am_conf/bt_minkey,
[Minimum keys per page]). The m4_arg(bt_minkey) value specified must
be at least 2; if m4_arg(bt_minkey) is not explicitly set, a value of
2 is used.])
m4_scope_db(dbh_set_bt_minkey)
m4_when_dbopen(dbh_set_bt_minkey, ignored)
m4_return(dbh_set_bt_minkey, std)
m4_parambegin
m4_param(bt_minkey, [dnl
The m4_arg(bt_minkey) parameter is the minimum number of key/data pairs
intended to be stored on any single Btree leaf page.])
m4_paramend
m4_err(dbh_set_bt_minkey,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_bt_minkey,
[minimum number of key/data pairs intended to be stored on any single Btree
leaf page],, bt_minkeyp)
m4_seealso(Db)
m4_page_footer

87
docs_src/db/db_set_bt_prefix.so Normal file
View File

@@ -0,0 +1,87 @@
m4_comment([$Id: db_set_bt_prefix.so,v 10.48 2004/08/13 03:38:56 bostic Exp $])
define(M4PAGELOCAL, dbh_set_bt_prefix)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_bt_prefix),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_bt_prefix(DB *db,
size_t (*bt_prefix_fcn)(DB *, const DBT *, const DBT *));
])
ifelse(M4API, CXX_API, [dnl
extern "C" {
typedef size_t (*bt_prefix_fcn_type)(DB *, const DBT *, const DBT *);
};
int
Db::set_bt_prefix(bt_prefix_fcn_type bt_prefix_fcn);
]))
define(__prefix_param, [dnl
ifelse([$1], internal, [dnl
The m4_arg(bt_prefix_fcn) function is the application-specific Btree
prefix function. The prefix function takes three parameters:
m4_tagbegin
m4_tag(m4_arg(db), [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_tag(m4_arg(dbt1), [dnl
The m4_arg(dbt1) parameter is a m4_ref(Dbt) representing a database key.])
m4_tag(m4_arg(dbt2), [dnl
The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing a database key.])
m4_tagend],[dnl
m4_parambegin
m4_param(db, [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_param(dbt1, [dnl
The m4_arg(dbt1) parameter is a m4_ref(Dbt) representing a database key.])
m4_param(dbt2, [dnl
The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing a database key.])
m4_paramend])])
define(__prefix_return, [dnl
The m4_arg(bt_prefix_fcn) function must return the number of bytes of
the second key parameter that would be required by the Btree key
comparison function to determine the second key parameter's ordering
relationship with respect to the first key parameter. If the two keys
are equal, the key length should be returned. The prefix function must
correctly handle any key values used by the application (possibly
including zero-length keys). The m4_arg(data) and m4_arg(size) fields
of the m4_ref(Dbt) are the only fields that may be used for the purposes
of this determination, and no particular alignment of the memory to
which the m4_arg(data) field refers may be assumed.])
m4_p([dnl
Set the Btree prefix function. The prefix function is used to determine
the amount by which keys stored on the Btree internal pages can be
safely truncated without losing their uniqueness. See the
m4_link(M4RELDIR/ref/am_conf/bt_prefix, Btree prefix comparison) section
of the m4_db Reference Guide for more details about how this works. The
usefulness of this is data-dependent, but can produce significantly
reduced tree sizes and search times in some data sets.])
m4_p([dnl
If no prefix function or key comparison function is specified by the
application, a default lexical comparison function is used as the prefix
function. If no prefix function is specified and a key comparison
function is specified, no prefix function is used. It is an error to
specify a prefix function without also specifying a Btree key comparison
function.])
m4_scope_dbh(dbh_set_bt_prefix)
m4_when_dbopen(dbh_set_bt_prefix, corrupt)
m4_return(dbh_set_bt_prefix, std)
m4_parambegin
m4_param(bt_prefix_fcn, [dnl
__prefix_param(internal)
m4_p([__prefix_return])])
m4_paramend
m4_err(dbh_set_bt_prefix,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_seealso(Db)
m4_page_footer

4
docs_src/db/db_set_cachesize.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_cachesize.so,v 10.21 2002/08/18 21:15:53 bostic Exp $])
define(M4INTERFACE, dbh_set_cachesize)
include(env/env_set_cachesize.so)

83
docs_src/db/db_set_dup_compare.so Normal file
View File

@@ -0,0 +1,83 @@
m4_comment([$Id: db_set_dup_compare.so,v 10.50 2004/08/13 03:38:56 bostic Exp $])
define(M4PAGELOCAL, dbh_set_dup_compare)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_dup_compare),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_dup_compare(DB *db,
int (*dup_compare_fcn)(DB *, const DBT *, const DBT *));
])
ifelse(M4API, CXX_API, [dnl
extern "C" {
typedef int (*dup_compare_fcn_type)(DB *, const DBT *, const DBT *);
};
int
Db::set_dup_compare(dup_compare_fcn_type dup_compare_fcn);
]))
define(__compareDuplicates_param, [dnl
ifelse([$1], internal, [dnl
The m4_arg(dup_compare_fcn) function is the application-specified
duplicate data item comparison function. The function takes three
arguments:
m4_tagbegin
m4_tag(m4_arg(db), [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_tag(m4_arg(dbt1), [dnl
The m4_arg(dbt1) parameter is a m4_ref(Dbt) representing the application
supplied data item.])
m4_tag(m4_arg(dbt2), [dnl
The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing the current
tree's data item.])
m4_tagend],[dnl
m4_parambegin
m4_param(db, [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_param(dbt1, [dnl
The m4_arg(dbt1) parameter is a m4_ref(Dbt) representing the application
supplied data item.])
m4_param(dbt2, [dnl
The m4_arg(dbt2) parameter is a m4_ref(Dbt) representing the current
tree's data item.])
m4_paramend])])
define(__compareDuplicates_return, [dnl
The m4_arg(dup_compare_fcn) function must return an integer value less
than, equal to, or greater than zero if the first data item parameter
is considered to be respectively less than, equal to, or greater than
the second data item parameter. In addition, the comparison function
must cause the data items in the set to be m4_italic(well-ordered). The
comparison function must correctly handle any data item values used by
the application (possibly including zero-length data items). The
m4_arg(data) and m4_arg(size) fields of the m4_ref(Dbt) are the only
fields that may be used for the purposes of this comparison, and no
particular alignment of the memory to which the m4_arg(data) field
refers may be assumed.])
m4_p([dnl
Set the duplicate data item comparison function. The comparison
function is called whenever it is necessary to compare a data item
specified by the application with a data item currently stored in the
database. Calling m4_ref(dbh_set_dup_compare) implies calling
m4_ref(dbh_set_flags) with the m4_ref(DB_DUPSORT) flag.])
m4_p([dnl
If no comparison function is specified, the data items are compared
lexically, with shorter data items collating before longer data items.])
m4_when_dbopen(dbh_set_dup_compare, corrupt)
m4_return(dbh_set_dup_compare, std)
m4_parambegin
m4_param(dup_compare_fcn, [dnl
__compareDuplicates_param(internal)
m4_p([__compareDuplicates_return])])
m4_paramend
m4_err(dbh_set_dup_compare, einval)
m4_seealso(Db)
m4_page_footer

4
docs_src/db/db_set_encrypt.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_encrypt.so,v 10.3 2002/08/18 21:15:54 bostic Exp $])
define(M4INTERFACE, dbh_set_encrypt)
include(env/env_set_encrypt.so)

4
docs_src/db/db_set_errcall.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_errcall.so,v 10.10 2002/08/18 21:15:54 bostic Exp $])
define(M4INTERFACE, dbh_set_errcall)
include(env/env_set_errcall.so)

4
docs_src/db/db_set_errfile.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_errfile.so,v 10.10 2002/08/18 21:15:54 bostic Exp $])
define(M4INTERFACE, dbh_set_errfile)
include(env/env_set_errfile.so)

4
docs_src/db/db_set_error_stream.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_error_stream.so,v 10.2 2002/08/18 21:15:54 bostic Exp $])
define(M4INTERFACE, dbh_set_error_stream)
include(env/env_set_error_stream.so)

4
docs_src/db/db_set_errpfx.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_errpfx.so,v 10.10 2002/08/18 21:15:55 bostic Exp $])
define(M4INTERFACE, dbh_set_errpfx)
include(env/env_set_errpfx.so)

4
docs_src/db/db_set_feedback.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_feedback.so,v 10.29 2003/10/19 01:27:11 bostic Exp $])
define(M4INTERFACE, dbh_set_feedback)
include(env/env_set_feedback.so)

266
docs_src/db/db_set_flags.so Normal file
View File

@@ -0,0 +1,266 @@
m4_comment([$Id: db_set_flags.so,v 10.68 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL,
[dbh_set_flags, dbh_get_flags, DB_CHKSUM, DB_DUP, DB_DUPSORT,
DB_ENCRYPT, DB_INORDER, DB_RECNUM, DB_REVSPLITOFF, DB_RENUMBER,
DB_SNAPSHOT, DB_TXN_NOT_DURABLE])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_flags),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_flags(DB *db, u_int32_t flags);
m4_blank
int
DB-__GT__get_flags(DB *db, u_int32_t *flagsp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_flags(u_int32_t flags);
m4_blank
int Db::get_flags(u_int32_t *flagsp);
]))
define(m4_scope_db_flags, [m4_p([dnl
Calling m4_ref(dbh_set_flags) with the m4_ref($1) flag affects the
database, including all threads of control accessing the database.])])
define(m4_scope_dbh_flags, [m4_p([dnl
Calling m4_ref(dbh_set_flags) with the m4_ref($1) flag only affects the
specified m4_ref(Db) handle (and any other m4_db handles opened within
the scope of that handle).])])
define(m4_db_flag_open, [m4_p([dnl
If the database already exists when m4_ref(dbh_open) is called, the $1
flag
ifelse($2, error, [must be the same as the existing database or an error
will be returned.])
ifelse($2, ignored, [will be ignored.])])])
define(m4_dupflag, [dnl
m4_tag(m4_idef(DB_DUP), [dnl
Permit duplicate data items in the database; that is, insertion when the
key of the key/data pair being inserted already exists in the database
will be successful. The ordering of duplicates in the database is
determined by the order of insertion, unless the ordering is otherwise
specified by use of a cursor operation.
m4_p([dnl
The m4_ref(DB_DUPSORT) flag is preferred to m4_ref(DB_DUP) for
performance reasons. The m4_ref(DB_DUP) flag should only be used by
applications wanting to order duplicate data items manually.])
m4_scope_db_flags(DB_DUP)
m4_db_flag_open(DB_DUP, error)
ifelse([$1],,, m4_p([$1]))])])
define(m4_dupsortflag, [dnl
m4_tag(m4_idef(DB_DUPSORT), [dnl
Permit duplicate data items in the database; that is, insertion when the
key of the key/data pair being inserted already exists in the database
will be successful. The ordering of duplicates in the database is
determined by the duplicate comparison function. If the application
does not specify a comparison function using the
m4_refT(dbh_set_dup_compare), a default lexical comparison will be used.
It is an error to specify both m4_ref(DB_DUPSORT) and m4_ref(DB_RECNUM).
m4_scope_db_flags(DB_DUPSORT)
m4_db_flag_open(DB_DUPSORT, error)])])
m4_p([dnl
Configure a database. Calling m4_ref(dbh_set_flags) is additive; there
is no way to clear flags.])
m4_when_dbopen(dbh_set_flags)
m4_return(dbh_set_flags, std)
m4_parambegin
m4_param(flags, [dnl
m4_sf_or_may
m4_section(General)
m4_p([dnl
The following flags may be specified for any m4_db access method:])
m4_tagbegin
m4_idefz([database page @checksum])
m4_tag(m4_idef(DB_CHKSUM), [dnl
Do checksum verification of pages read into the cache from the backing
filestore. m4_db uses the SHA1 Secure Hash Algorithm
if encryption is configured and a general hash algorithm if it is not.
m4_scope_dbh_flags(DB_CHKSUM)
m4_db_flag_open(DB_CHKSUM, ignored)
If creating additional databases in a file, the checksum behavior specified
must be consistent with the existing databases in the file or an error will
be returned.])
m4_idefz([database @encryption])
m4_tag(m4_idef(DB_ENCRYPT), [dnl
Encrypt the database using the cryptographic password specified to the
m4_ref(dbenv_set_encrypt) or m4_refT(dbh_set_encrypt)s.
m4_scope_dbh_flags(DB_ENCRYPT)
m4_db_flag_open(DB_ENCRYPT, error)
If creating additional databases in a file, the encryption behavior specified
must be consistent with the existing databases in the file or an error will
be returned.
m4_p([dnl
Encrypted databases are not portable between machines of different byte
orders, that is, encrypted databases created on big-endian machines
cannot be read on little-endian machines, and vice versa.])])
m4_idefz([turn off database @durability])
m4_tag(m4_idef(DB_TXN_NOT_DURABLE), [dnl
If set, m4_db will not write log records for this database. This means
that updates of this database exhibit the ACI (atomicity, consistency,
and isolation) properties, but not D (durability); that is, database
integrity will be maintained, but if the application or system fails,
integrity will not persist. The database file must be verified and/or
restored from backup after a failure. In order to ensure integrity
after application shut down, the database handles must be closed without
specifying m4_ref(DB_NOSYNC), or all database changes must be flushed
from the database environment cache using either the
m4_ref(txn_checkpoint) or m4_refT(memp_sync)s. All database handles for
a single physical file must set m4_ref(DB_TXN_NOT_DURABLE), including
database handles for different databases in a physical file.
m4_scope_dbh_flags(DB_TXN_NOT_DURABLE)])
m4_tagend
m4_section(Btree)
m4_p([dnl
The following flags may be specified for the Btree access method:])
m4_tagbegin
m4_idefz([@duplicate data items])
m4_dupflag([It is an error to specify both m4_ref(DB_DUP) and m4_ref(DB_RECNUM).])
m4_idefz([sorted @duplicate data items])
m4_dupsortflag
m4_idefz([accessing Btree records by @record number])
m4_tag(m4_idef(DB_RECNUM), [dnl
Support retrieval from the Btree using record numbers. For more
information, see the m4_ref(DB_SET_RECNO) flag to the m4_ref(dbh_get)
and m4_ref(dbc_get) methods.
m4_p([dnl
Logical record numbers in Btree databases are mutable in the face of
record insertion or deletion. See the m4_ref(DB_RENUMBER) flag in the
Recno access method information for further discussion.])
m4_p([dnl
Maintaining record counts within a Btree introduces a serious point of
contention, namely the page locations where the record counts are
stored. In addition, the entire database must be locked during both
insertions and deletions, effectively single-threading the database for
those operations. Specifying m4_ref(DB_RECNUM) can result in serious
performance degradation for some applications and data sets.])
m4_p([dnl
It is an error to specify both m4_ref(DB_DUP) and m4_ref(DB_RECNUM).])
m4_scope_db_flags(DB_RECNUM)
m4_db_flag_open(DB_RECNUM, error)])
m4_idefz([turn off @reverse splits in Btree databases],
[turn off reverse @splits in Btree databases])
m4_tag(m4_idef(DB_REVSPLITOFF), [dnl
Turn off reverse splitting in the Btree. As pages are emptied in a
database, the m4_db Btree implementation attempts to coalesce empty pages
into higher-level pages in order to keep the database as small as possible
and minimize search time. This can hurt performance in applications
with cyclical data demands; that is, applications where the database grows
and shrinks repeatedly. For example, because m4_db does page-level
locking, the maximum level of concurrency in a database of two pages is far
smaller than that in a database of 100 pages, so a database that has
shrunk to a minimal size can cause severe deadlocking when a new cycle of
data insertion begins.
m4_scope_dbh_flags(DB_REVSPLITOFF)])
m4_tagend
m4_section(Hash)
m4_p([dnl
The following flags may be specified for the Hash access method:])
m4_tagbegin
m4_dupflag
m4_dupsortflag
m4_tagend
m4_section(Queue)
m4_p([dnl
The following flags may be specified for the Queue access method:])
m4_tagbegin
m4_idefz([@ordered retrieval of records from Queue databases])
m4_tag(m4_idef(DB_INORDER), [dnl
The m4_ref(DB_INORDER) flag modifies the operation of the
m4_ref(DB_CONSUME) or m4_ref(DB_CONSUME_WAIT) flags to m4_ref(dbh_get)
to return key/data pairs in order. That is, they will always return
the key/data item from the head of the queue.
m4_p([dnl
The default behavior of queue databases is optimized for multiple
readers, and does not guarantee that record will be retrieved in the
order they are added to the queue. Specifically, if a writing thread
adds multiple records to an empty queue, reading threads may skip some
of the initial records when the next m4_ref(dbh_get) call returns.])
m4_p([dnl
This flag modifies the m4_ref(dbh_get) call to verify that the record
being returned is in fact the head of the queue. This will increase
contention and reduce concurrency when there are many reading threads.])
m4_scope_dbh_flags(DB_INORDER)])
m4_tagend
m4_section(Recno)
m4_p([dnl
The following flags may be specified for the Recno access method:])
m4_tagbegin
m4_idefz([@renumbering records in Recno databases])
m4_tag(m4_idef(DB_RENUMBER), [dnl
Specifying the m4_ref(DB_RENUMBER) flag causes the logical record
numbers to be mutable, and change as records are added to and deleted
from the database. For example, the deletion of record number 4 causes
records numbered 5 and greater to be renumbered downward by one. If a
cursor was positioned to record number 4 before the deletion, it will
refer to the new record number 4, if any such record exists, after the
deletion. If a cursor was positioned after record number 4 before the
deletion, it will be shifted downward one logical record, continuing to
refer to the same record as it did before.
m4_p([dnl
Using the m4_ref(dbh_put) or m4_ref(dbc_put) interfaces to create new
records will cause the creation of multiple records if the record number
is more than one greater than the largest record currently in the
database. For example, creating record 28, when record 25 was previously
the last record in the database, will create records 26 and 27 as well as
28. Attempts to retrieve records that were created in this manner will
result in an error return of m4_ref(DB_KEYEMPTY).])
m4_p([dnl
If a created record is not at the end of the database, all records
following the new record will be automatically renumbered upward by one.
For example, the creation of a new record numbered 8 causes records
numbered 8 and greater to be renumbered upward by one. If a cursor was
positioned to record number 8 or greater before the insertion, it will be
shifted upward one logical record, continuing to refer to the same record
as it did before.])
m4_p([dnl
For these reasons, concurrent access to a Recno database with the
m4_ref(DB_RENUMBER) flag specified may be largely meaningless, although
it is supported.])
m4_scope_db_flags(DB_RENUMBER)
m4_db_flag_open(DB_RENUMBER, error)])
m4_idefz([pre-loading @text files into Recno databases])
m4_tag(m4_idef(DB_SNAPSHOT), [dnl
This flag specifies that any specified m4_arg(re_source) file be read
in its entirety when m4_ref(dbh_open) is called. If this flag is not
specified, the m4_arg(re_source) file may be read lazily.
m4_scope_dbh_flags(DB_SNAPSHOT)])
m4_tagend])
m4_paramend
m4_err(dbh_set_flags, einval)
m4_pf_getter(dbh_get_flags, current flags,, flagsp)
m4_seealso(Db)
m4_page_footer

66
docs_src/db/db_set_h_compare.so Normal file
View File

@@ -0,0 +1,66 @@
m4_comment([$Id: db_set_h_compare.so,v 1.1 2006/10/27 00:28:44 bostic Exp $])
define(M4PAGELOCAL, dbh_set_h_compare)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_h_compare),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_h_compare(DB *db,
int (*compare_fcn)(DB *db, const DBT *dbt1, const DBT *dbt2));
])
ifelse(M4API, CXX_API, [dnl
extern "C" {
typedef int (*compare_fcn_type)(DB *db, const DBT *dbt1, const DBT *dbt2);
};
int
Db::set_h_compare(compare_fcn_type compare_fcn);
]))
m4_p([dnl
Set the Hash key comparison function. The comparison function is called
whenever it is necessary to compare a key specified by the application
with a key currently stored in the database.])
m4_p([dnl
If no comparison function is specified, a byte-by-byte comparison is
performed.])
m4_scope_dbh(dbh_set_h_compare)
m4_when_dbopen(dbh_set_h_compare, corrupt)
m4_return(dbh_set_h_compare, std)
m4_parambegin
m4_param(compare_fcn, [dnl
The m4_arg(compare_fcn) function is the application-specified Hash
comparison function. The comparison function takes three parameters:
m4_tagbegin
m4_tag(m4_arg(db), [dnl
The m4_arg(db) parameter is the enclosing database handle.])
m4_tag(m4_arg(dbt1), [dnl
The m4_arg(dbt1) parameter is the m4_ref(Dbt) representing the
application supplied key.])
m4_tag(m4_arg(dbt2), [dnl
The m4_arg(dbt2) parameter is the m4_ref(Dbt) representing the
current database's key.])
m4_tagend])
m4_p([dnl
The m4_arg(compare_fcn) function must return an integer value less
than, equal to, or greater than zero if the first key parameter is
considered to be respectively less than, equal to, or greater than the
second key parameter. The comparison function must correctly handle any
key values used by the application (possibly including zero-length
keys). The m4_arg(data) and m4_arg(size) fields of the m4_ref(Dbt) are
the only fields that may be used for the purposes of this comparison,
and no particular alignment of the memory to which by the m4_arg(data)
field refers may be assumed.])
m4_paramend
m4_err(dbh_set_h_compare,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_seealso(Db)
m4_page_footer

51
docs_src/db/db_set_h_ffactor.so Normal file
View File

@@ -0,0 +1,51 @@
m4_comment([$Id: db_set_h_ffactor.so,v 10.37 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_h_ffactor, dbh_get_h_ffactor])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_h_ffactor),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_h_ffactor(DB *db, u_int32_t h_ffactor);
int
m4_blank
DB-__GT__get_h_ffactor(DB *db, u_int32_t *h_ffactorp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_h_ffactor(u_int32_t h_ffactor);
m4_blank
int Db::get_h_ffactor(u_int32_t *h_ffactorp);
]))
m4_p([dnl
Set the desired density within the hash table. If no value is
specified, the fill factor will be selected dynamically as pages are
filled.])
m4_scope_db(dbh_set_h_ffactor)
m4_when_dbopen(dbh_set_h_ffactor, ignored)
m4_return(dbh_set_h_ffactor, std)
m4_parambegin
m4_param(h_ffactor, [dnl
The m4_arg(h_ffactor) parameter is the desired density within the hash table.])
m4_p([dnl
The density is an approximation of the number of keys allowed to
accumulate in any one bucket, determining when the hash table grows or
shrinks. If you know the average sizes of the keys and data in your
data set, setting the fill factor can enhance performance. A reasonable
rule computing fill factor is to set it to the following:])
m4_indent([dnl
(pagesize - 32) / (average_key_size + average_data_size + 8)])
m4_paramend
m4_err(dbh_set_h_ffactor,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_h_ffactor, hash table density,, h_ffactorp)
m4_seealso(Db)
m4_page_footer

49
docs_src/db/db_set_h_hash.so Normal file
View File

@@ -0,0 +1,49 @@
m4_comment([$Id: db_set_h_hash.so,v 10.40 2004/08/13 03:38:56 bostic Exp $])
define(M4PAGELOCAL, dbh_set_h_hash)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_h_hash),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_h_hash(DB *db,
u_int32_t (*h_hash_fcn)(DB *, const void *bytes, u_int32_t length));
])
ifelse(M4API, CXX_API, [dnl
extern "C" {
typedef u_int32_t (*h_hash_fcn_type)
(DB *, const void *bytes, u_int32_t length);
};
int
Db::set_h_hash(h_hash_fcn_type h_hash_fcn);
]))
m4_p([dnl
Set a user-defined hash function; if no hash function is specified, a
default hash function is used. Because no hash function performs
equally well on all possible data, the user may find that the built-in
hash function performs poorly with a particular data set.])
m4_scope_dbh(dbh_set_h_hash)
m4_when_dbopen(dbh_set_h_hash, corrupt)
m4_return(dbh_set_h_hash, std)
m4_parambegin
m4_param(h_hash_fcn, [dnl
The m4_arg(h_hash_fcn) parameter is the application-specified hash function.
m4_p([dnl
Application-specified hash functions take a pointer to a byte string and
a length as parameters, and return a value of type m4_bold(u_int32_t).
The hash function must handle any key values used by the application
(possibly including zero-length keys).])])
m4_paramend
m4_err(dbh_set_h_hash,
einval, [the method was called after m4_ref(dbh_open) was called; the
specified hash function differs from the hash function with which the
database was created])
m4_seealso(Db)
m4_page_footer

51
docs_src/db/db_set_h_nelem.so Normal file
View File

@@ -0,0 +1,51 @@
m4_comment([$Id: db_set_h_nelem.so,v 10.36 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_h_nelem, dbh_get_h_nelem])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_h_nelem),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_h_nelem(DB *db, u_int32_t h_nelem);
m4_blank
int
DB-__GT__get_h_nelem(DB *db, u_int32_t *h_nelemp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_h_nelem(u_int32_t h_nelem);
m4_blank
int
Db::get_h_nelem(u_int32_t *h_nelemp);
]))
m4_p([dnl
Set an estimate of the final size of the hash table.])
m4_p([dnl
In order for the estimate to be used when creating the database, the
m4_ref(dbh_set_h_ffactor) method must also be called. If the estimate
or fill factor are not set or are set too low, hash tables will still
expand gracefully as keys are entered, although a slight performance
degradation may be noticed.])
m4_scope_db(dbh_set_h_nelem)
m4_when_dbopen(dbh_set_h_nelem, ignored)
m4_return(dbh_set_h_nelem, std)
m4_parambegin
m4_param(h_nelem, [dnl
The m4_arg(h_nelem) parameter is an estimate of the final size of the
hash table.])
m4_paramend
m4_err(dbh_set_h_nelem,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_h_nelem,
[estimate of the final size of the hash table],, h_nelemp)
m4_seealso(Db)
m4_page_footer

57
docs_src/db/db_set_lorder.so Normal file
View File

@@ -0,0 +1,57 @@
m4_comment([$Id: db_set_lorder.so,v 10.38 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_lorder, dbh_get_lorder])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_lorder),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_lorder(DB *db, int lorder);
m4_blank
int
DB-__GT__get_lorder(DB *db, int *lorderp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_lorder(int lorder);
m4_blank
int
Db::get_lorder(int *lorderp);
]))
m4_p([dnl
Set the byte order for integers in the stored database metadata. The
host byte order of the machine where the m4_db library was compiled will
be used if no byte order is set.])
m4_p([m4_bold([dnl
The access methods provide no guarantees about the byte ordering of the
application data stored in the database, and applications are responsible
for maintaining any necessary ordering.])])
m4_scope_db(dbh_set_lorder)
m4_when_dbopen(dbh_set_lorder, ignored)
If creating additional databases in a single physical file, information
specified to m4_ref(dbh_set_lorder) will be ignored and the byte order
of the existing databases will be used.
m4_return(dbh_set_lorder, std)
m4_parambegin
m4_param(lorder, [dnl
The m4_arg(lorder) parameter should represent the byte order as an
integer; for example, big endian order is the number 4,321, and little
endian order is the number 1,234.])
m4_paramend
m4_err(dbh_set_lorder,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_lorder,
[database byte order; a byte order of 4,321 indicates a big endian
order, and a byte order of 1,234 indicates a little endian order],
[database byte order], lorderp)
m4_seealso(Db)
m4_page_footer

4
docs_src/db/db_set_msg_stream.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_msg_stream.so,v 1.1 2004/07/14 19:30:39 bostic Exp $])
define(M4INTERFACE, dbh_set_message_stream)
include(env/env_set_msg_stream.so)

4
docs_src/db/db_set_msgcall.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_msgcall.so,v 10.1 2004/04/16 19:01:56 bostic Exp $])
define(M4INTERFACE, dbh_set_msgcall)
include(env/env_set_msgcall.so)

4
docs_src/db/db_set_msgfile.so Normal file
View File

@@ -0,0 +1,4 @@
m4_comment([$Id: db_set_msgfile.so,v 1.1 2004/07/14 19:30:39 bostic Exp $])
define(M4INTERFACE, dbh_set_msgfile)
include(env/env_set_msgfile.so)

54
docs_src/db/db_set_pagesize.so Normal file
View File

@@ -0,0 +1,54 @@
m4_comment([$Id: db_set_pagesize.so,v 10.40 2005/12/16 01:19:35 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_pagesize, dbh_get_pagesize])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_pagesize),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_pagesize(DB *db, u_int32_t pagesize);
m4_blank
int
DB-__GT__get_pagesize(DB *db, u_int32_t *pagesizep);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_pagesize(u_int32_t pagesize);
m4_blank
int
Db::get_pagesize(u_int32_t *pagesizep);
]))
m4_p([dnl
Set the size of the pages used to hold items in the database, in bytes.
The minimum page size is 512 bytes, the maximum page size is 64K bytes,
and the page size must be a power-of-two. If the page size is not
explicitly set, one is selected based on the underlying filesystem I/O
block size. The automatically selected size has a lower limit of 512
bytes and an upper limit of 16K bytes.])
m4_p([dnl
For information on tuning the m4_db page size, see
m4_link(M4RELDIR/ref/am_conf/pagesize, [Selecting a page size]).])
m4_scope_db(dbh_set_pagesize)
m4_when_dbopen(dbh_set_pagesize, ignored)
If creating additional databases in a single physical file, information
specified to m4_ref(dbh_set_pagesize) will be ignored and the page size
of the existing databases will be used.
m4_return(dbh_set_pagesize, std)
m4_parambegin
m4_param(pagesize, [dnl
The m4_arg(pagesize) parameter sets the database page size.])
m4_paramend
m4_err(dbh_set_pagesize,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_pagesize, page size,, pagesizep)
m4_seealso(Db)
m4_page_footer

24
docs_src/db/db_set_priority.so Normal file
View File

@@ -0,0 +1,24 @@
m4_comment([$Id: db_set_priority.so,v 1.1 2007/05/22 18:06:05 bostic Exp $])
define(M4INTERFACE, dbh_set_priority)
define(M4PAGELOCAL, [dbh_get_priority, dbh_set_priority,
DB_PRIORITY_VERY_LOW, DB_PRIORITY_LOW, DB_PRIORITY_DEFAULT,
DB_PRIORITY_HIGH, DB_PRIORITY_VERY_HIGH])
m4_pf_header(m4_ref(dbh_set_priority),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_priority(DB *db, DB_CACHE_PRIORITY priority);
m4_blank
int
DB-__GT__get_priority(DB *db, DB_CACHE_PRIORITY *priorityp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_priority(DB_CACHE_PRIORITY priority);
m4_blank
int
Db::get_priority(DB_CACHE_PRIORITY *priorityp);
]))
include(dbc/dbc_set_priority.so)

50
docs_src/db/db_set_q_extentsize.so Normal file
View File

@@ -0,0 +1,50 @@
m4_comment([$Id: db_set_q_extentsize.so,v 1.23 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_q_extentsize, dbh_get_q_extentsize])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_q_extentsize),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_q_extentsize(DB *db, u_int32_t extentsize);
m4_blank
int
DB-__GT__get_q_extentsize(DB *db, u_int32_t *extentsizep);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_q_extentsize(u_int32_t extentsize);
m4_blank
int
Db::get_q_extentsize(u_int32_t *extentsizep);
]))
m4_p([dnl
Set the size of the extents used to hold pages in a Queue database,
specified as a number of pages. Each extent is created as a separate
physical file. If no extent size is set, the default behavior is to
create only a single underlying database file.])
m4_p([dnl
For information on tuning the extent size, see
m4_link(M4RELDIR/ref/am_conf/extentsize, [Selecting a extent size]).])
m4_scope_db(dbh_set_q_extentsize)
m4_when_dbopen(dbh_set_q_extentsize, ignored)
m4_return(dbh_set_q_extentsize, std)
m4_parambegin
m4_param(extentsize, [dnl
The m4_arg(extentsize) parameter is the number of pages in a Queue database
extent.])
m4_paramend
m4_err(dbh_set_q_extentsize,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_q_extentsize, number of pages in an extent,, extentsizep)
m4_seealso(Db)
m4_page_footer

50
docs_src/db/db_set_re_delim.so Normal file
View File

@@ -0,0 +1,50 @@
m4_comment([$Id: db_set_re_delim.so,v 10.39 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_re_delim, dbh_get_re_delim])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_re_delim),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_re_delim(DB *db, int delim);
m4_blank
int
DB-__GT__get_re_delim(DB *db, int *delimp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_re_delim(int re_delim);
m4_blank
int
Db::get_re_delim(int *delimp);
]))
m4_p([dnl
Set the delimiting byte used to mark the end of a record in the backing
source file for the Recno access method.])
m4_p([dnl
This byte is used for variable length records if the m4_arg(re_source)
file is specified. If the m4_arg(re_source) file is specified and no
delimiting byte was specified, m4_htmlquote(newline) characters (that
is, ASCII 0x0a) are interpreted as end-of-record markers.])
m4_scope_db(dbh_set_re_delim)
m4_when_dbopen(dbh_set_re_delim, ignored)
m4_return(dbh_set_re_delim, std)
m4_parambegin
m4_param(re_delim, [dnl
The m4_arg(re_delim) parameter is the delimiting byte used to mark the
end of a record.])
m4_paramend
m4_err(dbh_set_re_delim,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_re_delim, delimiting byte,, delimp)
m4_seealso(Db)
m4_page_footer

61
docs_src/db/db_set_re_len.so Normal file
View File

@@ -0,0 +1,61 @@
m4_comment([$Id: db_set_re_len.so,v 10.40 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_re_len, dbh_get_re_len])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_re_len),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_re_len(DB *db, u_int32_t re_len);
m4_blank
int
DB-__GT__get_re_len(DB *db, u_int32_t *re_lenp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_re_len(u_int32_t re_len);
m4_blank
int
Db::get_re_len(u_int32_t *re_lenp);
]))
m4_p([dnl
For the Queue access method, specify that the records are of length
m4_arg(re_len). For the Queue access method, the record length must be
enough smaller than the database's page size that at least one record
plus the database page's metadata information can fit on each database
page.])
m4_p([dnl
For the Recno access method, specify that the records are fixed-length,
not byte-delimited, and are of length m4_arg(re_len).])
m4_p([dnl
Any records added to the database that are less than m4_arg(re_len) bytes
long are automatically padded (see m4_ref(dbh_set_re_pad) for more
information).])
m4_p([dnl
Any attempt to insert records into the database that are greater than
m4_arg(re_len) bytes long will cause the call to fail immediately and
return an error.])
m4_scope_db(dbh_set_re_len)
m4_when_dbopen(dbh_set_re_len, ignored)
m4_return(dbh_set_re_len, std)
m4_parambegin
m4_param(re_len, [dnl
The m4_arg(re_len) parameter is the length of a Queue or Recno database
record, in bytes.])
m4_paramend
m4_err(dbh_set_re_len,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_re_len, record length,, re_lenp)
m4_seealso(Db)
m4_page_footer

48
docs_src/db/db_set_re_pad.so Normal file
View File

@@ -0,0 +1,48 @@
m4_comment([$Id: db_set_re_pad.so,v 10.37 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_re_pad, dbh_get_re_pad])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_re_pad),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_re_pad(DB *db, int re_pad);
m4_blank
int
DB-__GT__get_re_pad(DB *db, int *re_padp);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_re_pad(int re_pad);
m4_blank
int
Db::get_re_pad(int *re_padp);
]))
m4_p([dnl
Set the padding character for short, fixed-length records for the Queue
and Recno access methods.])
m4_p([dnl
If no pad character is specified, m4_htmlquote(space) characters (that
is, ASCII 0x20) are used for padding.])
m4_scope_db(dbh_set_re_pad)
m4_when_dbopen(dbh_set_re_pad, ignored)
m4_return(dbh_set_re_pad, std)
m4_parambegin
m4_param(re_pad, [dnl
The m4_arg(re_pad) parameter is the pad character for fixed-length
records for the Queue and Recno access methods.])
m4_paramend
m4_err(dbh_set_re_pad,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_re_pad, pad character,, re_padp)
m4_seealso(Db)
m4_page_footer

102
docs_src/db/db_set_re_source.so Normal file
View File

@@ -0,0 +1,102 @@
m4_comment([$Id: db_set_re_source.so,v 10.42 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL, [dbh_set_re_source, dbh_get_re_source])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_set_re_source),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_re_source(DB *db, char *source);
m4_blank
int
DB-__GT__get_re_source(DB *db, const char **sourcep);
])
ifelse(M4API, CXX_API, [dnl
int
Db::set_re_source(char *source);
m4_blank
int
Db::get_re_source(const char **sourcep);
]))
m4_p([dnl
Set the underlying source file for the Recno access method. The purpose
of the m4_arg(source) value is to provide fast access and modification
to databases that are normally stored as flat text files.])
m4_p([dnl
The m4_arg(source) parameter specifies an underlying flat text database
file that is read to initialize a transient record number index. In
the case of variable length records, the records are separated, as
specified by m4_ref(dbh_set_re_delim). For example, standard UNIX byte
stream files can be interpreted as a sequence of variable length records
separated by m4_htmlquote(newline) characters.])
m4_p([dnl
In addition, when cached data would normally be written back to the
underlying database file (for example, the m4_ref(dbh_close) or
m4_ref(dbh_sync) methods are called), the in-memory copy of the database
will be written back to the m4_arg(source) file.])
m4_p([dnl
By default, the backing source file is read lazily; that is, records
are not read from the file until they are requested by the application.
m4_bold([dnl
If multiple processes (not threads) are accessing a Recno database
concurrently, and are either inserting or deleting records, the backing
source file must be read in its entirety before more than a single
process accesses the database, and only that process should specify the
backing source file as part of the m4_ref(dbh_open) call. See the
m4_ref(DB_SNAPSHOT) flag for more information.])])
m4_p([dnl
m4_bold([dnl
Reading and writing the backing source file specified by m4_arg(source)
cannot be transaction-protected because it involves filesystem
operations that are not part of the Db transaction methodology.]) For
this reason, if a temporary database is used to hold the records, it is
possible to lose the contents of the m4_arg(source) file, for
example, if the system crashes at the right instant. If a file is used
to hold the database, normal database recovery on that file can be used
to prevent information loss, although it is still possible that the
contents of m4_arg(source) will be lost if the system crashes.])
m4_p([dnl
The m4_arg(source) file must already exist (but may be zero-length) when
m4_ref(dbh_open) is called.])
m4_p([dnl
It is not an error to specify a read-only m4_arg(source) file when
creating a database, nor is it an error to modify the resulting database.
However, any attempt to write the changes to the backing source file using
either the m4_ref(dbh_sync) or m4_refT(dbh_close)s will fail, of course.
Specify the m4_ref(DB_NOSYNC) flag to the m4_refT(dbh_close) to stop it
from attempting to write the changes to the backing file; instead, they
will be silently discarded.])
m4_p([dnl
For all of the previous reasons, the m4_arg(source) field is generally
used to specify databases that are read-only for m4_db applications;
and that are either generated on the fly by software tools or modified
using a different mechanism -- for example, a text editor.])
m4_scope_dbh(dbh_set_re_source)
m4_when_dbopen(dbh_set_re_source, corrupt)
m4_return(dbh_set_re_source, std)
m4_parambegin
m4_param_utf8(source, [dnl
The backing flat text database file for a Recno database.])
m4_paramend
m4_err(dbh_set_re_source,
einval, [the method was called after m4_ref(dbh_open) was called])
m4_pf_getter(dbh_get_re_source, source file, sourcep,, reference)
m4_seealso(Db)
m4_page_footer

259
docs_src/db/db_stat.so Normal file
View File

@@ -0,0 +1,259 @@
m4_comment([$Id: db_stat.so,v 10.95 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL, [dbh_stat, dbh_stat_print, DB_FAST_STAT])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_stat),
ifelse(M4API, C_API, [dnl
int
DB-__GT__stat(DB *db, DB_TXN *txnid, void *sp, u_int32_t flags);
m4_blank
int
DB-__GT__stat_print(DB *db, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::stat(DbTxn *txnid, void *sp, u_int32_t flags);
m4_blank
int
Db::stat_print(u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_stat) creates a statistical structure and copies a
pointer to it into user-specified memory locations. Specifically, if
m4_arg(sp) is non-NULL, a pointer to the statistics for the database are
copied into the memory location to which it refers.])
m4_parambegin
m4_param(flags, [dnl
m4_sf_zmust(1)
m4_tagbegin
m4_tag(m4_idef(DB_FAST_STAT), [dnl
Return only the values which do not require traversal of the database.
Among other things, this flag makes it possible for applications to
request key and record counts without incurring the performance penalty
of traversing the entire database.])
m4_tag(m4_idef(DB_READ_COMMITTED), [dnl
Database items read during a transactional call will have degree 2
isolation. This ensures the stability of the data items read during the
stat operation but permits that data to be modified or deleted by other
transactions prior to the commit of the specified transaction.])
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
Database items read during a transactional call will have degree 1
isolation, including modified but not yet committed data. Silently
ignored if the m4_ref(DB_READ_UNCOMMITTED) flag was not specified when
the underlying database was opened.]) m4_tagend])
m4_param_txn(dbh_stat)
m4_paramend
m4_alloc([Statistical structures])
m4_p([dnl
If the m4_ref(DB_FAST_STAT) flag has not been specified, the
m4_refT(dbh_stat) will access some of or all the pages in the database,
incurring a severe performance penalty as well as possibly flushing the
underlying buffer pool.])
m4_p([dnl
In the presence of multiple threads or processes accessing an active
database, the information returned by m4_ref(dbh_stat) may be out-of-date.])
m4_p([dnl
If the database was not opened read-only and the m4_ref(DB_FAST_STAT)
flag was not specified, the cached key and record numbers will be
updated after the statistical information has been gathered.])
m4_when(dbh_stat, before, dbh_open)
m4_return(dbh_stat, std)
m4_section([Hash Statistics])
m4_p([dnl
In the case of a Hash database, the statistics are stored in a structure
of type DB_HASH_STAT. The following fields will be filled in:])
m4_tagbegin
m4_field(u_int32_t, hash_magic,
[Magic number that identifies the file as a Hash file. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, hash_version,
[The version of the Hash database. Returned if m4_ref(DB_FAST_STAT) is
set.])
m4_field(u_int32_t, hash_nkeys,
[The number of unique keys in the database. If m4_ref(DB_FAST_STAT) was
specified the count will be the last saved value unless it has never
been calculated, in which case it will be 0. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, hash_ndata,
[The number of key/data pairs in the database. If m4_ref(DB_FAST_STAT)
was specified the count will be the last saved value unless it has never
been calculated, in which case it will be 0. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, hash_pagecnt,
[The number of pages in the database. Returned if m4_ref(DB_FAST_STAT)
is set.])
m4_field(u_int32_t, hash_pagesize,
[The underlying database page (and bucket) size, in bytes. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, hash_ffactor,
[The desired fill factor (number of items per bucket) specified at
database-creation time. Returned if m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, hash_buckets,
[The number of hash buckets. Returned if m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, hash_free,
[The number of pages on the free list.])
m4_field(u_int32_t, hash_bfree,
[The number of bytes free on bucket pages.])
m4_field(u_int32_t, hash_bigpages,
[The number of big key/data pages.])
m4_field(u_int32_t, hash_big_bfree,
[The number of bytes free on big item pages.])
m4_field(u_int32_t, hash_overflows,
[The number of overflow pages (overflow pages are pages that contain items
that did not fit in the main bucket page).])
m4_field(u_int32_t, hash_ovfl_free,
[The number of bytes free on overflow pages.])
m4_field(u_int32_t, hash_dup,
[The number of duplicate pages.])
m4_field(u_int32_t, hash_dup_free,
[The number of bytes free on duplicate pages.])
m4_tagend
m4_section([Btree and Recno Statistics])
m4_p([dnl
In the case of a Btree or Recno database, the statistics are stored in
a structure of type DB_BTREE_STAT. The following fields will be filled
in:])
m4_tagbegin
m4_field(u_int32_t, bt_magic,
[Magic number that identifies the file as a Btree database. Returned
if m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, bt_version,
[The version of the Btree database. Returned if m4_ref(DB_FAST_STAT)
is set.])
m4_field(u_int32_t, bt_nkeys,
[For the Btree Access Method, the number of keys in the database. If
the m4_ref(DB_FAST_STAT) flag is not specified or the database was
configured to support record numbers (see m4_ref(DB_RECNUM)), the count
will be exact. Otherwise, the count will be the last saved value unless
it has never been calculated, in which case it will be 0.
m4_p([dnl
For the Recno Access Method, the number of records in the database. If
the database was configured with mutable record numbers (see
m4_ref(DB_RENUMBER)), the count will be exact. Otherwise, if the
m4_ref(DB_FAST_STAT) flag is specified the count will be exact but will
include deleted and implicitly created records; if the
m4_ref(DB_FAST_STAT) flag is not specified, the count will be exact and
will not include deleted or implicitly created records.])
m4_p([dnl
Returned if m4_ref(DB_FAST_STAT) is set.])])
m4_field(u_int32_t, bt_ndata, [dnl
For the Btree Access Method, the number of key/data pairs in the
database. If the m4_ref(DB_FAST_STAT) flag is not specified, the count
will be exact. Otherwise, the count will be the last saved value unless
it has never been calculated, in which case it will be 0.
m4_p([dnl
For the Recno Access Method, the number of records in the database. If
the database was configured with mutable record numbers (see
m4_ref(DB_RENUMBER)), the count will be exact. Otherwise, if the
m4_ref(DB_FAST_STAT) flag is specified the count will be exact but will
include deleted and implicitly created records; if the
m4_ref(DB_FAST_STAT) flag is not specified, the count will be exact and
will not include deleted or implicitly created records.])
m4_p([dnl
Returned if m4_ref(DB_FAST_STAT) is set.])])
m4_field(u_int32_t, bt_pagecnt,
[The number of pages in the database. Returned if m4_ref(DB_FAST_STAT)
is set.])
m4_field(u_int32_t, bt_pagesize,
[The underlying database page size, in bytes. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, bt_minkey,
[The minimum keys per page. Returned if m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, bt_re_len,
[The length of fixed-length records. Returned if m4_ref(DB_FAST_STAT)
is set.])
m4_field(u_int32_t, bt_re_pad,
[The padding byte value for fixed-length records. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, bt_levels,
[Number of levels in the database.])
m4_field(u_int32_t, bt_int_pg,
[Number of database internal pages.])
m4_field(u_int32_t, bt_leaf_pg,
[Number of database leaf pages.])
m4_field(u_int32_t, bt_dup_pg,
[Number of database duplicate pages.])
m4_field(u_int32_t, bt_over_pg,
[Number of database overflow pages.])
m4_field(u_int32_t, bt_empty_pg,
[Number of empty database pages.])
m4_field(u_int32_t, bt_free,
[Number of pages on the free list.])
m4_field(u_int32_t, bt_int_pgfree,
[Number of bytes free in database internal pages.])
m4_field(u_int32_t, bt_leaf_pgfree,
[Number of bytes free in database leaf pages.])
m4_field(u_int32_t, bt_dup_pgfree,
[Number of bytes free in database duplicate pages.])
m4_field(u_int32_t, bt_over_pgfree,
[Number of bytes free in database overflow pages.])
m4_tagend
m4_section([Queue Statistics])
m4_p([dnl
In the case of a Queue database, the statistics are stored in a
structure of type DB_QUEUE_STAT. The following fields will be filled
in:])
m4_tagbegin
m4_field(u_int32_t, qs_magic,
[Magic number that identifies the file as a Queue file. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, qs_version,
[The version of the Queue file type. Returned if m4_ref(DB_FAST_STAT)
is set.])
m4_field(u_int32_t, qs_nkeys,
[The number of records in the database. If m4_ref(DB_FAST_STAT) was
specified the count will be the last saved value unless it has never
been calculated, in which case it will be 0. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, qs_ndata,
[The number of records in the database. If m4_ref(DB_FAST_STAT) was
specified the count will be the last saved value unless it has never
been calculated, in which case it will be 0. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, qs_pagesize,
[Underlying database page size, in bytes. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, qs_extentsize,
[Underlying database extent size, in pages. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, qs_pages,
[Number of pages in the database.])
m4_field(u_int32_t, qs_re_len,
[The length of the records. Returned if m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, qs_re_pad,
[The padding byte value for the records. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, qs_pgfree,
[Number of bytes free in database pages.])
m4_field(u_int32_t, qs_first_recno,
[First undeleted record in the database. Returned if
m4_ref(DB_FAST_STAT) is set.])
m4_field(u_int32_t, qs_cur_recno,
[Next available record number. Returned if m4_ref(DB_FAST_STAT) is set.])
m4_tagend
m4_err(dbh_stat, rephandle, replockout, einval)
m4_stat_print(dbh_stat_print, database, dbh_stat)
m4_seealso(Db)
m4_page_footer

44
docs_src/db/db_sync.so Normal file
View File

@@ -0,0 +1,44 @@
m4_comment([$Id: db_sync.so,v 10.37 2007/10/24 16:06:06 bostic Exp $])
define(M4PAGELOCAL, dbh_sync)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_sync),
ifelse(M4API, C_API, [dnl
int
DB-__GT__sync(DB *db, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::sync(u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_sync) flushes any cached information to disk.])
m4_p([dnl
If the database is in memory only, the m4_refT(dbh_sync) has no effect and
will always succeed.])
m4_p([m4_bold([dnl
It is important to understand that flushing cached information to disk
only minimizes the window of opportunity for corrupted data.]) Although
unlikely, it is possible for database corruption to happen if a system
or application crash occurs while writing data to the database. To
ensure that database corruption never occurs, applications must either:
use transactions and logging with automatic recovery; use logging and
application-specific recovery; or edit a copy of the database, and once
all applications using the database have successfully called
m4_ref(dbh_close), atomically replace the original database with the
updated copy.])
m4_return(dbh_sync, std)
m4_parambegin
m4_unusedflags
m4_paramend
m4_err(dbh_sync, rephandle, replockout, einval)
m4_seealso(Db)
m4_page_footer

46
docs_src/db/db_truncate.so Normal file
View File

@@ -0,0 +1,46 @@
m4_comment([$Id: db_truncate.so,v 1.29 2006/09/13 14:30:52 mjc Exp $])
define(M4PAGELOCAL, dbh_truncate)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_truncate),
ifelse(M4API, C_API, [dnl
int
DB-__GT__truncate(DB *db,
DB_TXN *txnid, u_int32_t *countp, u_int32_t flags);
], M4API, CXX_API, [dnl
int
Db::truncate(DbTxn *txnid, u_int32_t *countp, u_int32_t flags);
], [dnl
public int truncate(DbTxn txnid, int flags)
throws DbException;
]))
m4_p([dnl
The m4_refT(dbh_truncate) empties the database, discarding all records
it contains. The number of records discarded from the database is
returned in m4_arg(countp).])
m4_p([dnl
When called on a database configured with secondary indices using the
m4_refT(dbh_associate), the m4_refT(dbh_truncate) truncates the primary
database and all secondary indices. A count of the records discarded
from the primary database is returned.])
m4_p([dnl
It is an error to call the m4_refT(dbh_truncate) on a database with open
cursors.])
m4_return(dbh_truncate, std)
m4_parambegin
m4_param_co(countp, number of records discarded from the database)
m4_unusedflags
m4_param_txn(dbh_truncate)
m4_paramend
m4_err(dbh_truncate, deadlock,
einval, [there are open cursors in the database])
m4_seealso(Db)
m4_page_footer

82
docs_src/db/db_upgrade.so Normal file
View File

@@ -0,0 +1,82 @@
m4_comment([$Id: db_upgrade.so,v 10.37 2004/08/13 03:38:56 bostic Exp $])
define(M4PAGELOCAL, [dbh_upgrade, DB_DUPSORT])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_upgrade),
ifelse(M4API, C_API, [dnl
int
DB-__GT__upgrade(DB *db, const char *file, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::upgrade(const char *file, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_upgrade) upgrades all of the databases included in the
file m4_arg(file), if necessary. If no upgrade is necessary,
m4_ref(dbh_upgrade) always returns success.])
m4_p([m4_bold([dnl
Database upgrades are done in place and are destructive. For example,
if pages need to be allocated and no disk space is available, the
database may be left corrupted. Backups should be made before databases
are upgraded. See m4_link(M4RELDIR/ref/am/upgrade, Upgrading databases)
for more information.])])
m4_p([dnl
Unlike all other database operations, m4_ref(dbh_upgrade) may only be done
on a system with the same byte-order as the database.])
m4_return(dbh_upgrade, std)
m4_underfunc(dbh_upgrade, dbh_upgrade, db_upgrade)
m4_parambegin
m4_param(file, [dnl
The m4_arg(file) parameter is the physical file containing the databases
to be upgraded.])
m4_param(flags, [dnl
m4_sf_zmust(0)
m4_tagbegin
m4_tag(m4_idef(DB_DUPSORT), [dnl
m4_bold([This flag is only meaningful when upgrading databases from
releases before the m4_db 3.1 release.])
m4_p([dnl
As part of the upgrade from the m4_db 3.0 release to the 3.1 release,
the on-disk format of duplicate data items changed. To correctly
upgrade the format requires applications to specify whether duplicate
data items in the database are sorted or not. Specifying the
m4_ref(DB_DUPSORT) flag informs m4_ref(dbh_upgrade) that the duplicates
are sorted; otherwise they are assumed to be unsorted. Incorrectly
specifying the value of this flag may lead to database corruption.])
m4_p([dnl
Further, because the m4_refT(dbh_upgrade) upgrades a physical file
(including all the databases it contains), it is not possible to use
m4_ref(dbh_upgrade) to upgrade files in which some of the databases it
includes have sorted duplicate data items, and some of the databases it
includes have unsorted duplicate data items. If the file does not have
more than a single database, if the databases do not support duplicate
data items, or if all of the databases that support duplicate data items
support the same style of duplicates (either sorted or unsorted),
m4_ref(dbh_upgrade) will work correctly as long as the
m4_ref(DB_DUPSORT) flag is correctly specified. Otherwise, the file
cannot be upgraded using m4_ref(dbh_upgrade); it must be upgraded
manually by dumping and reloading the databases.])])
m4_tagend])
m4_paramend
m4_header([Environment Variables])
m4_data_location(dbh_upgrade, 1)
m4_err(dbh_upgrade,
m4_idef(DB_OLD_VERSION),
[The database cannot be upgraded by this version of the m4_db software.],
einval, [the database is not in the same byte-order as the system])
m4_seealso(Db)
m4_page_footer

142
docs_src/db/db_verify.so Normal file
View File

@@ -0,0 +1,142 @@
m4_comment([$Id: db_verify.so,v 10.30 2005/03/08 16:29:34 bostic Exp $])
define(M4PAGELOCAL,
[dbh_verify, DB_AGGRESSIVE, DB_NOORDERCHK, DB_ORDERCHKONLY,
DB_PRINTABLE, DB_SALVAGE, DB_VERIFY_BAD])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbh_verify),
ifelse(M4API, C_API, [dnl
int
DB-__GT__verify(DB *db, const char *file,
const char *database, FILE *outfile, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::verify(const char *file,
const char *database, ostream *outfile, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbh_verify) verifies the integrity of all databases in the
file specified by the m4_arg(file) parameter, and optionally outputs the
databases' key/data pairs to the file stream specified by the
m4_arg(outfile) parameter.])
m4_p([m4_bold([dnl
The m4_refT(dbh_verify) does not perform any locking, even in m4_db
environments that are configured with a locking subsystem. As such, it
should only be used on files that are not being modified by another
thread of control.])])
m4_when_dbopen(dbh_verify)
m4_destructor(Db, dbh_verify)
m4_underfunc(dbh_verify, dbh_verify, db_verify)
m4_idefz(DB_VERIFY_BAD)
m4_return(dbh_verify, specific, DB_VERIFY_BAD, [if a database is
corrupted. When the m4_ref(DB_SALVAGE) flag is specified, the
m4_ref(DB_VERIFY_BAD) return means that all key/data pairs in the file
may not have been successfully output], prev)
m4_parambegin
m4_param(database, [dnl
The m4_arg(database) parameter is the database in m4_arg(file) on which
the database checks for btree and duplicate sort order and for hashing
are to be performed. See the m4_ref(DB_ORDERCHKONLY) flag for more
information.
m4_p([dnl
The database parameter must be set to NULL except when the
m4_ref(DB_ORDERCHKONLY) flag is set.])])
m4_param(file, [dnl
The m4_arg(file) parameter is the physical file in which the databases
to be verified are found.])
m4_param(flags, [dnl
m4_sf_zmust(0)
m4_tagbegin
m4_tag(m4_idef(DB_SALVAGE), [dnl
Write the key/data pairs from all databases in the file to the file
stream named in the m4_arg(outfile) parameter. Key values are written
for Btree, Hash and Queue databases, but not for Recno databases.
m4_p([dnl
The output format is the same as that specified for the m4_ref(db_dump)
utility, and can be used as input for the m4_ref(db_load) utility.])
m4_p([dnl
Because the key/data pairs are output in page order as opposed to the sort
order used by m4_ref(db_dump), using m4_ref(dbh_verify) to dump key/data
pairs normally produces less than optimal loads for Btree databases.])])
m4_tagend
m4_p([dnl
In addition, the following flags may be set by m4_or them into the
m4_arg(flags) parameter:])
m4_tagbegin
m4_tag(m4_idef(DB_AGGRESSIVE), [dnl
Output m4_bold(all) the key/data pairs in the file that can be found.
By default, m4_ref(dbh_verify) does not assume corruption. For example,
if a key/data pair on a page is marked as deleted, it is not then written
to the output file. When m4_ref(DB_AGGRESSIVE) is specified, corruption
is assumed, and any key/data pair that can be found is written. In this
case, key/data pairs that are corrupted or have been deleted may appear
in the output (even if the file being salvaged is in no way corrupt), and
the output will almost certainly require editing before being loaded into
a database.])
m4_tag(m4_idef(DB_PRINTABLE), [dnl
When using the m4_ref(DB_SALVAGE) flag, if characters in either the key
or data items are printing characters (as defined by m4_manref(isprint,
3)), use printing characters to represent them. This flag permits users
to use standard text editors and tools to modify the contents of
databases or selectively remove data from salvager output.
m4_p([dnl
Note: different systems may have different notions about what characters
are considered m4_italic(printing characters), and databases dumped in
this manner may be less portable to external systems.])])
m4_tag(m4_idef(DB_NOORDERCHK), [dnl
Skip the database checks for btree and duplicate sort order and for
hashing.
m4_p([dnl
The m4_refT(dbh_verify) normally verifies that btree keys and duplicate
items are correctly sorted, and hash keys are correctly hashed. If the
file being verified contains multiple databases using differing sorting
or hashing algorithms, some of them must necessarily fail database
verification because only one sort order or hash function can be
specified before m4_ref(dbh_verify) is called. To verify files with
multiple databases having differing sorting orders or hashing functions,
first perform verification of the file as a whole by using the
m4_ref(DB_NOORDERCHK) flag, and then individually verify the sort order
and hashing function for each database in the file using the
m4_ref(DB_ORDERCHKONLY) flag.])])
m4_tag(m4_idef(DB_ORDERCHKONLY), [dnl
Perform the database checks for btree and duplicate sort order and for
hashing, skipped by m4_ref(DB_NOORDERCHK).
m4_p([dnl
When this flag is specified, a m4_arg(database) parameter should also be
specified, indicating the database in the physical file which is to be
checked. This flag is only safe to use on databases that have already
successfully been verified using m4_ref(dbh_verify) with the
m4_ref(DB_NOORDERCHK) flag set.])])
m4_tagend])
m4_param(outfile, [dnl
The m4_arg(outfile) parameter is an optional file stream to which the
databases' key/data pairs are written.])
m4_paramend
m4_header([Environment Variables])
m4_data_location(dbh_verify, 1)
m4_err(dbh_verify, filenotfound,
einval, [m4_ref(dbh_verify) was called after m4_ref(dbh_open)])
m4_seealso(Db)
m4_page_footer

83
docs_src/db/dbt_bulk.so Normal file
View File

@@ -0,0 +1,83 @@
m4_comment([$Id: dbt_bulk.so,v 10.14 2007/01/31 14:45:22 bostic Exp $])
define(M4PAGELOCAL,
[DB_MULTIPLE_INIT, DB_MULTIPLE_NEXT, DB_MULTIPLE_KEY_NEXT,
DB_MULTIPLE_RECNO_NEXT])
include(m4/m4.seealso)
m4_page_header(DBT, [DBT: Bulk Retrieval], yes)
m4_idefz(bulk retrieval)
m4_p([dnl
If either of the m4_ref(DB_MULTIPLE) or m4_ref(DB_MULTIPLE_KEY) flags
were specified to the m4_ref(dbh_get) or m4_refT(dbc_get)s, the data
m4_ref(Dbt) returned by those interfaces will refer to a buffer that is
filled with data. Access to that data is through the following
macros:])
m4_tagbegin
m4_tag(m4_idef(DB_MULTIPLE_INIT), [dnl
m4_literal([DB_MULTIPLE_INIT(void *pointer, m4_ref(Dbt) *data);])
m4_p([dnl
Initialize the retrieval. The m4_arg(pointer) parameter is a variable
to be initialized. The m4_arg(data) parameter is a m4_ref(Dbt)
structure returned from a successful call to m4_ref(dbh_get) or
m4_ref(dbc_get) for which one of the m4_ref(DB_MULTIPLE) or
m4_ref(DB_MULTIPLE_KEY) flags was specified.])])
m4_tag(m4_idef(DB_MULTIPLE_NEXT), [dnl
m4_literal([DB_MULTIPLE_NEXT(void *pointer, m4_ref(Dbt) *data, void *retdata, size_t retdlen);])
m4_p([dnl
The m4_arg(data) parameter is a m4_ref(Dbt) structure returned from a
successful call to m4_ref(dbh_get) or m4_ref(dbc_get) for which the
m4_ref(DB_MULTIPLE) flag was specified. The m4_arg(pointer) and
m4_arg(data) parameters must have been previously initialized by a call
to m4_ref(DB_MULTIPLE_INIT). The m4_arg(retdata) parameter is set to
refer to the next data element in the returned set, and the
m4_arg(retdlen) parameter is set to the length, in bytes, of that data
element. When used with the Queue and Recno access methods,
m4_arg(retdata) will be set to NULL for deleted records. The
m4_arg(pointer) parameter is set to NULL if there are no more data
elements in the returned set.])])
m4_tag(m4_idef(DB_MULTIPLE_KEY_NEXT), [dnl
m4_literal([DB_MULTIPLE_KEY_NEXT(void *pointer, m4_ref(Dbt) *data,
void *retkey, size_t retklen, void *retdata, size_t retdlen);])
m4_p([dnl
The m4_arg(data) parameter is a m4_ref(Dbt) structure returned from a
successful call to m4_ref(dbc_get) with the Btree or Hash access methods
for which the m4_ref(DB_MULTIPLE_KEY) flag was specified. The
m4_arg(pointer) and m4_arg(data) parameters must have been previously
initialized by a call to m4_ref(DB_MULTIPLE_INIT). The m4_arg(retkey)
parameter is set to refer to the next key element in the returned set,
and the m4_arg(retklen) parameter is set to the length, in bytes, of
that key element. The m4_arg(retdata) parameter is set to refer to the
next data element in the returned set, and the m4_arg(retdlen) parameter
is set to the length, in bytes, of that data element. The
m4_arg(pointer) parameter is set to NULL if there are no more key/data
pairs in the returned set.])])
m4_tag(m4_idef(DB_MULTIPLE_RECNO_NEXT), [dnl
m4_literal([DB_MULTIPLE_RECNO_NEXT(void *pointer, m4_ref(Dbt) *data,
db_recno_t recno, void * retdata, size_t retdlen);])
m4_p([dnl
The m4_arg(data) parameter is a m4_ref(Dbt) structure returned from a
successful call to m4_ref(dbc_get) with the Queue or Recno access
methods for which the m4_ref(DB_MULTIPLE_KEY) flag was specified. The
m4_arg(pointer) and m4_arg(data) parameters must have been previously
initialized by a call to m4_ref(DB_MULTIPLE_INIT). The m4_arg(recno)
parameter is set to the record number of the next record in the returned
set. The m4_arg(retdata) parameter is set to refer to the next data
element in the returned set, and the m4_arg(retdlen) parameter is set to
the length, in bytes, of that data element. Deleted records are not
included in the results. The m4_arg(pointer) parameter is set to NULL
if there are no more key/data pairs in the returned set.])])
m4_tagend
m4_p([dnl
These macros may be called multiple times, but m4_ref(DB_MULTIPLE_INIT)
must be called before each new access of the data.])
m4_page_footer

165
docs_src/db/dbt_bulk_class.so Normal file
View File

@@ -0,0 +1,165 @@
m4_comment([$Id: dbt_bulk_class.so,v 1.15 2004/08/13 03:38:56 bostic Exp $])
define(M4PAGELOCAL,
[DbMultipleDataIterator, DbMultipleKeyDataIterator,
DbMultipleRecnoDataIterator])
include(m4/m4.seealso)
m4_pf_header(Bulk Retrieval API,
ifelse(M4API, C_API, [dnl
])
ifelse(M4API, CXX_API, [dnl
class DbMultipleDataIterator
{
public:
DbMultipleDataIterator(const Dbt &dbt);
m4_blank
bool next(Dbt &data);
};
m4_blank
class DbMultipleKeyDataIterator
{
public:
DbMultipleKeyDataIterator(const Dbt &dbt);
m4_blank
bool next(Dbt &key, Dbt &data);
};
m4_blank
class DbMultipleRecnoDataIterator
{
public:
DbMultipleRecnoDataIterator(const Dbt &dbt);
m4_blank
bool next(db_recno_t &key, Dbt &data);
};
]))
m4_p([dnl
If either of the m4_ref(DB_MULTIPLE) or m4_ref(DB_MULTIPLE_KEY) flags
were specified to the m4_ref(dbh_get) or m4_refT(dbc_get), the data
m4_ref(Dbt) returned by those interfaces will refer to a buffer that
is filled with data. Access to that data is through the following
classes.])
m4_p([dnl
All instances of the bulk retrieval classes may be used only once, and
to traverse the bulk retrieval buffer in the forward direction only.
However, they are nondestructive, so multiple iterators can be
instantiated and used on the same returned data m4_ref(Dbt).])
m4_pf_description(DbMultipleIterator)
m4_p([dnl
The m4_ref(DbMultipleIterator) is a shared package-private base class
for the three types of bulk-return Iterator; it should never be
instantiated directly, but it handles the functionality shared by its
subclasses.])
m4_pf_description(DbMultipleDataIterator)
m4_p([dnl
The m4_ref(DbMultipleDataIterator) class is used to iterate through data
returned using the m4_ref(DB_MULTIPLE) flag from a database belonging
to any access method.])
m4_p([dnl
The constructor takes the data m4_ref(Dbt) returned by the call to
m4_ref(dbh_get) or m4_ref(dbc_get) that used the m4_ref(DB_MULTIPLE)
flag.])
m4_parambegin
m4_param(dbt, [dnl
The m4_arg(dbt) parameter is a data m4_ref(Dbt) returned by the call to
m4_ref(dbh_get) or m4_ref(dbc_get) that used the m4_ref(DB_MULTIPLE)
flag.])
m4_paramend
m4_pf_description(DbMultipleDataIterator.next)
m4_p([dnl
The DbMultipleDataIterator.next method takes a m4_ref(Dbt) that will be
filled in with a reference to a buffer, a size, and an offset that
together yield the next data item in the original bulk retrieval buffer.])
m4_p([dnl
The DbMultipleDataIterator.next method returns false if no more data are
available, and true otherwise.])
m4_parambegin
m4_param(data, [dnl
The m4_arg(data) parameter is a m4_ref(Dbt) that will be filled in with
a reference to a buffer, a size, and an offset that together yield the
next data item in the original bulk retrieval buffer.])
m4_paramend
m4_pf_description(DbMultipleKeyDataIterator)
m4_p([dnl
The m4_ref(DbMultipleKeyDataIterator) class is used to iterate through
data returned using the m4_ref(DB_MULTIPLE_KEY) flag from a database
belonging to the Btree or Hash access methods.])
m4_p([dnl
The constructor takes the data m4_ref(Dbt) returned by the call to
m4_ref(dbh_get) or m4_ref(dbc_get) that used the m4_ref(DB_MULTIPLE_KEY)
flag.])
m4_parambegin
m4_param(dbt, [dnl
The m4_arg(dbt) parameter is a data m4_ref(Dbt) returned by the call to
m4_ref(dbh_get) or m4_ref(dbc_get) that used the m4_ref(DB_MULTIPLE_KEY)
flag.])
m4_paramend
m4_pf_description(DbMultipleKeyDataIterator.next)
m4_p([dnl
The DbMultipleKeyDataIterator.next method takes two m4_ref(Dbt)s, one
for a key and one for a data item, that will each be filled in with a
reference to a buffer, a size, and an offset that together yield the
next key and data item in the original bulk retrieval buffer. The
DbMultipleKeyDataIterator.next method returns false if no more data are
available, and true otherwise.])
m4_p([dnl
The DbMultipleKeyDataIterator.next method returns false if no more data
are available, and true otherwise.])
m4_parambegin
m4_param(key, [dnl
The m4_arg(key) parameter will be filled in with a reference to a buffer,
a size, and an offset that yields the next key item in the original bulk
retrieval buffer.])
m4_param(data, [dnl
The m4_arg(data) parameter will be filled in with a reference to a buffer,
a size, and an offset that yields the next data item in the original bulk
retrieval buffer.])
m4_paramend
m4_pf_description(DbMultipleRecnoDataIterator)
m4_p([dnl
This class is used to iterate through data returned using the
m4_ref(DB_MULTIPLE_KEY) flag from a database belonging to the Recno or
Queue access methods.])
m4_p([dnl
The constructor takes the data m4_ref(Dbt) returned by the call to
m4_ref(dbh_get) or m4_ref(dbc_get) that used the m4_ref(DB_MULTIPLE_KEY)
flag.])
m4_parambegin
m4_param(dbt, [dnl
The m4_arg(dbt) parameter is a data m4_ref(Dbt) returned by the call to
m4_ref(dbh_get) or m4_ref(dbc_get) that used the m4_ref(DB_MULTIPLE_KEY)
flag.])
m4_paramend
m4_pf_description(DbMultipleRecnoDataIterator.next)
ifelse(M4API, CXX_API, [dnl
The DbMultipleRecnoDataIterator.next method takes a m4_arg(db_recno_t)
for the key and a m4_ref(Dbt) for a data item, which will be filled in
with a pointer to a buffer and a size. Together they yield the next key
and data item in the original bulk retrieval buffer.])
m4_p([dnl
The DbMultipleRecnoDataIterator.next method returns false if no more
data are available, and true otherwise.])
m4_parambegin
m4_param(key, [dnl
The m4_arg(key) parameter will be filled in with a reference to a
buffer, a size, and an offset that yields the next key item in the
original bulk retrieval buffer.])
m4_param(data, [dnl
The m4_arg(data) parameter will be filled in with a reference to a
buffer, a size, and an offset that yields the next data item in the
original bulk retrieval buffer.])
m4_paramend
m4_page_footer

176
docs_src/db/dbt_c.so Normal file
View File

@@ -0,0 +1,176 @@
m4_comment([$Id: dbt_c.so,v 10.52 2007/02/27 00:41:24 mjc Exp $])
define(M4PAGELOCAL,
[Dbt, DB_BUFFER_SMALL,
DB_DBT_MALLOC, DB_DBT_PARTIAL, DB_DBT_REALLOC, DB_DBT_USERMEM])
m4_page_header(DBT, [DBT: Key/Data Pairs], yes)
m4_idefz(key/data pairs)
m4_p([dnl
Storage and retrieval for the m4_db access methods are based on key/data
pairs. Both key and data items are represented by the DBT data
structure. (The name m4_italic(DBT) is a mnemonic for m4_italic(data
base thang), and was used because no one could think of a reasonable
name that wasn't already in use somewhere else.) Key and data byte
strings may refer to strings of zero length up to strings of
essentially unlimited length. See m4_link(M4RELDIR/ref/am_misc/dbsizes,
[Database limits]) for more information.])
m4_indent([dnl
typedef struct {
void *data;
u_int32_t size;
u_int32_t ulen;
u_int32_t dlen;
u_int32_t doff;
u_int32_t flags;
} DBT;])
m4_p([dnl
In order to ensure compatibility with future releases of m4_db, all
fields of the DBT structure that are not explicitly set should be
initialized to nul bytes before the first time the structure is used.
Do this by declaring the structure external or static, or by calling
the C library routine m4_manref(bzero, 3) or m4_manref(memset, 3).])
m4_p([dnl
By default, the m4_arg(flags) structure element is expected to be set
to 0. In this default case, when the application is providing m4_db a
key or data item to store into the database, m4_db expects the
m4_arg(data) structure element to point to a byte string of m4_arg(size)
bytes. When returning a key/data item to the application, m4_db will
store into the m4_arg(data) structure element a pointer to a byte string
of m4_arg(size) bytes, and the memory to which the pointer refers will be
allocated and managed by m4_db.])
m4_p([The elements of the DBT structure are defined as follows:])
m4_tagbegin
m4_tag([void *m4_idef(data);], [A pointer to a byte string.])
m4_tag([u_int32_t m4_idef(size);], [The length of m4_arg(data), in bytes.])
m4_tag([u_int32_t m4_idef(ulen);], [dnl
The size of the user's buffer (to which m4_arg(data) refers), in bytes.
This location is not written by the m4_db functions.
m4_p([dnl
Note that applications can determine the length of a record by setting
the m4_arg(ulen) field to 0 and checking the return value in the
m4_arg(size) field. See the DB_DBT_USERMEM flag for more information.])])
m4_tag([u_int32_t m4_idef(dlen);], [dnl
The length of the partial record being read or written by the application,
in bytes. See the DB_DBT_PARTIAL flag for more information.])
m4_tag([u_int32_t m4_idef(doff);], [dnl
The offset of the partial record being read or written by the application,
in bytes. See the DB_DBT_PARTIAL flag for more information.])
m4_tag([u_int32_t flags;], [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_DBT_MALLOC), [dnl
When this flag is set, m4_db will allocate memory for the returned key
or data item (using m4_manref(malloc, 3), or the user-specified malloc
function), and return a pointer to it in the m4_arg(data) field of the
key or data DBT structure. Because any allocated memory becomes the
responsibility of the calling application, the caller must determine
whether memory was allocated using the returned value of the
m4_arg(data) field.
m4_p([dnl
It is an error to specify more than one of m4_ref(DB_DBT_MALLOC),
m4_ref(DB_DBT_REALLOC), and m4_ref(DB_DBT_USERMEM).])])
m4_tag(m4_idef(DB_DBT_REALLOC), [dnl
When this flag is set m4_db will allocate memory for the returned key
or data item (using m4_manref(realloc, 3), or the user-specified realloc
function), and return a pointer to it in the m4_arg(data) field of the
key or data DBT structure. Because any allocated memory becomes the
responsibility of the calling application, the caller must determine
whether memory was allocated using the returned value of the
m4_arg(data) field.
m4_p([dnl
The difference between m4_ref(DB_DBT_MALLOC) and m4_ref(DB_DBT_REALLOC)
is that the latter will call m4_manref(realloc, 3) instead of
m4_manref(malloc, 3), so the allocated memory will be grown as necessary
instead of the application doing repeated free/malloc calls.])
m4_p([dnl
It is an error to specify more than one of m4_ref(DB_DBT_MALLOC),
m4_ref(DB_DBT_REALLOC), and m4_ref(DB_DBT_USERMEM).])])
m4_idefz(DB_BUFFER_SMALL)
m4_tag(m4_idef(DB_DBT_USERMEM), [dnl
The m4_arg(data) field of the key or data structure must refer to
memory that is at least m4_arg(ulen) bytes in length. If the length of
the requested item is less than or equal to that number of bytes, the
item is copied into the memory to which the m4_arg(data) field refers.
Otherwise, the m4_arg(size) field is set to the length needed for the
requested item, and the error m4_ref(DB_BUFFER_SMALL) is returned.
m4_p([dnl
It is an error to specify more than one of m4_ref(DB_DBT_MALLOC),
m4_ref(DB_DBT_REALLOC), and m4_ref(DB_DBT_USERMEM).])])
m4_tag(m4_idef(DB_DBT_PARTIAL), [dnl
Do partial retrieval or storage of an item. If the calling application
is doing a get, the m4_arg(dlen) bytes starting m4_arg(doff) bytes from
the beginning of the retrieved data record are returned as if they
comprised the entire record. If any or all of the specified bytes do
not exist in the record, the get is successful, and any existing bytes
are returned.
m4_p([dnl
For example, if the data portion of a retrieved record was 100 bytes,
and a partial retrieval was done using a DBT having a m4_arg(dlen)
field of 20 and a m4_arg(doff) field of 85, the get call would succeed,
the m4_arg(data) field would refer to the last 15 bytes of the record,
and the m4_arg(size) field would be set to 15.])
m4_p([dnl
If the calling application is doing a put, the m4_arg(dlen) bytes
starting m4_arg(doff) bytes from the beginning of the specified key's
data record are replaced by the data specified by the m4_arg(data) and
m4_arg(size) structure elements. If m4_arg(dlen) is smaller than
m4_arg(size), the record will grow; if m4_arg(dlen) is larger than
m4_arg(size), the record will shrink. If the specified bytes do not
exist, the record will be extended using nul bytes as necessary, and
the put call will succeed.])
m4_p([dnl
It is an error to attempt a partial put using the m4_ref(dbh_put) function
in a database that supports duplicate records.
Partial puts in databases supporting duplicate records must be done
using a m4_ref(dbc_put) function.])
m4_p([dnl
It is an error to attempt a partial put with differing m4_arg(dlen) and
m4_arg(size) values in Queue or Recno databases with fixed-length records.])
m4_p([dnl
For example, if the data portion of a retrieved record was 100 bytes,
and a partial put was done using a DBT having a m4_arg(dlen) field of 20,
a m4_arg(doff) field of 85, and a m4_arg(size) field of 30, the resulting
record would be 115 bytes in length, where the last 30 bytes would be
those specified by the put call.])])
m4_tag(m4_idef(DB_DBT_APPMALLOC), [dnl
After an application-supplied callback routine passed to either
m4_ref(dbh_associate) or m4_ref(dbh_set_append_recno) is executed, the
m4_arg(data) field of a m4_ref(Dbt) may refer to memory allocated with
m4_manref(malloc, 3) or m4_manref(realloc, 3). In that case, the
callback sets the m4_ref(DB_DBT_APPMALLOC) flag in the m4_ref(Dbt) so
that m4_db will call m4_manref(free, 3) to deallocate the memory when it
is no longer required.])
m4_tag(m4_idef(DB_DBT_MULTIPLE), [dnl
Set in a secondary key creation callback routine passed to
m4_ref(dbh_associate) to indicate that multiple secondary keys should be
associated with the given primary key/data pair. If set, the
m4_arg(size) field indicates the number of secondary keys and the
m4_arg(data) field refers to an array of that number of m4_ref(Dbt)
structures.
m4_p([dnl
The m4_ref(DB_DBT_APPMALLOC) flag may be set on any of the m4_ref(Dbt)
structures to indicate that their m4_arg(data) field needs to be
freed.])])
m4_tagend])
m4_tagend
m4_page_footer

3
docs_src/db/dbt_class.so Normal file
View File

@@ -0,0 +1,3 @@
m4_comment([$Id: dbt_class.so,v 10.1 2002/08/24 18:22:30 bostic Exp $])
include(ifelse(M4API, C_API, db/dbt_c.so, db/dbt_cxx.so))

341
docs_src/db/dbt_cxx.so Normal file
View File

@@ -0,0 +1,341 @@
m4_comment([$Id: dbt_cxx.so,v 10.72 2007/02/27 00:41:24 mjc Exp $])
define(M4PAGELOCAL,
[Dbt, DB_BUFFER_SMALL, DB_DBT_APPMALLOC, DB_DBT_MALLOC,
DB_DBT_REALLOC, DB_DBT_USERMEM, DB_DBT_PARTIAL,
DB_DBT_APPMALLOC, DB_DBT_MULTIPLE,
dbt_get_data, dbt_get_dlen, dbt_get_doff, dbt_get_flags,
dbt_get_offset, dbt_get_recno_key_data, dbt_get_size, dbt_get_ulen,
dbt_set_data, dbt_set_dlen, dbt_set_doff, dbt_set_flags,
dbt_set_offset, dbt_set_recno_key_data, dbt_set_size, dbt_set_ulen])
m4_pf_header(m4_ref(Dbt), [dnl
class Dbt {
public:
Dbt(void *data, size_t size);
Dbt();
Dbt(const Dbt &);
Dbt &operator = (const Dbt &);
~Dbt();
m4_blank
void *get_data() const;
void set_data(void *);
m4_blank
u_int32_t get_size() const;
void set_size(u_int32_t);
m4_blank
u_int32_t get_ulen() const;
void set_ulen(u_int32_t);
m4_blank
u_int32_t get_dlen() const;
void set_dlen(u_int32_t);
m4_blank
u_int32_t get_doff() const;
void set_doff(u_int32_t);
m4_blank
u_int32_t get_flags() const;
void set_flags(u_int32_t);
m4_blank
DBT *Dbt::get_DBT();
const DBT *Dbt::get_const_DBT() const;
static Dbt *Dbt::get_Dbt(DBT *dbt);
static const Dbt *Dbt::get_const_Dbt(const DBT *dbt);
};])
m4_p([dnl
This information describes the specific details of the m4_ref(Dbt) class,
used to encode keys and data items in a database.])
m4_idefz(key/data pairs)
m4_section([Key/Data Pairs])
m4_p([dnl
Storage and retrieval for the m4_ref(Db) access methods are based on
key/data pairs. Both key and data items are represented by m4_ref(Dbt)
objects. Key and data byte strings may refer to strings of zero length
up to strings of essentially unlimited length. See
m4_link(M4RELDIR/ref/am_misc/dbsizes, [Database limits]) for more
information.])
m4_p([dnl
The m4_ref(Dbt) class provides simple access to an underlying data
structure, whose elements can be examined or changed using the usual
m4_bold(set) or m4_bold(get) methods. m4_ref(Dbt) can be subclassed,
providing a way to associate with it additional data or references to
other structures.])
m4_p([dnl
The constructors set all elements of the underlying structure to zero.
The constructor with two parameters has the effect of setting all elements
to zero except for the m4_arg(data) and m4_arg(size) elements.])
m4_p([dnl
In the case in which the m4_arg(flags) structure element is set to 0, when
the application is providing m4_db a key or data item to store into the
database, m4_db expects the m4_arg(data) object to point to a byte
string of m4_arg(size) bytes. When returning a key/data item to the
application, m4_db will store into the m4_arg(data) object a pointer to
a byte string of m4_arg(size) bytes, and the memory to which the pointer
refers will be allocated and managed by m4_db.])
m4_p([dnl
Access to m4_ref(Dbt) objects is not re-entrant. In particular, if
multiple threads simultaneously access the same m4_ref(Dbt) object using
m4_ref(Db) API calls, the results are undefined, and may result in a
crash. One easy way to avoid problems is to use m4_ref(Dbt) objects
that are constructed as stack variables.])
m4_p([dnl
Each m4_ref(Dbt) object has an associated DBT struct, which is used by
the underlying implementation of m4_db and its C-language API. The
Dbt::get_DBT method returns a pointer to this struct. Given a const
m4_ref(Dbt) object, Dbt::get_const_DBT returns a const pointer to the
same struct.])
m4_p([dnl
Given a DBT struct, the Dbt::get_Dbt method returns the corresponding
m4_ref(Dbt) object, if there is one. If the DBT object was not
associated with a m4_ref(Dbt) (that is, it was not returned from a call
to Dbt::get_DBT), then the result of Dbt::get_Dbt is undefined. Given
a const DBT struct, Dbt::get_const_Dbt returns the associated const
m4_ref(Dbt) object, if there is one.])
m4_p([dnl
These methods may be useful for m4_db applications including both C
and C++ language software. It should not be necessary to use these
calls in a purely C++ application.])
m4_pf_description(m4_ref(dbt_set_data))
m4_p([dnl
Set the data array.])
m4_parambegin
m4_param(data, [dnl
The m4_arg(data) parameter is an array of bytes to be used to set the
content for the m4_ref(Dbt).])
m4_paramend
m4_pf_description(m4_ref(dbt_get_data))
m4_p([dnl
Return the data array.])
m4_pf_description(m4_ref(dbt_set_recno_key_data))
m4_p([dnl
Initialize the data array from a logical record number. Recno database
records are ordered by integer keys starting at 1. When the
m4_refT(dbt_set_recno_key_data) is called, the data, size and offset
fields in the m4_ref(Dbt) are implicitly set to hold a byte array
representation of the integer key.])
m4_parambegin
m4_param(recno, [dnl
The m4_arg(recno) parameter logical record number used to initialize the
data array.])
m4_paramend
m4_pf_description(m4_ref(dbt_get_recno_key_data))
m4_p([dnl
Return an object from the data array, expecting that data to be a
logical record number.])
m4_pf_description(m4_ref(dbt_set_offset))
m4_p([dnl
Set the byte offset into the data array.])
m4_p([dnl
The number of bytes offset into the m4_arg(data) array determine the
portion of the array actually used. This element is accessed using
m4_ref(dbt_get_offset) and m4_ref(dbt_set_offset).])
m4_parambegin
m4_param(offset, [dnl
The m4_arg(offset) parameter is the byte offset into the data array.])
m4_paramend
m4_pf_description(m4_ref(dbt_get_offset))
m4_p([dnl
Return the byte offset into the data array.])
m4_pf_description(m4_ref(dbt_set_size))
m4_p([dnl
Set the byte size of the data array.])
m4_parambegin
m4_param(size, [dnl
The m4_arg(size) parameter is the size of the data array in bytes.])
m4_paramend
m4_pf_description(m4_ref(dbt_get_size))
m4_p([dnl
Return the data array size.])
m4_pf_description(m4_ref(dbt_set_ulen))
m4_p([dnl
Set the byte size of the user-specified buffer.])
m4_p([dnl
Note that applications can determine the length of a record by setting
the m4_arg(ulen) to 0 and checking the return value found in m4_arg(size).
See the m4_ref(DB_DBT_USERMEM) flag for more information.])
m4_parambegin
m4_param(ulen, [dnl
The m4_arg(ulen) parameter the size of the data array in bytes.])
m4_paramend
m4_pf_description(m4_ref(dbt_get_ulen))
m4_p([dnl
Return the length in bytes of the user-specified buffer.])
m4_pf_description(m4_ref(dbt_set_dlen))
m4_p([dnl
Set the byte length of the partial record being read or written by the
application, in bytes. See the m4_ref(DB_DBT_PARTIAL) flag for more
information.])
m4_parambegin
m4_param(dlen, [dnl
The m4_arg(dlen) parameter is the length of the partial record in bytes.])
m4_paramend
m4_pf_description(m4_ref(dbt_get_dlen))
m4_p([dnl
Return the length of the partial record, in bytes.])
m4_pf_description(m4_ref(dbt_set_doff))
m4_p([dnl
Set the offset of the partial record being read or written by the
application, in bytes. See the m4_ref(DB_DBT_PARTIAL) flag for more
information.])
m4_parambegin
m4_param(doff, [dnl
The m4_arg(doff) parameter is the offset of the partial record.])
m4_paramend
m4_pf_description(m4_ref(dbt_get_doff))
m4_p([dnl
Return the offset of the partial record, in bytes.])
m4_pf_description(m4_ref(dbt_set_flags))
m4_p([dnl
Set the object flag value.])
m4_parambegin
m4_param(flags, [dnl
The m4_arg(flags) parameter is m4_ref(Dbt) flag value.])
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_DBT_MALLOC), [dnl
When this flag is set, m4_db will allocate memory for the returned key
or data item (using m4_manref(malloc, 3) or the user-specified malloc
method), and return a pointer to it in the m4_arg(data) field of the key
or data m4_ref(Dbt) object. Because any allocated memory becomes the
responsibility of the calling application, the caller must determine
whether memory was allocated using the returned value of the
m4_arg(data) field.
m4_p([dnl
It is an error to specify more than one of m4_ref(DB_DBT_MALLOC),
m4_ref(DB_DBT_REALLOC), and m4_ref(DB_DBT_USERMEM).])])
m4_tag(m4_idef(DB_DBT_REALLOC), [dnl
When this flag is set m4_db will allocate memory for the returned key
or data item (using m4_manref(realloc, 3) or the user-specified realloc
method), and return a pointer to it in the m4_arg(data) field of the key
or data m4_ref(Dbt) object. Because any allocated memory becomes the
responsibility of the calling application, the caller must determine
whether memory was allocated using the returned value of the
m4_arg(data) field.
m4_p([dnl
It is an error to specify more than one of m4_ref(DB_DBT_MALLOC),
m4_ref(DB_DBT_REALLOC), and m4_ref(DB_DBT_USERMEM).])])
m4_idefz(DB_BUFFER_SMALL)
m4_tag(m4_idef(DB_DBT_USERMEM), [dnl
The m4_arg(data) field of the key or data object must refer to memory
that is at least m4_arg(ulen) bytes in length. If the length of the
requested item is less than or equal to that number of bytes, the item
is copied into the memory referred to by the m4_arg(data) field.
Otherwise, the m4_arg(size) fields of both the key and data m4_ref(Dbt)
objects are set to the length needed for the requested item, and the
error m4_ref(DB_BUFFER_SMALL) is returned.
m4_p([dnl
It is an error to specify more than one of m4_ref(DB_DBT_MALLOC),
m4_ref(DB_DBT_REALLOC), and m4_ref(DB_DBT_USERMEM).])])
m4_tagend
m4_p([dnl
If m4_ref(DB_DBT_MALLOC) or m4_ref(DB_DBT_REALLOC) is specified, m4_db
allocates a properly sized byte array to contain the data. This can be
convenient if you know little about the nature of the data, specifically
the size of data in the database. However, if your application makes
repeated calls to retrieve keys or data, you may notice increased garbage
collection due to this allocation. If you know the maximum size of data
you are retrieving, you might decrease the memory burden and speed your
application by allocating your own byte array and using
m4_ref(DB_DBT_USERMEM). Even if you don't know the maximum size, you can
use this option and reallocate your array whenever your retrieval API call
returns an m4_ref(DB_BUFFER_SMALL) error or throws an exception
encapsulating an m4_ref(DB_BUFFER_SMALL).])
m4_tagbegin
m4_tag(m4_idef(DB_DBT_PARTIAL), [dnl
Do partial retrieval or storage of an item. If the calling application
is doing a get, the m4_arg(dlen) bytes starting m4_arg(doff) bytes from
the beginning of the retrieved data record are returned as if they
comprised the entire record. If any or all of the specified bytes do
not exist in the record, the get is successful, and any existing bytes
are returned.
m4_p([dnl
For example, if the data portion of a retrieved record was 100 bytes,
and a partial retrieval was done using a m4_ref(Dbt) having a m4_arg(dlen)
field of 20 and a m4_arg(doff) field of 85, the get call would succeed,
the m4_arg(data) field would refer to the last 15 bytes of the record,
and the m4_arg(size) field would be set to 15.])
m4_p([dnl
If the calling application is doing a put, the m4_arg(dlen) bytes starting
m4_arg(doff) bytes from the beginning of the specified key's data record
are replaced by the data specified by the m4_arg(data) and m4_arg(size)
objects.
If m4_arg(dlen) is smaller than m4_arg(size), the record will grow; if
m4_arg(dlen) is larger than m4_arg(size), the record will shrink.
If the specified bytes do not exist, the record will be extended using nul
bytes as necessary, and the put call will succeed.])
m4_p([dnl
It is an error to attempt a partial put using the m4_ref(dbh_put)
method in a database that supports duplicate records.
Partial puts in databases supporting duplicate records must be done
using a m4_ref(Dbc) method.])
m4_p([dnl
It is an error to attempt a partial put with differing m4_arg(dlen) and
m4_arg(size) values in Queue or Recno databases with fixed-length records.])
m4_p([dnl
For example, if the data portion of a retrieved record was 100 bytes,
and a partial put was done using a m4_ref(Dbt) having a m4_arg(dlen)
field of 20, a m4_arg(doff) field of 85, and a m4_arg(size) field of 30,
the resulting record would be 115 bytes in length, where the last 30
bytes would be those specified by the put call.])])
m4_tag(m4_idef(DB_DBT_APPMALLOC), [dnl
After an application-supplied callback routine passed to either
m4_ref(dbh_associate) or m4_ref(dbh_set_append_recno) is executed, the
m4_arg(data) field of a m4_ref(Dbt) may refer to memory allocated with
m4_manref(malloc, 3) or m4_manref(realloc, 3). In that case, the
callback sets the m4_ref(DB_DBT_APPMALLOC) flag in the m4_ref(Dbt) so
that m4_db will call m4_manref(free, 3) to deallocate the memory when it
is no longer required.])
m4_tag(m4_idef(DB_DBT_MULTIPLE), [dnl
Set in a secondary key creation callback routine passed to
m4_ref(dbh_associate) to indicate that multiple secondary keys should be
associated with the given primary key/data pair. If set, the
m4_arg(size) field indicates the number of secondary keys and the
m4_arg(data) field refers to an array of that number of m4_ref(Dbt)
structures.
m4_p([dnl
The m4_ref(DB_DBT_APPMALLOC) flag may be set on any of the m4_ref(Dbt)
structures to indicate that their m4_arg(data) field needs to be
freed.])])
m4_tagend
m4_paramend
m4_pf_description(m4_ref(dbt_get_flags))
m4_p([dnl
Return the object flag value.])
m4_page_footer

64
docs_src/db/m4.methods Normal file
View File

@@ -0,0 +1,64 @@
m4_comment([$Id: m4.methods,v 1.14 2007/07/12 18:27:42 bostic Exp $])
m4_table_begin(, _center)
m4_table_header(Database Operations, Description)
m4_comment([Db::])m4_table_element(m4_ref(ifelse(M4API, C_API, dbh_create, Db)), Create a database handle)
m4_comment([Db::associate])m4_table_element(m4_ref(dbh_associate), Associate a secondary index)
m4_comment([Db::close])m4_table_element(m4_ref(dbh_close), Close a database)
m4_comment([Db::compact])m4_table_element(m4_ref(dbh_compact), Compact a database)
m4_comment([Db::cursor])m4_table_element(m4_ref(dbh_cursor), Create a cursor)
m4_comment([Db::del])m4_table_element(m4_ref(dbh_del), Delete items from a database)
m4_comment([Db::err])m4_table_element([m4_ref(dbh_err), m4_ref(dbh_errx)], Error message)
m4_comment([Db::exists])m4_table_element(m4_ref(dbh_exists), Return if an item appears in a database)
m4_comment([Db::fd])m4_table_element(m4_ref(dbh_fd), Return a file descriptor from a database)
m4_comment([Db::get])m4_table_element([m4_ref(dbh_get), m4_ref(dbh_pget)], Get items from a database)
m4_comment([Db::get_byteswapped])m4_table_element(m4_ref(dbh_get_byteswapped), Return if the underlying database is in host order)
m4_comment([Db::get_type])m4_table_element(m4_ref(dbh_get_type), Return the database type)
m4_comment([Db::join])m4_table_element(m4_ref(dbh_join), Perform a database join on cursors)
m4_comment([Db::key_range])m4_table_element(m4_ref(dbh_key_range), Return estimate of key location)
m4_comment([Db::open])m4_table_element(m4_ref(dbh_open), Open a database)
m4_comment([Db::put])m4_table_element(m4_ref(dbh_put), Store items into a database)
m4_comment([Db::remove])m4_table_element(m4_ref(dbh_remove), Remove a database)
m4_comment([Db::rename])m4_table_element(m4_ref(dbh_rename), Rename a database)
m4_comment([Db::set_priority])m4_table_element([m4_ref(dbh_set_priority)], Set cache page priority)
m4_comment([Db::stat])m4_table_element([m4_ref(dbh_stat), m4_ref(dbh_stat_print)], Database statistics)
m4_comment([Db::sync])m4_table_element(m4_ref(dbh_sync), Flush a database to stable storage)
m4_comment([Db::truncate])m4_table_element(m4_ref(dbh_truncate), Empty a database)
m4_comment([Db::upgrade])m4_table_element(m4_ref(dbh_upgrade), Upgrade a database)
m4_comment([Db::verify])m4_table_element(m4_ref(dbh_verify), Verify/salvage a database)
m4_table_header(Database Configuration, _empty)
m4_comment([Db::set_alloc])m4_table_element( m4_ref(dbh_set_alloc), Set local space allocation functions)
m4_comment([Db::set_cachesize])m4_table_element(m4_ref(dbh_set_cachesize), Set the database cache size)
m4_comment([Db::set_dup_compare])m4_table_element(m4_ref(dbh_set_dup_compare), Set a duplicate comparison function)
m4_comment([Db::set_encrypt])m4_table_element(m4_ref(dbh_set_encrypt), Set the database cryptographic key)
m4_comment([Db::set_errcall])m4_table_element([m4_ref(dbh_set_errcall), m4_ref(dbh_set_msgcall)], Set error and informational message callback)
m4_comment([Db::set_errfile])m4_table_element([m4_ref(dbh_set_errfile), m4_ref(dbh_set_msgfile)], Set error and informational message FILE)
m4_comment([Db::set_error_stream])ifelse(M4API, C_API,, [m4_table_element([m4_ref(dbh_set_error_stream), m4_ref(dbh_set_message_stream)], Set error and informational message output stream)])
m4_comment([Db::set_errpfx])m4_table_element(m4_ref(dbh_set_errpfx), Set error message prefix)
m4_comment([Db::set_feedback])m4_table_element(m4_ref(dbh_set_feedback), Set feedback callback)
m4_comment([Db::set_flags])m4_table_element(m4_ref(dbh_set_flags), General database configuration)
m4_comment([Db::set_lorder])m4_table_element(m4_ref(dbh_set_lorder), Set the database byte order)
m4_comment([Db::set_pagesize])m4_table_element(m4_ref(dbh_set_pagesize), Set the underlying database page size)
m4_table_header(Btree/Recno Configuration, _empty)
m4_comment([Db::set_append_recno])m4_table_element(m4_ref(dbh_set_append_recno), Set record append callback)
m4_comment([Db::set_bt_compare])m4_table_element(m4_ref(dbh_set_bt_compare), Set a Btree comparison function)
m4_comment([Db::set_bt_minkey])m4_table_element(m4_ref(dbh_set_bt_minkey), Set the minimum number of keys per Btree page)
m4_comment([Db::set_bt_prefix])m4_table_element(m4_ref(dbh_set_bt_prefix), Set a Btree prefix comparison function)
m4_comment([Db::set_re_delim])m4_table_element(m4_ref(dbh_set_re_delim), Set the variable-length record delimiter)
m4_comment([Db::set_re_len])m4_table_element(m4_ref(dbh_set_re_len), Set the fixed-length record length)
m4_comment([Db::set_re_pad])m4_table_element(m4_ref(dbh_set_re_pad), Set the fixed-length record pad byte)
m4_comment([Db::set_re_source])m4_table_element(m4_ref(dbh_set_re_source), Set the backing Recno text file)
m4_table_header(Hash Configuration, _empty)
m4_comment([Db::set_h_compare])m4_table_element(m4_ref(dbh_set_h_compare), Set a Hash comparison function)
m4_comment([Db::set_h_ffactor])m4_table_element(m4_ref(dbh_set_h_ffactor), Set the Hash table density)
m4_comment([Db::set_h_hash])m4_table_element(m4_ref(dbh_set_h_hash), Set a hashing function)
m4_comment([Db::set_h_nelem])m4_table_element(m4_ref(dbh_set_h_nelem), Set the Hash table size)
m4_table_header(Queue Configuration, _empty)
m4_comment([Db::set_q_extentsize])m4_table_element(m4_ref(dbh_set_q_extentsize), Set Queue database extent size)
m4_table_end

4
docs_src/db_except/Makefile Normal file
View File

@@ -0,0 +1,4 @@
# $Id: Makefile,v 1.3 2004/08/13 03:38:56 bostic Exp $
CXX= except_class.html \
runrec_class.html

53
docs_src/db_except/except_class.so Normal file
View File

@@ -0,0 +1,53 @@
m4_comment([$Id: except_class.so,v 10.38 2004/09/28 15:04:19 bostic Exp $])
define(M4PAGELOCAL,
[DbException, except_get_env, except_get_errno, except_what])
include(m4/m4.seealso)
m4_pf_header(m4_ref(DbException),
ifelse(M4API, CXX_API, [dnl
class DbException {
public:
int get_errno() const;
virtual const char *what() const;
DbEnv *get_env() const;
};
]))
m4_p([dnl
This information describes the m4_ref(DbException) class and how it is
used by the various m4_db classes.])
ifelse(M4API, CXX_API, [dnl
m4_p([dnl
Most methods in the m4_db classes return an int, but also throw an
exception. This allows for two different error behaviors. By default,
the m4_db C++ API is configured to throw an exception whenever a serious
error occurs. This generally allows for cleaner logic for transaction
processing because a try block can surround a single transaction.
Alternatively, m4_db can be configured to not throw exceptions, and
instead have the individual function return an error code, by setting
the m4_ref(DB_CXX_NO_EXCEPTIONS) for the m4_ref(Db) and m4_ref(DbEnv)
constructors.])
m4_p([dnl
A DbException object contains an informational string, an errno, and a
reference to the environment from which the exception was thrown. The
errno can be obtained by using m4_ref(except_get_errno), and can be
used, in standard cases, to determine the type of the exception. The
informational string can be obtained by using m4_ref(except_what). And,
the environment can be obtained using m4_ref(except_get_env).])
m4_p([dnl
We expect in the future that this class will inherit from the standard
class exception, but certain language implementation bugs currently
prevent this on some platforms.])])
m4_p([dnl
Some methods may return non-zero values without issuing an exception.
This occurs in situations that are not normally considered an error, but
when some informational status is returned. For example,
m4_ref(dbh_get) returns m4_ref(DB_NOTFOUND) when a requested key does
not appear in the database.])
m4_page_footer

27
docs_src/db_except/runrec_class.so Normal file
View File

@@ -0,0 +1,27 @@
m4_comment([$Id: runrec_class.so,v 10.19 2004/08/13 03:38:56 bostic Exp $])
define(M4PAGELOCAL, DbRunRecoveryException)
include(m4/m4.seealso)
m4_pf_header(m4_ref(DbRunRecoveryException),
ifelse(M4API, C_API, [dnl
])
ifelse(M4API, CXX_API, [dnl
class DbRunRecoveryException : public DbException { ... };
]))
m4_p([dnl
This information describes the m4_ref(DbRunRecoveryException) class and
how it is used by the various m4_db classes.])
m4_p([dnl
Errors can occur in the m4_db library where the only solution is to shut
down the application and run recovery (for example, if m4_db is unable
to allocate heap memory). When a fatal error occurs in m4_db, methods
will throw a m4_ref(DbRunRecoveryException), at which point all
subsequent m4_db calls will also fail in the same way. When this
occurs, recovery should be performed.])
m4_p([dnl
The m4_ref(DbException) errno value is set to DB_RUNRECOVERY.])
m4_page_footer

11
docs_src/dbc/Makefile Normal file
View File

@@ -0,0 +1,11 @@
# $Id: Makefile,v 1.4 2007/05/08 21:37:19 bostic Exp $
COMMON= dbc_class.html \
dbc_close.html \
dbc_count.html \
dbc_del.html \
dbc_dup.html \
dbc_get.html \
dbc_list.html \
dbc_put.html \
dbc_set_priority.html

26
docs_src/dbc/dbc_class.so Normal file
View File

@@ -0,0 +1,26 @@
m4_comment([$Id: dbc_class.so,v 10.19 2004/08/13 03:38:56 bostic Exp $])
define(M4PAGELOCAL, Dbc)
include(m4/m4.seealso)
m4_pf_header(m4_ref(Dbc),
ifelse(M4API, C_API, [dnl
typedef struct __dbc DBC;
])
ifelse(M4API, CXX_API, [dnl
class Dbc { ... };
]))
m4_p([dnl
The m4_ref(Dbc) object is the handle for a cursor into a m4_db database.
The handle is not free-threaded. Cursor handles may be used by multiple
threads, but only serially, that is, the application must serialize
access to the m4_ref(Dbc) handle.])
m4_p([dnl
If the cursor is to be used to perform operations on behalf of a
transaction, the cursor must be opened and closed within the context of
that single transaction. Once m4_ref(dbc_close) has been called, the
handle may not be accessed again, regardless of the method's return.])
m4_page_footer

35
docs_src/dbc/dbc_close.so Normal file
View File

@@ -0,0 +1,35 @@
m4_comment([$Id: dbc_close.so,v 10.35 2006/10/24 13:26:50 bostic Exp $])
define(M4PAGELOCAL, dbc_close)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbc_close),
ifelse(M4API, C_API, [dnl
int
DBcursor-__GT__close(DBC *DBcursor);
])
ifelse(M4API, CXX_API, [dnl
int
Dbc::close(void);
]))
m4_p([dnl
The m4_refT(dbc_close) discards the cursor.])
m4_p([dnl
It is possible for the m4_refT(dbc_close) to return
m4_ref(DB_LOCK_DEADLOCK), signaling that any enclosing transaction should
be aborted. If the application is already intending to abort the
transaction, this error should be ignored, and the application should
proceed.])
m4_p([dnl
After m4_ref(dbc_close) has been called, regardless of its return, the
cursor handle may not be used again.])
m4_return(dbc_close, std)
m4_err(dbc_close, deadlock, einval, [the cursor is already closed])
m4_seealso(Dbc)
m4_page_footer

31
docs_src/dbc/dbc_count.so Normal file
View File

@@ -0,0 +1,31 @@
m4_comment([$Id: dbc_count.so,v 10.27 2007/10/24 16:06:07 bostic Exp $])
define(M4PAGELOCAL, dbc_count)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbc_count),
ifelse(M4API, C_API, [dnl
int
DBcursor-__GT__count(DBC *DBcursor, db_recno_t *countp, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Dbc::count(db_recno_t *countp, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbc_count) returns a count of the number of data items for
the key to which the cursor refers.])
m4_return(dbc_count, std)
m4_parambegin
m4_param_co(countp, count of the number of duplicate data items)
m4_unusedflags
m4_paramend
m4_err(dbc_count,
rephandle, replockout, einval, [the cursor has not been initialized])
m4_seealso(Dbc)
m4_page_footer

42
docs_src/dbc/dbc_del.so Normal file
View File

@@ -0,0 +1,42 @@
m4_comment([$Id: dbc_del.so,v 10.49 2007/10/24 16:06:07 bostic Exp $])
define(M4PAGELOCAL, [dbc_del])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbc_del),
ifelse(M4API, C_API, [dnl
int
DBcursor-__GT__del(DBC *DBcursor, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Dbc::del(u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbc_del) deletes the key/data pair to which the cursor
refers.])
m4_p([dnl
When called on a cursor opened on a database that has been made into a
secondary index using the m4_refT(dbh_associate), the m4_refT(dbh_del)
deletes the key/data pair from the primary database and all secondary
indices.])
m4_p([dnl
The cursor position is unchanged after a delete, and subsequent calls to
cursor functions expecting the cursor to refer to an existing key will
fail.])
m4_return(dbc_del,
specific, DB_KEYEMPTY, [if the element has already been deleted], prev)
m4_parambegin
m4_unusedflags
m4_paramend
m4_err(dbc_del, deadlock, rephandle, replockout, secondary_bad, readonly,
einval, [the cursor has not been initialized], cdbperm)
m4_seealso(Dbc)
m4_page_footer

42
docs_src/dbc/dbc_dup.so Normal file
View File

@@ -0,0 +1,42 @@
m4_comment([$Id: dbc_dup.so,v 10.34 2007/10/24 16:06:07 bostic Exp $])
define(M4PAGELOCAL, [dbc_dup, DB_POSITION])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbc_dup),
ifelse(M4API, C_API, [dnl
int
DBcursor-__GT__dup(DBC *DBcursor, DBC **cursorp, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Dbc::dup(Dbc **cursorp, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbc_dup) creates a new cursor that uses the same transaction
and locker ID as the original cursor. This is useful when an application
is using locking and requires two or more cursors in the same thread of
control.])
m4_return(dbc_dup, std)
m4_parambegin
m4_param(flags, [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_POSITION), [dnl
The newly created cursor is initialized to refer to the same position
in the database as the original cursor (if any) and hold the same locks
(if any). If the m4_ref(DB_POSITION) flag is not specified, or the
original cursor does not hold a database position and locks, the created
cursor is uninitialized and will behave like a cursor newly created
using m4_ref(dbh_cursor).])
m4_tagend])
m4_paramend
m4_err(dbc_dup, rephandle, replockout, einval)
m4_seealso(Dbc)
m4_page_footer

344
docs_src/dbc/dbc_get.so Normal file
View File

@@ -0,0 +1,344 @@
m4_comment([$Id: dbc_get.so,v 10.121 2007/10/24 16:06:07 bostic Exp $])
define(M4PAGELOCAL,
[dbc_get, dbc_pget, DB_CURRENT, DB_FIRST, DB_GET_BOTH,
DB_GET_BOTH_RANGE, DB_GET_RECNO, DB_IGNORE_LEASE, DB_JOIN_ITEM,
DB_LAST, DB_MULTIPLE, DB_MULTIPLE_KEY, DB_NEXT, DB_NEXT_DUP,
DB_NEXT_NODUP, DB_PREV, DB_PREV_DUP, DB_PREV_NODUP, DB_SET,
DB_SET_RANGE, DB_SET_RECNO])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbc_get),
ifelse(M4API, C_API, [dnl
int
DBcursor-__GT__get(DBC *DBcursor,
DBT *key, DBT *data, u_int32_t flags);
m4_blank
int
DBcursor-__GT__pget(DBC *DBcursor,
DBT *key, DBT *pkey, DBT *data, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Dbc::get(Dbt *key, Dbt *data, u_int32_t flags);
m4_blank
int
Dbc::pget(Dbt *key, Dbt *pkey, Dbt *data, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbc_get) retrieves key/data pairs from the database. The
address and length of the key are returned in the object to which
m4_arg(key) refers (except for the case of the m4_ref(DB_SET) flag, in
which the m4_arg(key) object is unchanged), and the address and length
of the data are returned in the object to which m4_arg(data) refers.])
m4_p([dnl
When called on a cursor opened on a database that has been made into a
secondary index using the m4_refT(dbh_associate), the m4_ref(dbc_get)
and m4_refT(dbc_pget)s return the key from the secondary index and the
data item from the primary database. In addition, the m4_refT(dbc_pget)
returns the key from the primary database. In databases that are not
secondary indices, the m4_refT(dbc_pget) will always fail.])
m4_p([dnl
Modifications to the database during a sequential scan will be reflected
in the scan; that is, records inserted behind a cursor will not be
returned while records inserted in front of a cursor will be returned.])
m4_p([dnl
In Queue and Recno databases, missing entries (that is, entries that
were never explicitly created or that were created and then deleted)
will be skipped during a sequential scan.])
m4_return(dbc_get, prev)
m4_p([dnl
If m4_ref(dbc_get) fails for any reason, the state of the cursor will be
unchanged.])
m4_parambegin
m4_param_data
m4_param(flags, [dnl
m4_sf_must
m4_tagbegin
m4_tag(m4_idef(DB_CURRENT), [dnl
Return the key/data pair to which the cursor refers.
m4_return(dbc_get, specific, DB_KEYEMPTY,
[if m4_ref(DB_CURRENT) is set and the cursor key/data pair was deleted])])
m4_tag([m4_idef(DB_FIRST)], [dnl
The cursor is set to refer to the first key/data pair of the database,
and that pair is returned. If the first key has duplicate values, the
first data item in the set of duplicates is returned.
m4_p([dnl
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
m4_ref(DB_FIRST) flag will ignore any keys that exist but were never
explicitly created by the application, or were created and later
deleted.])
m4_return(dbc_get, specific, DB_NOTFOUND,
[if m4_ref(DB_FIRST) is set and the database is empty])])
m4_tag(m4_idef(DB_GET_BOTH), [dnl
The m4_ref(DB_GET_BOTH) flag is identical to the m4_ref(DB_SET) flag,
except that both the key and the data parameters must be matched by the
key and data item in the database.
m4_p([dnl
When used with the m4_refT(dbc_pget) version of this method on a
secondary index handle, both the secondary and primary keys must be
matched by the secondary and primary key item in the database. It is
an error to use the m4_ref(DB_GET_BOTH) flag with the m4_ref(dbc_get)
version of this method and a cursor that has been opened on a secondary
index handle.])])
m4_tag(m4_idef(DB_GET_BOTH_RANGE), [dnl
The m4_ref(DB_GET_BOTH_RANGE) flag is identical to the m4_ref(DB_GET_BOTH)
flag, except that, in the case of any database supporting sorted
duplicate sets, the returned key/data pair is the smallest data item
greater than or equal to the specified data item (as determined by the
comparison function), permitting partial matches and range searches in
duplicate data sets.])
m4_tag(m4_idef(DB_GET_RECNO), [dnl
Return the record number associated with the cursor. The record number
will be returned in m4_arg(data), as described in m4_ref(Dbt). The
m4_arg(key) parameter is ignored.
m4_p([dnl
For m4_ref(DB_GET_RECNO) to be specified, the underlying database must be
of type Btree, and it must have been created with the m4_ref(DB_RECNUM)
flag.])
m4_p([dnl
When called on a cursor opened on a database that has been made into a
secondary index, the m4_ref(dbc_get) and m4_refT(dbc_pget)s return the
record number of the primary database in m4_arg(data). In addition, the
m4_refT(dbc_pget) returns the record number of the secondary index in
m4_arg(pkey). If either underlying database is not of type Btree or is
not created with the m4_ref(DB_RECNUM) flag, the out-of-band record
number of 0 is returned.])])
m4_tag(m4_idef(DB_JOIN_ITEM), [dnl
Do not use the data value found in all of the cursors as a lookup key for
the primary database, but simply return it in the key parameter instead.
The data parameter is left unchanged.
m4_p([dnl
For m4_ref(DB_JOIN_ITEM) to be specified, the underlying cursor must have
been returned from the m4_refT(dbh_join).])])
m4_tag([m4_idef(DB_LAST)], [dnl
The cursor is set to refer to the last key/data pair of the database,
and that pair is returned. If the last key has duplicate values, the
last data item in the set of duplicates is returned.
m4_p([dnl
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
m4_ref(DB_LAST) flag will ignore any keys that exist but were never
explicitly created by the application, or were created and later
deleted.])
m4_return(dbc_get, specific, DB_NOTFOUND,
[if m4_ref(DB_LAST) is set and the database is empty])])
m4_tag([m4_idef(DB_NEXT)], [dnl
If the cursor is not yet initialized, m4_ref(DB_NEXT) is identical to
m4_ref(DB_FIRST). Otherwise, the cursor is moved to the next key/data
pair of the database, and that pair is returned. In the presence of
duplicate key values, the value of the key may not change.
m4_p([dnl
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
m4_ref(DB_NEXT) flag will skip any keys that exist but were never
explicitly created by the application, or those that were created and
later deleted.])
m4_return(dbc_get, specific, DB_NOTFOUND,
[if m4_ref(DB_NEXT) is set and the cursor is already on the last record
in the database])])
m4_tag(m4_idef(DB_NEXT_DUP), [dnl
If the next key/data pair of the database is a duplicate data record for
the current key/data pair, the cursor is moved to the next key/data pair
of the database, and that pair is returned.
m4_return(dbc_get, specific, DB_NOTFOUND,
[if m4_ref(DB_NEXT_DUP) is set and the next key/data pair of the
database is not a duplicate data record for the current key/data pair])])
m4_tag([dnl
m4_idef(DB_NEXT_NODUP)], [dnl
If the cursor is not yet initialized, m4_ref(DB_NEXT_NODUP) is identical
to m4_ref(DB_FIRST). Otherwise, the cursor is moved to the next
non-duplicate key of the database, and that key/data pair is returned.
m4_p([dnl
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
m4_ref(DB_NEXT_NODUP) flag will ignore any keys that exist but were
never explicitly created by the application, or those that were created
and later deleted.])
m4_return(dbc_get, specific, DB_NOTFOUND,
[if m4_ref(DB_NEXT_NODUP) is set and no non-duplicate key/data pairs
occur after the cursor position in the database])])
m4_tag([m4_idef(DB_PREV)], [dnl
If the cursor is not yet initialized, m4_ref(DB_PREV) is identical to
m4_ref(DB_LAST). Otherwise, the cursor is moved to the previous
key/data pair of the database, and that pair is returned. In the
presence of duplicate key values, the value of the key may not change.
m4_p([dnl
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
m4_ref(DB_PREV) flag will skip any keys that exist but were never
explicitly created by the application, or those that were created and
later deleted.])
m4_return(dbc_get, specific, DB_NOTFOUND,
[if m4_ref(DB_PREV) is set and the cursor is already on the first record
in the database])])
m4_tag(m4_idef(DB_PREV_DUP), [dnl
If the previous key/data pair of the database is a duplicate data record
for the current key/data pair, the cursor is moved to the previous key/data
pair of the database, and that pair is returned.
m4_return(dbc_get, specific, DB_NOTFOUND,
[if m4_ref(DB_PREV_DUP) is set and the previous key/data pair of the
database is not a duplicate data record for the current key/data pair])])
m4_tag([dnl
m4_idef(DB_PREV_NODUP)], [dnl
If the cursor is not yet initialized, m4_ref(DB_PREV_NODUP) is identical
to m4_ref(DB_LAST). Otherwise, the cursor is moved to the previous
non-duplicate key of the database, and that key/data pair is returned.
m4_p([dnl
If the database is a Queue or Recno database, m4_ref(dbc_get) using the
m4_ref(DB_PREV_NODUP) flag will ignore any keys that exist but were
never explicitly created by the application, or those that were created
and later deleted.])
m4_return(dbc_get, specific, DB_NOTFOUND,
[if m4_ref(DB_PREV_NODUP) is set and no non-duplicate key/data pairs
occur before the cursor position in the database])])
m4_tag(m4_idef(DB_SET), [dnl
Move the cursor to the specified key/data pair of the database, and
return the datum associated with the given key.
m4_return(dbc_get, specific, DB_NOTFOUND, [if m4_ref(DB_SET) is set and
no matching keys are found],
specific, DB_KEYEMPTY, [if m4_ref(DB_SET) is set and the database is a
Queue or Recno database, and the specified key exists, but was never
explicitly created by the application or was later deleted],
[In the presence of duplicate key values, m4_ref(dbc_get) will return the
first data item for the given key.])])
m4_tag(m4_idef(DB_SET_RANGE), [dnl
The m4_ref(DB_SET_RANGE) flag is identical to the m4_ref(DB_SET) flag,
except that in the case of the Btree access method, the key is returned
as well as the data item and the returned key/data pair is the smallest
key greater than or equal to the specified key (as determined by the
Btree comparison function), permitting partial key matches and range
searches.])
m4_tag(m4_idef(DB_SET_RECNO), [dnl
Move the cursor to the specific numbered record of the database, and
return the associated key/data pair. The m4_arg(data) field of the
specified m4_arg(key) must be a pointer to a memory location from which
a m4_ref(db_recno_t) may be read, as described in m4_ref(Dbt). This
memory location will be read to determine the record to be retrieved.
m4_p([dnl
For m4_ref(DB_SET_RECNO) to be specified, the underlying database must be
of type Btree, and it must have been created with the m4_ref(DB_RECNUM)
flag.])])
m4_tagend
m4_sf_or_add(1)
m4_tagbegin
m4_tag(m4_idef(DB_IGNORE_LEASE), [dnl
Return the data item irrespective of the state of master leases. The
item will be returned under all conditions: if master leases are not
configured, if the request is made to a client, if the request is made
to a master with a valid lease, or if the request is made to a master
without a valid lease.])
m4_tag(m4_idef(DB_READ_UNCOMMITTED), [dnl
Database items read during a transactional call will have degree 1
isolation, including modified but not yet committed data. Silently
ignored if the m4_ref(DB_READ_UNCOMMITTED) flag was not specified when
the underlying database was opened.])
m4_tag(m4_idef(DB_MULTIPLE), [dnl
Return multiple data items in the m4_arg(data) parameter.
m4_p([dnl
In the case of Btree or Hash databases, duplicate data items for the
current key, starting at the current cursor position, are entered into
the buffer. Subsequent calls with both the m4_ref(DB_NEXT_DUP) and
m4_ref(DB_MULTIPLE) flags specified will return additional duplicate
data items associated with the current key or m4_ref(DB_NOTFOUND) if
there are no additional duplicate data items to return. Subsequent
calls with both the m4_ref(DB_NEXT) and m4_ref(DB_MULTIPLE) flags
specified will return additional duplicate data items associated with
the current key or if there are no additional duplicate data items will
return the next key and its data items or m4_ref(DB_NOTFOUND) if there
are no additional keys in the database.])
m4_p([dnl
In the case of Queue or Recno databases, data items starting at the
current cursor position are entered into the buffer. The record number
of the first record will be returned in the m4_arg(key) parameter. The
record number of each subsequent returned record must be calculated from
this value. Subsequent calls with the m4_ref(DB_MULTIPLE) flag
specified will return additional data items or m4_ref(DB_NOTFOUND) if
there are no additional data items to return.])
m4_p([dnl
m4_bulk_mem])
m4_p([dnl
The multiple data items can be iterated over using the
ifelse(M4API, C_API, m4_ref(DB_MULTIPLE_NEXT) macro,
m4_ref(DbMultipleDataIterator) class).])
m4_p([dnl
The m4_ref(DB_MULTIPLE) flag may only be used with the
m4_ref(DB_CURRENT), m4_ref(DB_FIRST), m4_ref(DB_GET_BOTH),
m4_ref(DB_GET_BOTH_RANGE), m4_ref(DB_NEXT), m4_ref(DB_NEXT_DUP),
m4_ref(DB_NEXT_NODUP), m4_ref(DB_SET), m4_ref(DB_SET_RANGE), and
m4_ref(DB_SET_RECNO) options. The m4_ref(DB_MULTIPLE) flag may not be
used when accessing databases made into secondary indices using the
m4_refT(dbh_associate).])])
m4_tag(m4_idef(DB_MULTIPLE_KEY), [dnl
Return multiple key and data pairs in the m4_arg(data) parameter.
m4_p([dnl
Key and data pairs, starting at the current cursor position, are entered
into the buffer. Subsequent calls with both the m4_ref(DB_NEXT) and
m4_ref(DB_MULTIPLE_KEY) flags specified will return additional key and data
pairs or m4_ref(DB_NOTFOUND) if there are no additional key and data
items to return.])
m4_p([dnl
In the case of Btree or Hash databases,
the multiple key and data pairs can be iterated over using the
ifelse(M4API, C_API, m4_ref(DB_MULTIPLE_KEY_NEXT) macro,
m4_ref(DbMultipleKeyDataIterator) class).])
m4_p([dnl
In the case of Queue or Recno databases,
the multiple record number and data pairs can be iterated over using the
ifelse(M4API, C_API, m4_ref(DB_MULTIPLE_RECNO_NEXT) macro,
m4_ref(DbMultipleRecnoDataIterator) class).])
m4_p([dnl
m4_bulk_mem])
m4_p([dnl
The m4_ref(DB_MULTIPLE_KEY) flag may only be used with the
m4_ref(DB_CURRENT), m4_ref(DB_FIRST), m4_ref(DB_GET_BOTH),
m4_ref(DB_GET_BOTH_RANGE), m4_ref(DB_NEXT), m4_ref(DB_NEXT_DUP),
m4_ref(DB_NEXT_NODUP), m4_ref(DB_SET), m4_ref(DB_SET_RANGE), and
m4_ref(DB_SET_RECNO) options. The m4_ref(DB_MULTIPLE_KEY) flag may not
be used when accessing databases made into secondary indices using the
m4_refT(dbh_associate).])])
m4_rmw_flag()
m4_tagend])
m4_param_key
m4_param(pkey, [The secondary index key m4_ref(Dbt) operated on.])
m4_paramend
m4_err(dbc_get,
buffersmall,
[requested item could not be returned due to undersized buffer],
deadlock, rephandle, replease, replockout, secondary_bad, einval,
[the m4_ref(DB_CURRENT), m4_ref(DB_NEXT_DUP) or m4_ref(DB_PREV_DUP) flags
were specified and the cursor has not been initialized;
the m4_refT(dbc_pget) was called with a cursor that does not refer to a
secondary index])
m4_seealso(Dbc)
m4_page_footer

7
docs_src/dbc/dbc_list.so Normal file
View File

@@ -0,0 +1,7 @@
m4_comment([$Id: dbc_list.so,v 1.1 2002/08/30 20:00:49 bostic Exp $])
m4_page_title([m4_db: Database Cursors and Related Methods])
include(dbc/m4.methods)
m4_page_footer

140
docs_src/dbc/dbc_put.so Normal file
View File

@@ -0,0 +1,140 @@
m4_comment([$Id: dbc_put.so,v 10.64 2007/10/24 16:06:07 bostic Exp $])
define(M4PAGELOCAL,
[dbc_put, DB_AFTER, DB_BEFORE, DB_CURRENT, DB_KEYFIRST,
DB_KEYLAST, DB_NODUPDATA])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbc_put),
ifelse(M4API, C_API, [dnl
int
DBcursor-__GT__put(DBC *DBcursor, DBT *key, DBT *data, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Dbc::put(Dbt *key, Dbt *data, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbc_put) stores key/data pairs into the database.])
m4_return(dbc_put, prev)
m4_p([dnl
If m4_ref(dbc_put) fails for any reason, the state of the cursor will be
unchanged. If m4_ref(dbc_put) succeeds and an item is inserted into the
database, the cursor is always positioned to refer to the newly inserted
item.])
m4_parambegin
m4_param_data
m4_param(flags, [dnl
m4_sf_must
m4_tagbegin
m4_tag(m4_idef(DB_AFTER), [dnl
In the case of the Btree and Hash access methods, insert the data
element as a duplicate element of the key to which the cursor refers.
The new element appears immediately after the current cursor position.
It is an error to specify m4_ref(DB_AFTER) if the underlying Btree or
Hash database is not configured for unsorted duplicate data items. The
m4_arg(key) parameter is ignored.
m4_p([dnl
In the case of the Recno access method, it is an error to specify
m4_ref(DB_AFTER) if the underlying Recno database was not created with
the m4_ref(DB_RENUMBER) flag. If the m4_ref(DB_RENUMBER) flag was
specified, a new key is created, all records after the inserted item
are automatically renumbered, and the key of the new record is returned
in the structure to which the m4_arg(key) parameter refers. The initial
value of the m4_arg(key) parameter is ignored. See m4_ref(dbh_open)
for more information.])
m4_p([dnl
The m4_ref(DB_AFTER) flag may not be specified to the Queue access method.])
m4_return(dbc_put,
specific, DB_NOTFOUND,
[if the current cursor record has already been deleted and the
underlying access method is Hash])])
m4_tag(m4_idef(DB_BEFORE), [dnl
In the case of the Btree and Hash access methods, insert the data
element as a duplicate element of the key to which the cursor refers.
The new element appears immediately before the current cursor position.
It is an error to specify m4_ref(DB_AFTER) if the underlying Btree or
Hash database is not configured for unsorted duplicate data items. The
m4_arg(key) parameter is ignored.
m4_p([dnl
In the case of the Recno access method, it is an error to specify
m4_ref(DB_BEFORE) if the underlying Recno database was not created with
the m4_ref(DB_RENUMBER) flag. If the m4_ref(DB_RENUMBER) flag was
specified, a new key is created, the current record and all records
after it are automatically renumbered, and the key of the new record is
returned in the structure to which the m4_arg(key) parameter refers.
The initial value of the m4_arg(key) parameter is ignored. See
m4_ref(dbh_open) for more information.])
m4_p([dnl
The m4_ref(DB_BEFORE) flag may not be specified to the Queue access method.])
m4_return(dbc_put,
specific, DB_NOTFOUND,
[if the current cursor record has already been deleted and the underlying
access method is Hash])])
m4_tag(m4_idef(DB_CURRENT), [dnl
Overwrite the data of the key/data pair to which the cursor refers with
the specified data item. The m4_arg(key) parameter is ignored.
m4_return(dbc_put,
specific, DB_NOTFOUND,
[if the current cursor record has already been deleted])])
m4_tag(m4_idef(DB_KEYFIRST), [dnl
Insert the specified key/data pair into the database.
m4_p([dnl
If the underlying database supports duplicate data items, and if the
key already exists in the database and a duplicate sort function has
been specified, the inserted data item is added in its sorted location.
If the key already exists in the database and no duplicate sort function
has been specified, the inserted data item is added as the first of the
data items for that key.])])
m4_tag(m4_idef(DB_KEYLAST), [dnl
Insert the specified key/data pair into the database.
m4_p([dnl
If the underlying database supports duplicate data items, and if the
key already exists in the database and a duplicate sort function has
been specified, the inserted data item is added in its sorted location.
If the key already exists in the database, and no duplicate sort
function has been specified, the inserted data item is added as the last
of the data items for that key.])])
m4_tag(m4_idef(DB_NODUPDATA), [dnl
In the case of the Btree and Hash access methods, insert the specified
key/data pair into the database, unless a key/data pair comparing
equally to it already exists in the database. If a matching key/data
pair already exists in the database, m4_ref(DB_KEYEXIST) is returned.
The DB_NODUPDATA flag may only be specified if the underlying
database has been configured to support sorted duplicate data items.
m4_p([dnl
The DB_NODUPDATA flag may not be specified to the Queue or Recno
access methods.])])
m4_tagend])
m4_param_key
m4_paramend
m4_err(dbc_put, deadlock, rephandle, replockout, readonly, einval,
[the m4_ref(DB_AFTER), m4_ref(DB_BEFORE) or m4_ref(DB_CURRENT) flags
were specified and the cursor has not been initialized;
the m4_ref(DB_AFTER) or m4_ref(DB_BEFORE) flags were specified and a
duplicate sort function has been specified;
the m4_ref(DB_CURRENT) flag was specified, a duplicate sort function has
been specified, and the data item of the referenced key/data pair does
not compare equally to the m4_arg(data) parameter;
the m4_ref(DB_AFTER) or m4_ref(DB_BEFORE) flags were specified, and the
underlying access method is Queue;
an attempt was made to add a record to a fixed-length database that was too
large to fit;
an attempt was made to add a record to a secondary index],
cdbperm)
m4_seealso(Dbc)
m4_page_footer

64
docs_src/dbc/dbc_set_priority.so Normal file
View File

@@ -0,0 +1,64 @@
m4_comment([$Id: dbc_set_priority.so,v 1.3 2007/05/22 18:06:05 bostic Exp $])
include(m4/m4.seealso)
ifdef([M4INTERFACE],, [dnl
define(M4INTERFACE, dbc_set_priority)
define(M4PAGELOCAL, [dbc_get_priority, dbc_set_priority,
DB_PRIORITY_VERY_LOW, DB_PRIORITY_LOW, DB_PRIORITY_DEFAULT,
DB_PRIORITY_HIGH, DB_PRIORITY_VERY_HIGH])
m4_pf_header(m4_ref(dbc_set_priority),
ifelse(M4API, C_API, [dnl
int
DbCursor-__GT__set_priority(DBC *DbCursor, DB_CACHE_PRIORITY priority);
m4_blank
int
DbCursor-__GT__get_priority(DBC *DbCursor, DB_CACHE_PRIORITY *priorityp);
])
ifelse(M4API, CXX_API, [dnl
int
Dbc::set_priority(DB_CACHE_PRIORITY priority);
m4_blank
int
Dbc::get_priority(DB_CACHE_PRIORITY *priorityp);
]))])
m4_p([dnl
Set the cache priority for pages referenced by the
ifelse(M4INTERFACE, dbh_set_priority, m4_ref(Db),
M4INTERFACE, memp_set_priority, m4_ref(DbMpoolFile), m4_ref(Dbc))
handle.])
m4_cache_priority_explain(M4INTERFACE)
ifelse(M4INTERFACE, memp_set_priority,[dnl
m4_p([dnl
To set the priority for the pages belonging to a particular database,
call the m4_refT(memp_set_priority) using the m4_ref(DbMpoolFile) handle
returned by the m4_refT(dbh_get_mpf).])
m4_scope_mpf(memp_set_priority)])
m4_when_any(M4INTERFACE)
m4_return(M4INTERFACE, std)
m4_parambegin
m4_cache_priority_parameter
m4_paramend
ifelse(M4INTERFACE, memp_set_priority,
m4_pf_getter(memp_get_priority,
cache priority for the file referenced by the m4_ref(DbMpoolFile) handle,,
priorityp, reference),
m4_pf_getter(
ifelse(M4INTERFACE, dbh_set_priority, dbh_get_priority, dbc_get_priority),
cache priority for pages referenced by the
ifelse(M4INTERFACE, dbh_set_priority, m4_ref(Db), m4_ref(Dbc))
handle,, priorityp, reference))
m4_seealso(
ifelse(M4INTERFACE, dbh_set_priority, Db,
M4INTERFACE, memp_set_priority, DbMpool, Dbc))
m4_page_footer

15
docs_src/dbc/m4.methods Normal file
View File

@@ -0,0 +1,15 @@
m4_comment([$Id: m4.methods,v 1.5 2007/05/08 21:37:19 bostic Exp $])
m4_table_begin(, _center)
m4_table_header(Database Cursors and Related Methods, Description)
m4_comment([Db::cursor])m4_table_element(m4_ref(dbh_cursor), Create a cursor)
m4_comment([DbCursor::close])m4_table_element(m4_ref(dbc_close), Close a cursor)
m4_comment([DbCursor::count])m4_table_element(m4_ref(dbc_count), Return count of duplicates)
m4_comment([DbCursor::del])m4_table_element(m4_ref(dbc_del), Delete by cursor)
m4_comment([DbCursor::dup])m4_table_element(m4_ref(dbc_dup), Duplicate a cursor)
m4_comment([DbCursor::get])m4_table_element([m4_ref(dbc_get), m4_ref(dbc_pget)], Retrieve by cursor)
m4_comment([DbCursor::put])m4_table_element(m4_ref(dbc_put), Store by cursor)
m4_comment([DbCursor::set_priority])m4_table_element(m4_ref(dbc_set_priority), Set the cursor's cache priority)
m4_table_end

3
docs_src/dbt/Makefile Normal file
View File

@@ -0,0 +1,3 @@
# $Id: Makefile,v 10.5 2006/10/05 01:06:04 bostic Exp $
COMMON= dbt_package.html

19
docs_src/dbt/dbt_package.so Normal file
View File

@@ -0,0 +1,19 @@
m4_comment([$Id: dbt_package.so,v 10.2 2004/08/29 14:00:03 bostic Exp $])
m4_page_title([DBT and Bulk Get Operations])
m4_table_begin(, _center)
m4_table_header(DBT and Bulk Get Operations, Description)
m4_table_element(m4_ref(Dbt), Key/data pairs)
ifelse(M4API, C_API, [dnl
m4_table_element(m4_ref(DB_MULTIPLE_INIT), Initialize bulk get retrieval)
m4_table_element(m4_ref(DB_MULTIPLE_NEXT), Next bulk get retrieval)
m4_table_element(m4_ref(DB_MULTIPLE_KEY_NEXT), Next bulk get retrieval)
m4_table_element(m4_ref(DB_MULTIPLE_RECNO_NEXT), Next bulk get retrieval)],[dnl
m4_table_element(m4_ref(DbMultipleDataIterator), Next bulk get retrieval)
m4_table_element(m4_ref(DbMultipleKeyDataIterator), Next bulk get retrieval)
m4_table_element(m4_ref(DbMultipleRecnoDataIterator), Next bulk get retrieval)])
m4_table_end
m4_page_footer

48
docs_src/env/Makefile vendored Normal file
View File

@@ -0,0 +1,48 @@
# $Id: Makefile,v 10.106 2008/01/12 13:42:40 bostic Exp $
COMMON= api_core.html \
env_class.html \
env_close.html \
env_dbremove.html \
env_dbrename.html \
env_err.html \
env_event_notify.html \
env_failchk.html \
env_fileid_reset.html \
env_list.html \
env_lsn_reset.html \
env_open.html \
env_remove.html \
env_set_app_dispatch.html \
env_set_cachesize.html \
env_set_data_dir.html \
env_set_encrypt.html \
env_set_errcall.html \
env_set_errpfx.html \
env_set_feedback.html \
env_set_flags.html \
env_set_isalive.html \
env_set_msgcall.html \
env_set_rpc_server.html \
env_set_intermediate_dir_mode.html \
env_set_shm_key.html \
env_set_thread_count.html \
env_set_thread_id.html \
env_set_thread_id_string.html \
env_set_timeout.html \
env_set_tmp_dir.html \
env_set_verbose.html \
env_strerror.html \
env_version.html
C= env_set_alloc.html \
env_set_errfile.html \
env_set_msgfile.html \
env_stat.html
CXX= env_set_alloc.html \
env_set_errfile.html \
env_set_error_stream.html \
env_set_msg_stream.html \
env_set_msgfile.html \
env_stat.html

214
docs_src/env/api_core.so vendored Normal file
View File

@@ -0,0 +1,214 @@
m4_comment([DO NOT EDIT: automatically built by build script.])
m4_page_title([m4_db: ifelse(M4API, C_API, C, C++) Handle Methods (version M4MAJOR.M4MINOR.M4PATCH)])
m4_table_begin(, _center)
m4_table_header(ifelse(M4API, C_API, C, C++) Handle Methods, Description)
m4_comment([Db::])m4_table_element(m4_ref(ifelse(M4API, C_API, dbh_create, Db)), Create a database handle)
m4_comment([Db::associate])m4_table_element(m4_ref(dbh_associate), Associate a secondary index)
m4_comment([Db::close])m4_table_element(m4_ref(dbh_close), Close a database)
m4_comment([Db::compact])m4_table_element(m4_ref(dbh_compact), Compact a database)
m4_comment([Db::cursor])m4_table_element(m4_ref(dbh_cursor), Create a cursor)
m4_comment([Db::del])m4_table_element(m4_ref(dbh_del), Delete items from a database)
m4_comment([Db::err])m4_table_element([m4_ref(dbh_err), m4_ref(dbh_errx)], Error message)
m4_comment([Db::exists])m4_table_element(m4_ref(dbh_exists), Return if an item appears in a database)
m4_comment([Db::fd])m4_table_element(m4_ref(dbh_fd), Return a file descriptor from a database)
m4_comment([Db::get])m4_table_element([m4_ref(dbh_get), m4_ref(dbh_pget)], Get items from a database)
m4_comment([Db::get_byteswapped])m4_table_element(m4_ref(dbh_get_byteswapped), Return if the underlying database is in host order)
m4_comment([Db::get_env])m4_table_element(m4_ref(dbh_getenv), Return m4_ref(Db)'s underlying m4_ref(DbEnv) handle)
m4_comment([Db::get_type])m4_table_element(m4_ref(dbh_get_type), Return the database type)
m4_comment([Db::join])m4_table_element(m4_ref(dbh_join), Perform a database join on cursors)
m4_comment([Db::key_range])m4_table_element(m4_ref(dbh_key_range), Return estimate of key location)
m4_comment([Db::mpf])m4_table_element(m4_ref(dbh_get_mpf), Return m4_ref(Db)'s underlying m4_ref(DbMpoolFile) handle)
m4_comment([Db::open])m4_table_element(m4_ref(dbh_open), Open a database)
m4_comment([Db::put])m4_table_element(m4_ref(dbh_put), Store items into a database)
m4_comment([Db::remove])m4_table_element(m4_ref(dbh_remove), Remove a database)
m4_comment([Db::rename])m4_table_element(m4_ref(dbh_rename), Rename a database)
m4_comment([Db::set_alloc])m4_table_element( m4_ref(dbh_set_alloc), Set local space allocation functions)
m4_comment([Db::set_append_recno])m4_table_element(m4_ref(dbh_set_append_recno), Set record append callback)
m4_comment([Db::set_bt_compare])m4_table_element(m4_ref(dbh_set_bt_compare), Set a Btree comparison function)
m4_comment([Db::set_bt_minkey])m4_table_element(m4_ref(dbh_set_bt_minkey), Set the minimum number of keys per Btree page)
m4_comment([Db::set_bt_prefix])m4_table_element(m4_ref(dbh_set_bt_prefix), Set a Btree prefix comparison function)
m4_comment([Db::set_cachesize])m4_table_element(m4_ref(dbh_set_cachesize), Set the database cache size)
m4_comment([Db::set_dup_compare])m4_table_element(m4_ref(dbh_set_dup_compare), Set a duplicate comparison function)
m4_comment([Db::set_encrypt])m4_table_element(m4_ref(dbh_set_encrypt), Set the database cryptographic key)
m4_comment([Db::set_errcall])m4_table_element([m4_ref(dbh_set_errcall), m4_ref(dbh_set_msgcall)], Set error and informational message callback)
m4_comment([Db::set_errfile])m4_table_element([m4_ref(dbh_set_errfile), m4_ref(dbh_set_msgfile)], Set error and informational message FILE)
m4_comment([Db::set_error_stream])ifelse(M4API, C_API,, [m4_table_element([m4_ref(dbh_set_error_stream), m4_ref(dbh_set_message_stream)], Set error and informational message output stream)])
m4_comment([Db::set_errpfx])m4_table_element(m4_ref(dbh_set_errpfx), Set error message prefix)
m4_comment([Db::set_feedback])m4_table_element(m4_ref(dbh_set_feedback), Set feedback callback)
m4_comment([Db::set_flags])m4_table_element(m4_ref(dbh_set_flags), General database configuration)
m4_comment([Db::set_h_compare])m4_table_element(m4_ref(dbh_set_h_compare), Set a Hash comparison function)
m4_comment([Db::set_h_ffactor])m4_table_element(m4_ref(dbh_set_h_ffactor), Set the Hash table density)
m4_comment([Db::set_h_hash])m4_table_element(m4_ref(dbh_set_h_hash), Set a hashing function)
m4_comment([Db::set_h_nelem])m4_table_element(m4_ref(dbh_set_h_nelem), Set the Hash table size)
m4_comment([Db::set_lorder])m4_table_element(m4_ref(dbh_set_lorder), Set the database byte order)
m4_comment([Db::set_pagesize])m4_table_element(m4_ref(dbh_set_pagesize), Set the underlying database page size)
m4_comment([Db::set_priority])m4_table_element([m4_ref(dbh_set_priority)], Set cache page priority)
m4_comment([Db::set_q_extentsize])m4_table_element(m4_ref(dbh_set_q_extentsize), Set Queue database extent size)
m4_comment([Db::set_re_delim])m4_table_element(m4_ref(dbh_set_re_delim), Set the variable-length record delimiter)
m4_comment([Db::set_re_len])m4_table_element(m4_ref(dbh_set_re_len), Set the fixed-length record length)
m4_comment([Db::set_re_pad])m4_table_element(m4_ref(dbh_set_re_pad), Set the fixed-length record pad byte)
m4_comment([Db::set_re_source])m4_table_element(m4_ref(dbh_set_re_source), Set the backing Recno text file)
m4_comment([Db::stat])m4_table_element([m4_ref(dbh_stat), m4_ref(dbh_stat_print)], Database statistics)
m4_comment([Db::sync])m4_table_element(m4_ref(dbh_sync), Flush a database to stable storage)
m4_comment([Db::truncate])m4_table_element(m4_ref(dbh_truncate), Empty a database)
m4_comment([Db::upgrade])m4_table_element(m4_ref(dbh_upgrade), Upgrade a database)
m4_comment([Db::verify])m4_table_element(m4_ref(dbh_verify), Verify/salvage a database)
m4_comment([DbCursor::close])m4_table_element(m4_ref(dbc_close), Close a cursor)
m4_comment([DbCursor::count])m4_table_element(m4_ref(dbc_count), Return count of duplicates)
m4_comment([DbCursor::del])m4_table_element(m4_ref(dbc_del), Delete by cursor)
m4_comment([DbCursor::dup])m4_table_element(m4_ref(dbc_dup), Duplicate a cursor)
m4_comment([DbCursor::get])m4_table_element([m4_ref(dbc_get), m4_ref(dbc_pget)], Retrieve by cursor)
m4_comment([DbCursor::put])m4_table_element(m4_ref(dbc_put), Store by cursor)
m4_comment([DbCursor::set_priority])m4_table_element(m4_ref(dbc_set_priority), Set the cursor's cache priority)
m4_comment([DbDeadlockException])ifelse(M4API, CXX_API, [m4_table_element(m4_ref(DbDeadlockException), Deadlock exception)])
m4_comment([DbEnv::])m4_table_element(m4_ref(ifelse(M4API, C_API, dbenv_create, DbEnv)), Create an environment handle)
m4_comment([DbEnv::cdsgroup_begin])m4_table_element(m4_ref(cdsgroup_begin), Get a locker ID in m4_cam)
m4_comment([DbEnv::close])m4_table_element(m4_ref(dbenv_close), Close an environment)
m4_comment([DbEnv::dbremove])m4_table_element(m4_ref(dbenv_dbremove), Remove a database)
m4_comment([DbEnv::dbrename])m4_table_element(m4_ref(dbenv_dbrename), Rename a database)
m4_comment([DbEnv::err])m4_table_element([m4_ref(dbenv_err), m4_ref(dbenv_errx)], Error message)
m4_comment([DbEnv::failchk])m4_table_element(m4_ref(dbenv_failchk), Check for thread failure)
m4_comment([DbEnv::fileid_reset])m4_table_element(m4_ref(dbenv_fileid_reset), Reset database file IDs)
m4_comment([DbEnv::get_home])m4_table_element(m4_ref(dbenv_get_home), Return environment's home directory)
m4_comment([DbEnv::get_open_flags])m4_table_element(m4_ref(dbenv_get_open_flags), Return flags with which the environment was opened)
m4_comment([DbEnv::lock_detect])m4_table_element(m4_ref(lock_detect), Perform deadlock detection)
m4_comment([DbEnv::lock_get])m4_table_element(m4_ref(lock_get), Acquire a lock)
m4_comment([DbEnv::lock_id])m4_table_element(m4_ref(lock_id), Acquire a locker ID)
m4_comment([DbEnv::lock_id_free])m4_table_element(m4_ref(lock_id_free), Release a locker ID)
m4_comment([DbEnv::lock_put])m4_table_element(m4_ref(lock_put), Release a lock)
m4_comment([DbEnv::lock_stat])m4_table_element(m4_ref(lock_stat), Return lock subsystem statistics)
m4_comment([DbEnv::lock_vec])m4_table_element(m4_ref(lock_vec), Acquire/release locks)
m4_comment([DbEnv::log_archive])m4_table_element(m4_ref(log_archive), List log and database files)
m4_comment([DbEnv::log_file])m4_table_element(m4_ref(log_file), Map Log Sequence Numbers to log files)
m4_comment([DbEnv::log_flush])m4_table_element(m4_ref(log_flush), Flush log records)
m4_comment([DbEnv::log_printf])m4_table_element(m4_ref(log_printf), Append informational message to the log)
m4_comment([DbEnv::log_put])m4_table_element(m4_ref(log_put), Write a log record)
m4_comment([DbEnv::log_set_config])m4_table_element(m4_ref(dbenv_log_set_config), Configure the logging subsystem)
m4_comment([DbEnv::log_stat])m4_table_element(m4_ref(log_stat), Return log subsystem statistics)
m4_comment([DbEnv::lsn_reset])m4_table_element(m4_ref(dbenv_lsn_reset), Reset database file LSNs)
m4_comment([DbEnv::memp_fcreate])m4_table_element(m4_ref(memp_fcreate), Create a memory pool file handle)
m4_comment([DbEnv::memp_register])m4_table_element(m4_ref(memp_register), Register input/output functions for a file in a memory pool)
m4_comment([DbEnv::memp_stat])m4_table_element(m4_ref(memp_stat), Return memory pool statistics)
m4_comment([DbEnv::memp_sync])m4_table_element(m4_ref(memp_sync), Flush pages from a memory pool)
m4_comment([DbEnv::memp_trickle])m4_table_element(m4_ref(memp_trickle), Trickle flush pages from a memory pool)
m4_comment([DbEnv::mutex_alloc])m4_table_element(m4_ref(mutex_alloc), Allocate a mutex)
m4_comment([DbEnv::mutex_free])m4_table_element(m4_ref(mutex_free), Free a mutex)
m4_comment([DbEnv::mutex_lock])m4_table_element(m4_ref(mutex_lock), Lock a mutex)
m4_comment([DbEnv::mutex_set_align])m4_table_element(m4_ref(mutex_set_align), Configure mutex alignment)
m4_comment([DbEnv::mutex_set_increment])m4_table_element(m4_ref(mutex_set_increment), Configure number of additional mutexes)
m4_comment([DbEnv::mutex_set_max])m4_table_element(m4_ref(mutex_set_max), Configure total number of mutexes)
m4_comment([DbEnv::mutex_set_tas_spins])m4_table_element(m4_ref(mutex_set_tas_spins), Configure test-and-set mutex spin count)
m4_comment([DbEnv::mutex_stat])m4_table_element(m4_ref(mutex_stat), Mutex statistics)
m4_comment([DbEnv::mutex_unlock])m4_table_element(m4_ref(mutex_unlock), Unlock a mutex)
m4_comment([DbEnv::open])m4_table_element(m4_ref(dbenv_open), Open an environment)
m4_comment([DbEnv::remove])m4_table_element(m4_ref(dbenv_remove), Remove an environment)
m4_comment([DbEnv::rep_elect])m4_table_element(m4_ref(rep_elect), Hold a replication election)
m4_comment([DbEnv::rep_process_message])m4_table_element(m4_ref(rep_message), Process a replication message)
m4_comment([DbEnv::rep_set_clockskew])m4_table_element(m4_ref(rep_set_clockskew), Configure master lease clock adjustment)
m4_comment([DbEnv::rep_set_config])m4_table_element(m4_ref(rep_set_config), Configure the replication subsystem)
m4_comment([DbEnv::rep_set_limit])m4_table_element(m4_ref(rep_set_limit), Limit data sent in response to a single message)
m4_comment([DbEnv::rep_set_nsites])m4_table_element(m4_ref(rep_set_nsites), Configure replication group site count)
m4_comment([DbEnv::rep_set_priority])m4_table_element(m4_ref(rep_set_priority), Configure replication site priority)
m4_comment([DbEnv::rep_set_request])m4_table_element(m4_ref(rep_set_request), Configure replication client retransmission requests)
m4_comment([DbEnv::rep_set_timeout])m4_table_element(m4_ref(rep_set_timeout), Configure replication timeouts)
m4_comment([DbEnv::rep_set_transport])m4_table_element(m4_ref(rep_set_transport), Configure replication transport callback)
m4_comment([DbEnv::rep_start])m4_table_element(m4_ref(rep_start), Configure an environment for replication)
m4_comment([DbEnv::rep_stat])m4_table_element(m4_ref(rep_stat), Replication statistics)
m4_comment([DbEnv::rep_sync])m4_table_element(m4_ref(rep_sync), Replication synchronization)
m4_comment([DbEnv::repmgr_add_remote_site])m4_table_element(m4_ref(repmgr_add_remote_site), Specify the replication manager's remote sites)
m4_comment([DbEnv::repmgr_set_ack_policy])m4_table_element(m4_ref(repmgr_set_ack_policy), Specify the replication manager's client acknowledgement policy)
m4_comment([DbEnv::repmgr_set_local_site])m4_table_element(m4_ref(repmgr_set_local_site), Specify the replication manager's local site)
m4_comment([DbEnv::repmgr_site_list])m4_table_element(m4_ref(repmgr_site_list), List the sites and their status)
m4_comment([DbEnv::repmgr_start])m4_table_element(m4_ref(repmgr_start), Start the replication manager)
m4_comment([DbEnv::repmgr_stat])m4_table_element(m4_ref(repmgr_stat), Replication manager statistics)
m4_comment([DbEnv::set_alloc])m4_table_element(m4_ref(dbenv_set_alloc), Set local space allocation functions)
m4_comment([DbEnv::set_app_dispatch])m4_table_element(m4_ref(dbenv_set_app_dispatch), Configure application recovery)
m4_comment([DbEnv::set_cache_max])m4_table_element(m4_ref(dbenv_set_cache_max), Set the maximum cache size)
m4_comment([DbEnv::set_cachesize])m4_table_element(m4_ref(dbenv_set_cachesize), Set the environment cache size)
m4_comment([DbEnv::set_data_dir])m4_table_element(m4_ref(dbenv_set_data_dir), Set the environment data directory)
m4_comment([DbEnv::set_encrypt])m4_table_element(m4_ref(dbenv_set_encrypt), Set the environment cryptographic key)
m4_comment([DbEnv::set_errcall])m4_table_element([m4_ref(dbenv_set_errcall), m4_ref(dbenv_set_msgcall)], Set error and informational message callbacks)
m4_comment([DbEnv::set_errfile])m4_table_element([m4_ref(dbenv_set_errfile), m4_ref(dbenv_set_msgfile)], Set error and informational message FILE)
m4_comment([DbEnv::set_error_stream])ifelse(M4API, C_API,, [m4_table_element([m4_ref(dbenv_set_error_stream), m4_ref(dbenv_set_message_stream)], Set error and informational message output stream)])
m4_comment([DbEnv::set_errpfx])m4_table_element(m4_ref(dbenv_set_errpfx), Set error message prefix)
m4_comment([DbEnv::set_event_notify])m4_table_element(m4_ref(dbenv_set_event_notify), Set event notification callback)
m4_comment([DbEnv::set_feedback])m4_table_element(m4_ref(dbenv_set_feedback), Set feedback callback)
m4_comment([DbEnv::set_flags])m4_table_element(m4_ref(dbenv_set_flags), Environment configuration)
m4_comment([DbEnv::set_intermediate_dir_mode])m4_table_element(m4_ref(dbenv_set_intermediate_dir_mode), Set intermediate directory creation mode)
m4_comment([DbEnv::set_isalive])m4_table_element(m4_ref(dbenv_set_isalive), Set thread is-alive callback)
m4_comment([DbEnv::set_lg_bsize])m4_table_element(m4_ref(dbenv_set_lg_bsize), Set log buffer size)
m4_comment([DbEnv::set_lg_dir])m4_table_element(m4_ref(dbenv_set_lg_dir), Set the environment logging directory)
m4_comment([DbEnv::set_lg_filemode])m4_table_element(m4_ref(dbenv_set_lg_filemode), Set log file mode)
m4_comment([DbEnv::set_lg_max])m4_table_element(m4_ref(dbenv_set_lg_max), Set log file size)
m4_comment([DbEnv::set_lg_regionmax])m4_table_element(m4_ref(dbenv_set_lg_regionmax), Set logging region size)
m4_comment([DbEnv::set_lk_conflicts])m4_table_element(m4_ref(dbenv_set_lk_conflicts), Set lock conflicts matrix)
m4_comment([DbEnv::set_lk_max_detect])m4_table_element(m4_ref(dbenv_set_lk_detect), Set automatic deadlock detection)
m4_comment([DbEnv::set_lk_max_lockers])m4_table_element(m4_ref(dbenv_set_lk_max_lockers), Set maximum number of lockers)
m4_comment([DbEnv::set_lk_max_locks])m4_table_element(m4_ref(dbenv_set_lk_max_locks), Set maximum number of locks)
m4_comment([DbEnv::set_lk_max_objects])m4_table_element(m4_ref(dbenv_set_lk_max_objects), Set maximum number of lock objects)
m4_comment([DbEnv::set_lk_partitions])m4_table_element(m4_ref(dbenv_set_lk_partitions), Set number of lock partitions)
m4_comment([DbEnv::set_mp_max_openfd])m4_table_element(m4_ref(memp_set_max_openfd), Set the maximum number of open file descriptors)
m4_comment([DbEnv::set_mp_max_write])m4_table_element(m4_ref(memp_set_max_write), Set the maximum number of sequential disk writes)
m4_comment([DbEnv::set_mp_mmapsize])m4_table_element(m4_ref(dbenv_set_mp_mmapsize), Set maximum mapped-in database file size)
m4_comment([DbEnv::set_rpc_server])m4_table_element(m4_ref(dbenv_set_rpc_server), Establish an RPC server connection)
m4_comment([DbEnv::set_shm_key])m4_table_element(m4_ref(dbenv_set_shm_key), Set system memory shared segment ID)
m4_comment([DbEnv::set_thread_count])m4_table_element(m4_ref(dbenv_set_thread_count), Set approximate thread count)
m4_comment([DbEnv::set_thread_id])m4_table_element(m4_ref(dbenv_set_thread_id), Set thread of control ID function)
m4_comment([DbEnv::set_thread_id_string])m4_table_element(m4_ref(dbenv_set_thread_id_string), Set thread of control ID format function)
m4_comment([DbEnv::set_timeout])m4_table_element(m4_ref(dbenv_set_timeout), Set lock and transaction timeout)
m4_comment([DbEnv::set_tmp_dir])m4_table_element(m4_ref(dbenv_set_tmp_dir), Set the environment temporary file directory)
m4_comment([DbEnv::set_tx_max])m4_table_element(m4_ref(dbenv_set_tx_max), Set maximum number of transactions)
m4_comment([DbEnv::set_tx_timestamp])m4_table_element(m4_ref(dbenv_set_tx_timestamp), Set recovery timestamp)
m4_comment([DbEnv::set_verbose])m4_table_element(m4_ref(dbenv_set_verbose), Set verbose messages)
m4_comment([DbEnv::stat_print])m4_table_element(m4_ref(dbenv_stat_print), Environment statistics)
m4_comment([DbEnv::txn_begin])m4_table_element(m4_ref(txn_begin), Begin a transaction)
m4_comment([DbEnv::txn_checkpoint])m4_table_element(m4_ref(txn_checkpoint), Checkpoint the transaction subsystem)
m4_comment([DbEnv::txn_recover])m4_table_element(m4_ref(txn_recover), Distributed transaction recovery)
m4_comment([DbEnv::txn_stat])m4_table_element(m4_ref(txn_stat), Return transaction subsystem statistics)
m4_comment([DbLockNotGrantedException])ifelse(M4API, CXX_API, [m4_table_element(m4_ref(DbLockNotGrantedException), Lock-not-granted exception)])
m4_comment([DbLock])ifelse(M4API, CXX_API, [m4_table_element(m4_ref(DbLock), Lock object)])
m4_comment([DbLogc::])ifelse(M4API, CXX_API, [m4_table_element(m4_ref(DbLogc), Log Cursor Object)])
m4_comment([DbLogc::])m4_table_element(m4_ref(log_cursor), Create a log cursor handle)
m4_comment([DbLogc::close])m4_table_element(m4_ref(logc_close), Close a log cursor)
m4_comment([DbLogc::get])m4_table_element(m4_ref(logc_get), Retrieve a log record)
m4_comment([DbLsn])m4_table_element(m4_ref(DbLsn), Log Sequence Numbers)
m4_comment([DbMemoryException])ifelse(M4API, CXX_API, [m4_table_element(m4_ref(DbMemoryException), Insufficient memory exception)])
m4_comment([DbMpoolFile::])ifelse(M4API, CXX_API, [m4_table_element(m4_ref(DbMpoolFile), Memory pool file object)])
m4_comment([DbMpoolFile::close])m4_table_element(m4_ref(memp_fclose), Close a file in a memory pool)
m4_comment([DbMpoolFile::get])m4_table_element(m4_ref(memp_fget), Get page from a file in a memory pool)
m4_comment([DbMpoolFile::open])m4_table_element(m4_ref(memp_fopen), Open a file in a memory pool)
m4_comment([DbMpoolFile::put])m4_table_element(m4_ref(memp_fput), Return a page to a memory pool)
m4_comment([DbMpoolFile::set_clear_len])m4_table_element(m4_ref(memp_set_clear_len), Set file page bytes to be cleared)
m4_comment([DbMpoolFile::set_fileid])m4_table_element(m4_ref(memp_set_fileid), Set file unique identifier)
m4_comment([DbMpoolFile::set_flags])m4_table_element(m4_ref(memp_set_flags), General memory pool file configuration)
m4_comment([DbMpoolFile::set_ftype])m4_table_element(m4_ref(memp_set_ftype), Set file type)
m4_comment([DbMpoolFile::set_lsn_offset])m4_table_element(m4_ref(memp_set_lsn_offset), Set file log-sequence-number offset)
m4_comment([DbMpoolFile::set_maxsize])m4_table_element(m4_ref(memp_set_maxsize), Set maximum file size)
m4_comment([DbMpoolFile::set_pgcookie])m4_table_element(m4_ref(memp_set_pgcookie), Set file cookie for pgin/pgout)
m4_comment([DbMpoolFile::set_priority])m4_table_element(m4_ref(memp_set_priority), Set memory pool file priority)
m4_comment([DbMpoolFile::sync])m4_table_element(m4_ref(memp_fsync), Flush pages from a file in a memory pool)
m4_comment([DbSequence::])m4_table_element(ifelse(M4API, C_API, m4_ref(seq_create), m4_ref(DbSequence)), Create a sequence handle)
m4_comment([DbSequence::close])m4_table_element(m4_ref(seq_close), Close a sequence)
m4_comment([DbSequence::get])m4_table_element(m4_ref(seq_get), Get the next sequence element(s))
m4_comment([DbSequence::get_dbp])m4_table_element(m4_ref(seq_get_dbp), Return a handle for the underlying sequence database)
m4_comment([DbSequence::get_key])m4_table_element(m4_ref(seq_get_key), Return the key for a sequence)
m4_comment([DbSequence::initial_value])m4_table_element(m4_ref(seq_initial_value), Set the initial value of a sequence)
m4_comment([DbSequence::open])m4_table_element(m4_ref(seq_open), Open a sequence)
m4_comment([DbSequence::remove])m4_table_element(m4_ref(seq_remove), Remove a sequence)
m4_comment([DbSequence::set_cachesize])m4_table_element(m4_ref(seq_set_cachesize), Set the cache size of a sequence)
m4_comment([DbSequence::set_flags])m4_table_element(m4_ref(seq_set_flags), Set the flags for a sequence)
m4_comment([DbSequence::set_range])m4_table_element(m4_ref(seq_set_range), Set the range for a sequence)
m4_comment([DbSequence::stat])m4_table_element(m4_ref(seq_stat), Return sequence statistics)
m4_comment([DbTxn::])ifelse(M4API, CXX_API, [m4_table_element(m4_ref(DbTxn), Transaction object)])
m4_comment([DbTxn::abort])m4_table_element(m4_ref(txn_abort), Abort a transaction)
m4_comment([DbTxn::commit])m4_table_element(m4_ref(txn_commit), Commit a transaction)
m4_comment([DbTxn::discard])m4_table_element(m4_ref(txn_discard), Discard a prepared but not resolved transaction handle)
m4_comment([DbTxn::id])m4_table_element(m4_ref(txn_id), Return a transaction's ID)
m4_comment([DbTxn::prepare])m4_table_element(m4_ref(txn_prepare), Prepare a transaction for commit)
m4_comment([DbTxn::set_name])m4_table_element(m4_ref(txn_set_name), Associate a string with a transaction)
m4_comment([DbTxn::set_timeout])m4_table_element(m4_ref(txn_set_timeout), Set transaction timeout)
m4_comment([db_strerror])m4_table_element(m4_ref(dbenv_strerror), Error strings)
m4_comment([db_version])m4_table_element(m4_ref(dbenv_version), Return version information)
m4_comment([log_compare])m4_table_element(m4_ref(log_compare), Compare two Log Sequence Numbers)
m4_table_end
m4_page_footer

123
docs_src/env/env_class.so vendored Normal file
View File

@@ -0,0 +1,123 @@
m4_comment([$Id: env_class.so,v 10.45 2005/11/30 19:09:47 bostic Exp $])
define(M4PAGELOCAL, [DbEnv, dbenv_create, DB_RPCCLIENT, DB_CXX_NO_EXCEPTIONS])
include(m4/m4.seealso)
ifelse(M4API, C_API, [dnl
m4_pf_header(m4_ref(dbenv_create), [dnl
int
db_env_create(DB_ENV **dbenvp, u_int32_t flags);
])])
ifelse(M4API, CXX_API, [dnl
m4_pf_header(m4_ref(DbEnv), [dnl
class DbEnv {
public:
DbEnv(u_int32 flags);
~DbEnv();
m4_blank
DB_ENV *DbEnv::get_DB_ENV();
const DB_ENV *DbEnv::get_const_DB_ENV() const;
static DbEnv *DbEnv::get_DbEnv(DB_ENV *dbenv);
static const DbEnv *DbEnv::get_const_DbEnv(const DB_ENV *dbenv);
...
};])])
define(m4_rpcclient, [dnl
m4_tag(m4_idef(DB_RPCCLIENT),
[Create a client environment to connect to a server.])
m4_p([dnl
The m4_ref(DB_RPCCLIENT) flag indicates to the system that this environment
is remote on a server. The use of this flag causes the environment
methods to use functions that call a server instead of local functions.
Prior to making any environment or database method calls, the application
must call the m4_ref(dbenv_set_rpc_server) function to establish the
connection to the server.])])
m4_p([dnl
The m4_ref(DbEnv) object is the handle for a m4_db environment -- a
collection including support for some or all of caching, locking,
logging and transaction subsystems, as well as databases and log files.
Methods of the m4_ref(DbEnv) handle are used to configure the
environment as well as to operate on subsystems and databases in the
environment.])
m4_p([dnl
m4_ref(DbEnv) handles are free-threaded if the m4_ref(DB_THREAD) flag
is specified to the m4_refT(dbenv_open) when the environment is opened.
The m4_ref(DbEnv) handle should not be closed while any other handle
remains open that is using it as a reference (for example, m4_ref(Db)
or m4_ref(DbTxn)). Once either the m4_ref(dbenv_close) or
m4_refT(dbenv_remove)s are called, the handle may not be accessed again,
regardless of the method's return.])
ifelse(M4API, C_API, [dnl
m4_p([dnl
The m4_ref(dbenv_create) function creates a m4_ref(DbEnv) structure that
is the handle for a m4_db environment. This function allocates memory
for the structure, returning a pointer to the structure in the memory
to which m4_arg(dbenvp) refers. To release the allocated memory and
discard the handle, call the m4_ref(dbenv_close) or m4_refT(dbenv_remove)s.])
m4_p([dnl
The m4_ref(DbEnv) handle contains a special field, "app_private", which
is declared as type "void *". This field is provided for the use of
the application program. It is initialized to NULL and is not further
used by m4_db in any way.])
m4_return(dbenv_create, std)
m4_sf_zmust(0)
m4_tagbegin
m4_rpcclient
m4_tagend
m4_err(dbenv_create)],[dnl
m4_p([dnl
The constructor creates the m4_ref(DbEnv) object. The constructor
allocates memory internally; calling the m4_ref(dbenv_close) or
m4_refT(dbenv_remove)s will free that memory.])
m4_p([dnl
The following m4_arg(flags) value may be specified:])
m4_tagbegin
ifelse(M4API, CXX_API, [dnl
m4_tag(m4_idef(DB_CXX_NO_EXCEPTIONS), [dnl
The m4_db C++ API supports two different error behaviors. By default,
whenever an error occurs, an exception is thrown that encapsulates the
error information. This generally allows for cleaner logic for
transaction processing because a try block can surround a single
transaction. However, if m4_ref(DB_CXX_NO_EXCEPTIONS) is specified,
exceptions are not thrown; instead, each individual function returns an
error code.])])
m4_rpcclient
m4_tagend
ifelse(M4API, CXX_API, [dnl
m4_p([dnl
Each m4_ref(DbEnv) object has an associated m4_refc(DbEnv) structure,
which is used by the underlying implementation of m4_db and its
C-language API. The DbEnv::get_DB_ENV method returns a pointer to this
struct. Given a const m4_ref(DbEnv) object, DbEnv::get_const_DB_ENV
returns a const pointer to the same struct.])
m4_p([dnl
Given a m4_refc(DbEnv) struct, the DbEnv::get_DbEnv method returns the
corresponding m4_ref(DbEnv) object, if there is one. If the
m4_refc(DbEnv) object was not associated with a m4_ref(DbEnv) (that is,
it was not returned from a call to DbEnv::get_DB_ENV), then the result
of DbEnv::get_DbEnv is undefined. Given a const m4_refc(DbEnv) struct,
DbEnv::get_const_Db_Env returns the associated const m4_ref(DbEnv)
object, if there is one.])
m4_p([dnl
These methods may be useful for m4_db applications including both C
and C++ language software. It should not be necessary to use these
calls in a purely C++ application.])])])
m4_seealso(DbEnv)
m4_page_footer

72
docs_src/env/env_close.so vendored Normal file
View File

@@ -0,0 +1,72 @@
m4_comment([$Id: env_close.so,v 10.38 2004/08/13 03:38:56 bostic Exp $])
define(M4PAGELOCAL, dbenv_close)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_close),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__close(DB_ENV *dbenv, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
DbEnv::close(u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbenv_close) closes the m4_db environment, freeing any
allocated resources and closing any underlying subsystems.])
m4_p([dnl
The m4_ref(DbEnv) handle should not be closed while any other handle
that refers to it is not yet closed; for example, database environment
handles must not be closed while database handles remain open, or
transactions in the environment have not yet been committed or aborted.
Specifically, this includes m4_ref(Db), m4_ref(Dbc), m4_ref(DbTxn),
m4_ref(DbLogc) and m4_ref(DbMpoolFile) handles.])
m4_p([dnl
Where the environment was initialized with the m4_ref(DB_INIT_LOCK)
flag, calling m4_ref(dbenv_close) does not release any locks still held
by the closing process, providing functionality for long-lived locks.
Processes that want to have all their locks released can do so by
issuing the appropriate m4_ref(lock_vec) call.])
m4_p([dnl
Where the environment was initialized with the m4_ref(DB_INIT_MPOOL)
flag, calling m4_ref(dbenv_close) implies calls to m4_ref(memp_fclose) for
any remaining open files in the memory pool that were returned to this
process by calls to m4_ref(memp_fopen). It does not imply a call to
m4_ref(memp_fsync) for those files.])
m4_p([dnl
Where the environment was initialized with the m4_ref(DB_INIT_TXN) flag,
calling m4_ref(dbenv_close) aborts any unresolved transactions.
Applications should not depend on this behavior for transactions
involving m4_db databases; all such transactions should be explicitly
resolved. The problem with depending on this semantic is that aborting
an unresolved transaction involving database operations requires a
database handle. Because the database handles should have been closed before
calling m4_ref(dbenv_close), it will not be possible to abort the
transaction, and recovery will have to be run on the m4_db environment
before further operations are done.])
m4_p([dnl
Where log cursors were created using the m4_refT(log_cursor), calling
m4_ref(dbenv_close) does not imply closing those cursors.])
m4_p([dnl
In multithreaded applications, only a single thread may call
m4_ref(dbenv_close).])
m4_p([dnl
After m4_ref(dbenv_close) has been called, regardless of its return, the
m4_db environment handle may not be accessed again.])
m4_return(dbenv_close, std)
m4_parambegin
m4_unusedflags
m4_paramend
m4_seealso(DbEnv)
m4_page_footer

90
docs_src/env/env_dbremove.so vendored Normal file
View File

@@ -0,0 +1,90 @@
m4_comment([$Id: env_dbremove.so,v 10.49 2004/12/16 19:13:01 bostic Exp $])
ifdef([M4INTERFACE],, [define(M4INTERFACE, dbenv_dbremove)])
define(M4PAGELOCAL, M4INTERFACE)
include(m4/m4.seealso)
ifelse(M4INTERFACE, dbenv_dbremove, [dnl
m4_pf_header(m4_ref(dbenv_dbremove),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__dbremove(DB_ENV *dbenv, DB_TXN *txnid,
const char *file, const char *database, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::dbremove(DbTxn *txnid,
const char *file, const char *database, u_int32_t flags);
]))],[dnl
m4_pf_header(m4_ref(dbh_remove),
ifelse(M4API, C_API, [dnl
int
DB-__GT__remove(DB *db,
const char *file, const char *database, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::remove(const char *file, const char *database, u_int32_t flags);
]))])
m4_p([dnl
The m4_refT(M4INTERFACE) removes the database specified by the
m4_arg(file) and m4_arg(database) parameters. If no m4_arg(database)
is specified, the underlying file represented by m4_arg(file) is
removed, incidentally removing all of the databases it contained.])
m4_p([dnl
Applications should never remove databases with open m4_ref(Db) handles,
or in the case of removing a file, when any database in the file has an
open handle. For example, some architectures do not permit the removal
of files with open system handles. On these architectures, attempts to
remove databases currently in use by any thread of control in the system
may fail.])
ifelse(M4INTERFACE, dbh_remove, [dnl
m4_p([dnl
The m4_refT(dbh_remove) should not be called if the remove is intended
to be transactionally safe; the m4_refT(dbenv_dbremove) should be used
instead.])
m4_p([dnl
The m4_refT(dbh_remove) may not be called after calling the
m4_refT(dbh_open) on any m4_ref(Db) handle. If the m4_refT(dbh_open)
has already been called on a m4_ref(Db) handle, close the existing
handle and create a new one before calling m4_ref(dbh_remove).])
m4_destructor(Db, dbh_remove)])
m4_return(M4INTERFACE, std)
m4_parambegin
m4_param(database, [dnl
The m4_arg(database) parameter is the database to be removed.])
m4_param_utf8(file, [dnl
The m4_arg(file) parameter is the physical file which contains the
database(s) to be removed.])
ifelse(M4INTERFACE, dbenv_dbremove, [dnl
m4_param(flags, [dnl
m4_sf_zmust(0)
m4_tagbegin
m4_autocommit_flag(dbenv_dbremove)
m4_tagend])
m4_param_txn(dbenv_dbremove, auto)
],[dnl
m4_unusedflags])
m4_paramend
m4_header([Environment Variables])
m4_data_location(M4INTERFACE, ifelse(M4INTERFACE, dbenv_dbremove, 0, 1))
m4_err(M4INTERFACE,
ifelse(M4INTERFACE, dbenv_dbremove, deadlock, empty),
einval, [ifelse(M4INTERFACE, dbenv_dbremove,
[m4_ref(dbenv_dbremove) called before m4_ref(dbenv_open) was called],
[m4_ref(dbh_remove) called after m4_ref(dbh_open) was called])],
filenotfound)
ifelse(M4INTERFACE, dbenv_dbremove, [m4_seealso(DbEnv)], [m4_seealso(Db)])
m4_page_footer

98
docs_src/env/env_dbrename.so vendored Normal file
View File

@@ -0,0 +1,98 @@
m4_comment([$Id: env_dbrename.so,v 10.37 2004/12/16 19:13:01 bostic Exp $])
ifdef([M4INTERFACE],, [define(M4INTERFACE, dbenv_dbrename)])
define(M4PAGELOCAL, M4INTERFACE)
include(m4/m4.seealso)
ifelse(M4INTERFACE, dbenv_dbrename, [dnl
m4_pf_header(m4_ref(dbenv_dbrename),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__dbrename(DB_ENV *dbenv, DB_TXN *txnid, const char *file,
const char *database, const char *newname, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::dbrename(DbTxn *txnid, const char *file,
const char *database, const char *newname, u_int32_t flags);
]))],[dnl
m4_pf_header(m4_ref(dbh_rename),
ifelse(M4API, C_API, [dnl
int
DB-__GT__rename(DB *db, const char *file,
const char *database, const char *newname, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
Db::rename(const char *file,
const char *database, const char *newname, u_int32_t flags);
]))])
m4_p([dnl
The m4_refT(M4INTERFACE) renames the database specified by the
m4_arg(file) and m4_arg(database) parameters to m4_arg(newname). If no
m4_arg(database) is specified, the underlying file represented by
m4_arg(file) is renamed, incidentally renaming all of the databases it
contained.])
m4_p([dnl
Applications should not rename databases that are currently in use. If
an underlying file is being renamed and logging is currently enabled in
the database environment, no database in the file may be open when the
m4_refT(M4INTERFACE) is called. In particular, some architectures do
not permit renaming files with open handles. On these architectures,
attempts to rename databases that are currently in use by any thread of
control in the system may fail.])
ifelse(M4INTERFACE, dbh_rename, [dnl
m4_p([dnl
The m4_refT(dbh_rename) should not be called if the rename is intended
to be transactionally safe; the m4_refT(dbenv_dbrename) should be used
instead.])
m4_p([dnl
The m4_refT(dbh_rename) may not be called after calling the
m4_refT(dbh_open) on any m4_ref(Db) handle. If the m4_refT(dbh_open)
has already been called on a m4_ref(Db) handle, close the existing
handle and create a new one before calling m4_ref(dbh_rename).])
m4_destructor(Db, dbh_rename)])
m4_return(M4INTERFACE, std)
m4_parambegin
m4_param(database, [dnl
The m4_arg(database) parameter is the database to be renamed.])
m4_param_utf8(file, [dnl
The m4_arg(file) parameter is the physical file which contains the
database(s) to be renamed.])
ifelse(M4INTERFACE, dbenv_dbrename, [dnl
m4_param(flags, [dnl
m4_sf_zmust(0)
m4_tagbegin
m4_autocommit_flag(dbenv_dbrename)
m4_tagend])
],[dnl
m4_unusedflags
])
m4_param(newname, [dnl
The m4_arg(newname) parameter is the new name of the database or file.])
ifelse(M4INTERFACE, dbenv_dbrename, [m4_param_txn(dbenv_dbrename, auto)])
m4_paramend
m4_header([Environment Variables])
m4_data_location(M4INTERFACE, ifelse(M4INTERFACE, dbenv_dbrename, 0, 1))
m4_err(M4INTERFACE,
ifelse(M4INTERFACE, dbenv_dbrename, deadlock, empty), einval,
[ifelse(M4INTERFACE, dbenv_dbrename,
[m4_ref(dbenv_dbrename) called before m4_ref(dbenv_open) was called],
[m4_ref(dbh_rename) called after m4_ref(dbh_open) was called])],
filenotfound)
ifelse(M4INTERFACE, dbenv_dbrename, [m4_seealso(DbEnv)], [m4_seealso(Db)])
m4_page_footer

106
docs_src/env/env_err.so vendored Normal file
View File

@@ -0,0 +1,106 @@
m4_comment([$Id: env_err.so,v 10.34 2006/04/27 20:17:47 bostic Exp $])
ifdef([M4INTERFACE],, [define(M4INTERFACE, dbenv_err)])
include(m4/m4.seealso)
ifelse(M4INTERFACE, dbenv_err, [dnl
define(M4PAGELOCAL, [dbenv_err, dbenv_errx])
m4_pf_header(m4_ref(dbenv_err),
ifelse(M4API, C_API, [dnl
void
DB_ENV-__GT__err(DB_ENV *dbenv, int error, const char *fmt, ...);
m4_blank
void
DB_ENV-__GT__errx(DB_ENV *dbenv, const char *fmt, ...);
])dnl
ifelse(M4API, CXX_API, [dnl
DbEnv::err(int error, const char *fmt, ...);
m4_blank
DbEnv::errx(const char *fmt, ...);
]))],[dnl
define(M4PAGELOCAL, [dbh_err, dbh_errx])
m4_pf_header(m4_ref(dbh_err),
ifelse(M4API, C_API, [dnl
void
DB-__GT__err(DB *db, int error, const char *fmt, ...);
m4_blank
void
DB-__GT__errx(DB *db, const char *fmt, ...);
])dnl
ifelse(M4API, CXX_API, [dnl
Db::err(int error, const char *fmt, ...);
m4_blank
Db::errx(const char *fmt, ...);
]))])
m4_p([dnl
The m4_ref(dbenv_err), m4_ref(dbenv_errx), m4_ref(dbh_err) and
m4_refT(dbh_errx)s provide error-messaging functionality for
applications written using the m4_db library.])
m4_p([dnl
The m4_ref(dbh_err) and m4_refT(dbenv_err)s constructs an error message
consisting of the following elements:])
m4_indentv([dnl
m4_tagbegin
m4_tag([An optional prefix string], [dnl
If no error callback function has been set using the
m4_refT(dbenv_set_errcall), any prefix string specified using the
m4_refT(dbenv_set_errpfx), followed by two separating characters: a colon
and a m4_htmlquote(space) character.])
m4_tag([An optional printf-style message], [dnl
The supplied message m4_arg(fmt), if non-NULL, in which the
m4_ansic_name printf function specifies how subsequent parameters
are converted for output.])
m4_tag([A separator], [dnl
Two separating characters: a colon and a m4_htmlquote(space) character.])
m4_tag([A standard error string], [dnl
The standard system or m4_db library error string associated with the
m4_arg(error) value, as returned by the m4_refT(dbenv_strerror).])
m4_tagend
])
m4_p([dnl
The m4_ref(dbh_errx) and m4_refT(dbenv_errx)s are the same as the
m4_ref(dbh_err) and m4_refT(dbenv_err)s, except they do not append the
final separator characters and standard error string to the error
message.])
m4_p([dnl
This constructed error message is then handled as follows:])
m4_indentv([dnl
m4_p([dnl
If an error callback function has been set (see m4_ref(dbh_set_errcall)
and m4_ref(dbenv_set_errcall)), that function is called with two
parameters: any prefix string specified (see m4_ref(dbh_set_errpfx) and
m4_ref(dbenv_set_errpfx)) and the error message.])
m4_p([dnl
If a C library FILE * has been set (see m4_ref(dbh_set_errfile) and
m4_ref(dbenv_set_errfile)), the error message is written to that output
stream.])
ifelse(M4API, C_API,, [dnl
m4_p([dnl
If ifelse(M4API, CXX_API, [a C++ ostream], [an OutputStream]) has been set
(see m4_ref(dbenv_set_error_stream) and m4_ref(dbh_set_error_stream)),
the error message is written to that stream.])])
m4_p([dnl
If none of these output options has been configured, the error message
is written to stderr, the standard error output stream.])])
m4_parambegin
m4_param(error, [dnl
The m4_arg(error) parameter is the error value for which the
m4_ref(dbenv_err) and m4_refT(dbh_err)s will display a explanatory
string.])
m4_param(fmt, [dnl
The m4_arg(fmt) parameter is an optional printf-style message to display.])
m4_paramend
ifelse(M4INTERFACE, dbenv_err, [m4_seealso(DbEnv)], [m4_seealso(Db)])
m4_page_footer

113
docs_src/env/env_event_notify.so vendored Normal file
View File

@@ -0,0 +1,113 @@
m4_comment([$Id: env_event_notify.so,v 10.13 2007/04/05 20:37:29 bostic Exp $])
define(M4PAGELOCAL, [dnl
dbenv_set_event_notify, DB_EVENT_PANIC, DB_EVENT_REP_CLIENT,
DB_EVENT_REP_ELECTED, DB_EVENT_REP_MASTER, DB_EVENT_REP_NEWMASTER,
DB_EVENT_REP_PERM_FAILED, DB_EVENT_REP_STARTUPDONE])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_set_event_notify),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__set_event_notify(DB_ENV *dbenv,
void (*db_event_fcn)(DB_ENV *dbenv, u_int32_t event, void *event_info));
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::set_event_notify(
void (*db_event_fcn)(DB_ENV *dbenv, u_int32_t event, void *event_info));
]))
m4_p([dnl
The m4_refT(dbenv_set_event_notify) configures a callback function which
is called to notify the process of specific m4_db events.])
m4_scope_dbenv(dbenv_set_event_notify)
m4_when_any(dbenv_set_event_notify)
m4_return(dbenv_set_event_notify, std)
m4_parambegin
m4_param(db_event_fcn, [dnl
The m4_arg(db_event_fcn) parameter is the application's event
notification function. The function takes three parameters:
m4_tagbegin
m4_tag(dbenv, [dnl
The m4_arg(dbenv) parameter is the enclosing database environment handle.])
m4_tag(event, [dnl
The m4_arg(event) parameter is one of the following values:])
m4_tagbegin
m4_tag(m4_idef(DB_EVENT_PANIC), [dnl
Errors can occur in the m4_db library where the only solution is to shut
down the application and run recovery (for example, if m4_db is unable
to allocate heap memory). In such cases, the m4_db methods will
ifelse(M4EXCEPT, return_only, [return m4_ref(DB_RUNRECOVERY).])
ifelse(M4EXCEPT, except_return, [dnl
either return m4_ref(DB_RUNRECOVERY) or throw a m4_ref(DbRunRecoveryException),
depending on the API configuration.])
ifelse(M4EXCEPT, except_only, [throw a m4_ref(DbRunRecoveryException).])
It is often easier to simply exit the application when such errors occur
rather than gracefully return up the stack.
m4_p([dnl
When m4_arg(event) is set to m4_ref(DB_EVENT_PANIC), the database
environment has failed. All threads of control in the database
environment should exit the environment, and recovery should be run.])])
m4_tag(m4_idef(DB_EVENT_REP_CLIENT), [dnl
The local site is now a replication client.])
m4_tag(m4_idef(DB_EVENT_REP_ELECTED), [dnl
The local replication site has just won an election. An application using
the Base replication API should arrange for a call to the m4_refT(rep_start)
after receiving this event, to reconfigure the local environment as a
replication master.])
m4_p([dnl
Replication Manager applications may safely ignore this event. The
Replication Manager calls m4_ref(rep_start) automatically on behalf of
the application when appropriate (resulting in firing of the
m4_ref(DB_EVENT_REP_MASTER) event).])
m4_tag(m4_idef(DB_EVENT_REP_MASTER), [dnl
The local site is now the master site of its replication group. It is
the application's responsibility to begin acting as the master environment.])
m4_tag(m4_idef(DB_EVENT_REP_NEWMASTER), [dnl
The replication group of which this site is a member has just established a
new master; the local site is not the new master. The
m4_arg(event_info) parameter points to an integer containing the
environment ID of the new master.])
m4_tag(m4_idef(DB_EVENT_REP_PERM_FAILED), [dnl
The replication manager did not receive enough acknowledgements (based on
the acknowledgement policy configured with m4_ref(repmgr_set_ack_policy))
to ensure a transaction's durability within the replication group. The
transaction will be flushed to the master's local disk storage for
durability.])
m4_p([dnl
The m4_ref(DB_EVENT_REP_PERM_FAILED) event is provided only to applications
configured for the replication manager.])
m4_tag(m4_idef(DB_EVENT_REP_STARTUPDONE), [dnl
The client has completed startup synchronization and is now processing
live log records received from the master.])
m4_tag(m4_idef(DB_EVENT_WRITE_FAILED), [dnl
A m4_db write to stable storage failed.])
m4_tagend
m4_tag(event_info, [dnl
The m4_arg(event_info) parameter may reference memory which contains
additional information describing an event. By default,
m4_arg(event_info) is NULL; specific events may pass non-NULL values,
in which case the event will also describe the memory's structure.])
m4_tagend])
m4_paramend
m4_not_reentrant
m4_seealso(DbEnv)
m4_page_footer

72
docs_src/env/env_failchk.so vendored Normal file
View File

@@ -0,0 +1,72 @@
m4_comment([$Id: env_failchk.so,v 10.7 2007/09/21 20:06:01 bostic Exp $])
define(M4PAGELOCAL, [dbenv_failchk])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_failchk),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__failchk(DB_ENV *dbenv, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::failchk(u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbenv_failchk) checks for threads of control (either a true
thread or a process) that have exited while manipulating m4_db library
data structures, while holding a logical database lock, or with an
unresolved transaction (that is, a transaction that was never aborted
or committed). For more information, see m4_link(M4RELDIR/ref/cam/app,
Architecting Data Store and Concurrent Data Store applications), and
m4_link(M4RELDIR/ref/transapp/app, Architecting Transactional Data Store
applications).])
m4_p([dnl
The m4_refT(dbenv_failchk) is based on the "thread_id" and "is_alive"
functions specified to the m4_refT(dbenv_set_thread_id). Applications
calling the m4_refT(dbenv_failchk) must have already called the
m4_refT(dbenv_set_isalive), on the same m4_ref(DbEnv), and must have
configured their database environment using the
m4_refT(dbenv_set_thread_count).])
m4_p([dnl
If m4_ref(dbenv_failchk) determines a thread of control exited while
holding database read locks, it will release those locks. If
m4_ref(dbenv_failchk) determines a thread of control exited with an
unresolved transaction, the transaction will be aborted. In either of
these cases, m4_ref(dbenv_failchk) will return 0 and the application may
continue to use the database environment.])
m4_p([dnl
In either of these cases, the m4_refT(dbenv_failchk) will also report
the process and thread IDs associated with any released locks or
aborted transactions. The information is printed to a specified output
channel (see the m4_refT(dbenv_set_msgfile) for more information), or
passed to an application callback function (see the
m4_refT(dbenv_set_msgcall) for more information).])
m4_p([dnl
If m4_ref(dbenv_failchk) determines a thread of control has exited such
that database environment recovery is required, it will return
m4_ref(DB_RUNRECOVERY). In this case, the application should not
continue to use the database environment. For a further description as
to the actions the application should take when this failure occurs, see
m4_link(M4RELDIR/ref/cam/fail, Handling failure in Data Store and
Concurrent Data Store applications), and
m4_link(M4RELDIR/ref/transapp/fail, Handling failure in Transactional
Data Store applications).])
m4_when(dbenv_failchk, before, dbenv_open)
m4_return(dbenv_failchk, std)
m4_parambegin
m4_unusedflags
m4_paramend
m4_err(dbenv_failchk, einval)
m4_seealso(DbEnv)
m4_page_footer

49
docs_src/env/env_fileid_reset.so vendored Normal file
View File

@@ -0,0 +1,49 @@
m4_comment([$Id: env_fileid_reset.so,v 1.3 2005/12/13 16:48:01 bostic Exp $])
define(M4PAGELOCAL, [dbenv_fileid_reset])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_fileid_reset),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__fileid_reset(DB_ENV *dbenv, const char *file, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::fileid_reset(const char *file, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbenv_fileid_reset) allows database files to be copied, and
then the copy used in the same database environment as the original.])
m4_p([dnl
All databases contain an ID string used to identify the database in the
database environment cache. If a physical database file is copied, and
used in the same environment as another file with the same ID strings,
corruption can occur. The m4_refT(dbenv_fileid_reset) creates new ID
strings for all of the databases in the physical file.])
m4_p([dnl
The m4_refT(dbenv_fileid_reset) modifies the physical file, in-place.
Applications should not reset IDs in files that are currently in use.])
m4_when_any(dbenv_fileid_reset)
m4_return(dbenv_fileid_reset, std)
m4_parambegin
m4_param(file, [dnl
The name of the physical file in which new file IDs are to be created.])
m4_param(flags, [dnl
m4_sf_zmust(0)
m4_tagbegin
m4_tag(DB_ENCRYPT, [dnl
The file contains encrypted databases.])
m4_tagend])
m4_paramend
m4_err(dbenv_fileid_reset, einval)
m4_seealso(DbEnv)
m4_page_footer

7
docs_src/env/env_list.so vendored Normal file
View File

@@ -0,0 +1,7 @@
m4_comment([$Id: env_list.so,v 10.1 2002/08/30 20:00:50 bostic Exp $])
m4_page_title([m4_db: Database Environments and Related Methods])
include(env/m4.methods)
m4_page_footer

57
docs_src/env/env_lsn_reset.so vendored Normal file
View File

@@ -0,0 +1,57 @@
m4_comment([$Id: env_lsn_reset.so,v 1.4 2005/12/13 16:48:01 bostic Exp $])
define(M4PAGELOCAL, [dbenv_lsn_reset])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_lsn_reset),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__lsn_reset(DB_ENV *dbenv, const char *file, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::lsn_reset(const char *file, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbenv_lsn_reset) allows database files to be moved from one
transactional database environment to another.])
m4_p([dnl
Database pages in transactional database environments contain references
to the environment's log files (that is, log sequence numbers, or LSNs).
Copying or moving a database file from one database environment to
another, and then modifying it, can result in data corruption if the
LSNs are not first cleared.])
m4_p([dnl
Note that LSNs should be reset before moving or copying the database
file into a new database environment, rather than moving or copying the
database file and then resetting the LSNs. m4_db has consistency checks
that may be triggered if an application calls m4_ref(dbenv_lsn_reset)
on a database in a new environment when the database LSNs still reflect
the old environment.])
m4_p([dnl
The m4_refT(dbenv_lsn_reset) modifies the physical file, in-place.
Applications should not reset LSNs in files that are currently in use.])
m4_when_any(dbenv_lsn_reset)
m4_return(dbenv_lsn_reset, std)
m4_parambegin
m4_param(file, [dnl
The name of the physical file in which the LSNs are to be cleared.])
m4_param(flags, [dnl
m4_sf_zmust(0)
m4_tagbegin
m4_tag(DB_ENCRYPT, [dnl
The file contains encrypted databases.])
m4_tagend])
m4_paramend
m4_err(dbenv_lsn_reset, einval)
m4_seealso(DbEnv)
m4_page_footer

274
docs_src/env/env_open.so vendored Normal file
View File

@@ -0,0 +1,274 @@
m4_comment([$Id: env_open.so,v 10.114 2008/04/29 22:42:03 mbrey Exp $])
define(M4PAGELOCAL,
[dbenv_open, dbenv_get_home, dbenv_get_open_flags, DB_CREATE,
DB_INIT_CDB, DB_INIT_LOCK, DB_INIT_LOG, DB_INIT_MPOOL,
DB_INIT_REP, DB_INIT_TXN, DB_LOCKDOWN, DB_PRIVATE, DB_RECOVER,
DB_RECOVER_FATAL, DB_REGISTER, DB_SYSTEM_MEM, DB_THREAD,
DB_VERSION_MISMATCH])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_open),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__open(DB_ENV *dbenv, char *db_home, u_int32_t flags, int mode);
m4_blank
int
DB_ENV-__GT__get_home(DB_ENV *dbenv, const char **homep);
m4_blank
int
DB_ENV-__GT__get_open_flags(DB_ENV *dbenv, u_int32_t *flagsp);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::open(const char *db_home, u_int32_t flags, int mode);
m4_blank
int
DbEnv::get_home(const char **homep);
m4_blank
int
DbEnv::get_open_flags(u_int32_t *flagsp);
]))
m4_p([dnl
The m4_refT(dbenv_open) opens a m4_db environment. It provides a
structure for creating a consistent environment for processes using one
or more of the features of m4_db.])
m4_return(dbenv_open, std,
[If m4_ref(dbenv_open) fails, the m4_refT(dbenv_close) must be called
to discard the m4_ref(DbEnv) handle.])
m4_parambegin
m4_param_utf8(db_home, [dnl
The m4_arg(db_home) parameter is the database environment's home
directory. For more information on m4_arg(db_home), and filename
resolution in general, see m4_link(M4RELDIR/ref/env/naming, [m4_db File
Naming]). The environment variable m4_envvar(DB_HOME) may be used as
the path of the database home, as described in
m4_link(M4RELDIR/ref/env/naming, [m4_db File Naming]).])
m4_param(flags, [dnl
The m4_arg(flags) parameter specifies the subsystems that are initialized
and how the application's environment affects m4_db file naming, among
other things.
m4_sf_or_may
m4_p([dnl
Because there are a large number of flags that can be specified, they
have been grouped together by functionality. The first group of flags
indicates which of the m4_db subsystems should be initialized.])
m4_p([dnl
The choice of subsystems initialized for a m4_db database environment
is specified by the thread of control initially creating the
environment. Any subsequent thread of control joining the environment
will automatically be configured to use the same subsystems as were
created in the environment (unless the thread of control requests a
subsystem not available in the environment, which will fail).
Applications joining an environment, able to adapt to whatever
subsystems have been configured in the environment, should open the
environment without specifying any subsystem flags. Applications
joining an environment, requiring specific subsystems from their
environments, should open the environment specifying those specific
subsystem flags.])
m4_tagbegin
m4_tag(m4_idef(DB_INIT_CDB), [dnl
Initialize locking for the m4_link(M4RELDIR/ref/cam/intro, m4_cam)
product. In this mode, m4_db provides multiple reader/single writer
access. The only other subsystem that should be specified with the
m4_ref(DB_INIT_CDB) flag is m4_ref(DB_INIT_MPOOL).])
m4_tag(m4_idef(DB_INIT_LOCK), [dnl
Initialize the locking subsystem. This subsystem should be used when
multiple processes or threads are going to be reading and writing a
m4_db database, so that they do not interfere with each other. If all
threads are accessing the database(s) read-only, locking is unnecessary.
When the m4_ref(DB_INIT_LOCK) flag is specified, it is usually necessary
to run a deadlock detector, as well. See m4_ref(db_deadlock) and
m4_ref(lock_detect) for more information.])
m4_tag(m4_idef(DB_INIT_LOG), [dnl
Initialize the logging subsystem. This subsystem should be used when
recovery from application or system failure is necessary. If the log
region is being created and log files are already present, the log files
are reviewed; subsequent log writes are appended to the end of the log,
rather than overwriting current log entries.])
m4_tag(m4_idef(DB_INIT_MPOOL), [dnl
Initialize the shared memory buffer pool subsystem. This subsystem
should be used whenever an application is using any m4_db access
method.])
m4_tag(m4_idef(DB_INIT_REP), [dnl
Initialize the replication subsystem. This subsystem
should be used whenever an application plans on using replication.
The m4_ref(DB_INIT_REP) flag requires the m4_ref(DB_INIT_TXN) and
m4_ref(DB_INIT_LOCK) flags also be configured.])
m4_tag(m4_idef(DB_INIT_TXN), [dnl
Initialize the transaction subsystem. This subsystem should be used
when recovery and atomicity of multiple operations are important. The
m4_ref(DB_INIT_TXN) flag implies the m4_ref(DB_INIT_LOG) flag.])
m4_tagend
m4_p([dnl
The second group of flags govern what recovery, if any, is performed when
the environment is initialized:])
m4_tagbegin
m4_tag(m4_idef(DB_RECOVER), [dnl
Run normal recovery on this environment before opening it for normal
use. If this flag is set, the m4_ref(DB_CREATE) and m4_ref(DB_INIT_TXN)
flags must also be set, because the regions will be removed and
re-created, and transactions are required for application recovery.])
m4_tag(m4_idef(DB_RECOVER_FATAL), [dnl
Run catastrophic recovery on this environment before opening it for
normal use. If this flag is set, the m4_ref(DB_CREATE) and
m4_ref(DB_INIT_TXN) flags must also be set, because the regions will be
removed and re-created, and transactions are required for application
recovery.])
m4_tagend
m4_p([dnl
A standard part of the recovery process is to remove the existing m4_db
environment and create a new one in which to perform recovery. If the
thread of control performing recovery does not specify the correct
region initialization information (for example, the correct memory pool
cache size), the result can be an application running in an environment
with incorrect cache and other subsystem sizes. For this reason, the
thread of control performing recovery should specify correct
configuration information before calling the m4_refT(dbenv_open); or it
should remove the environment after recovery is completed, leaving
creation of the correctly sized environment to a subsequent call to
m4_ref(dbenv_open).])
m4_p([dnl
All m4_db recovery processing must be single-threaded; that is, only a
single thread of control may perform recovery or access a m4_db
environment while recovery is being performed. Because it is not an
error to specify m4_ref(DB_RECOVER) for an environment for which no
recovery is required, it is reasonable programming practice for the
thread of control responsible for performing recovery and creating the
environment to always specify the m4_ref(DB_CREATE) and
m4_ref(DB_RECOVER) flags during startup.])
m4_p([dnl
The m4_ref(dbenv_open) function returns successfully if m4_ref(DB_RECOVER)
or m4_ref(DB_RECOVER_FATAL) is specified and no log files exist, so it
is necessary to ensure that all necessary log files are present before
running recovery. For further information, consult m4_ref(db_archive)
and m4_ref(db_recover).])
m4_p([dnl
The third group of flags govern file-naming extensions in the environment:])
m4_tagbegin
m4_env_flags
m4_tagend
m4_p([Finally, there are a few additional unrelated flags:])
m4_tagbegin
m4_tag(m4_idef(DB_CREATE), [dnl
Cause m4_db subsystems to create any underlying files, as necessary.])
m4_tag(m4_idef(DB_LOCKDOWN), [dnl
Lock shared m4_db environment files and memory-mapped databases into
memory.])
m4_tag(m4_idef(DB_PRIVATE), [dnl
Allocate region memory from the heap instead of from memory backed by
the filesystem or system shared memory.
m4_p([dnl
This flag implies the environment will only be accessed by a single
process (although that process may be multithreaded). This flag has two
effects on the m4_db environment. First, all underlying data structures
are allocated from per-process memory instead of from shared memory that
is accessible to more than a single process. Second, mutexes are only
configured to work between threads.])
m4_p([dnl
This flag should not be specified if more than a single process is
accessing the environment because it is likely to cause database
corruption and unpredictable behavior. For example, if both a server
application and m4_db utilities (for example, m4_ref(db_archive),
m4_ref(db_checkpoint) or m4_ref(db_stat)) are expected to access the
environment, the m4_ref(DB_PRIVATE) flag should not be specified.])
m4_p([dnl
See m4_link(M4RELDIR/ref/env/region, [Shared Memory Regions]) for more
information.])])
m4_tag(m4_idef(DB_REGISTER), [dnl
Check to see if recovery needs to be performed before opening the
database environment. (For this check to be accurate, all processes
using the environment must specify m4_ref(DB_REGISTER) when opening the
environment.) If recovery needs to be performed for any reason
(including the initial use of the m4_ref(DB_REGISTER) flag), and
m4_ref(DB_RECOVER) is also specified, recovery will be performed and the
open will proceed normally. If recovery needs to be performed and
m4_ref(DB_RECOVER) is not specified, m4_ref(DB_RUNRECOVERY) will be
returned. If recovery does not need to be performed, the
m4_ref(DB_RECOVER) flag will be ignored. See
m4_link(M4RELDIR/ref/transapp/app, Architecting Transactional Data Store
applications) for more information.])
m4_tag(m4_idef(DB_SYSTEM_MEM), [dnl
Allocate region memory from system shared memory instead of from heap
memory or memory backed by the filesystem.
m4_p([dnl
See m4_link(M4RELDIR/ref/env/region, [Shared Memory Regions]) for more
information.])])
m4_tag(m4_idef(DB_THREAD), [dnl
Cause the m4_ref(DbEnv) handle returned by m4_ref(dbenv_open) to be
m4_italic(free-threaded); that is, concurrently usable by multiple
threads in the address space. The DB_THREAD flag should be specified
if the m4_ref(DbEnv) handle will be concurrently used by more than one
thread in the process, or if any m4_ref(Db) handles opened in the scope
of the m4_ref(DbEnv) handle will be concurrently used by more than one
thread in the process.
m4_p([dnl
This flag is required when using the Replication Manager.])])
m4_tagend])
m4_param_filemode([m4_db])
m4_paramend
m4_idefz(DB_VERSION_MISMATCH)
m4_err(dbenv_open,
DB_RUNRECOVERY,
[The DB_REGISTER flag was specified, a failure has occurred, and no
recovery flag was specified.],
DB_VERSION_MISMATCH,
[The version of the m4_db library doesn't match the version that created
the database environment.],
regionagain, einval,
[the m4_ref(DB_THREAD) flag was specified and fast mutexes are not
available for this architecture;
The DB_HOME or TMPDIR environment variables were set, but empty;
An incorrectly formatted m4_bold([NAME VALUE]) entry or line was found],
ENOSPC,
[HP-UX only:
Due to the constraints of the PA-RISC memory architecture, HP-UX does not
allow a process to map a file into its address space multiple times.
For this reason, each m4_db environment may be opened only once by a
process on HP-UX; that is, calls to m4_ref(dbenv_open) will fail if the
specified m4_db environment has been opened and not subsequently closed.],
filenotfound)
m4_pf_getter(dbenv_get_home,
database environment home directory, homep,, reference)
m4_pf_getter(dbenv_get_open_flags,
open method flags originally used to create the database environment,, flagsp)
m4_seealso(DbEnv)
m4_page_footer

95
docs_src/env/env_remove.so vendored Normal file
View File

@@ -0,0 +1,95 @@
m4_comment([$Id: env_remove.so,v 10.45 2006/12/08 16:22:45 bostic Exp $])
define(M4PAGELOCAL, dbenv_remove)
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_remove),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__remove(DB_ENV *dbenv, char *db_home, u_int32_t flags);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::remove(const char *db_home, u_int32_t flags);
]))
m4_p([dnl
The m4_refT(dbenv_remove) destroys a m4_db environment if it is not
currently in use. The environment regions, including any backing files,
are removed. Any log or database files and the environment directory are
not removed.])
m4_p([dnl
If there are processes that have called m4_ref(dbenv_open) without
calling m4_ref(dbenv_close) (that is, there are processes currently
using the environment), m4_ref(dbenv_remove) will fail without further
action unless the m4_ref(DB_FORCE) flag is set, in which case
m4_ref(dbenv_remove) will attempt to remove the environment, regardless
of any processes still using it.])
m4_p([dnl
The result of attempting to forcibly destroy the environment when it is
in use is unspecified. Processes using an environment often maintain open
file descriptors for shared regions within it. On UNIX systems, the
environment removal will usually succeed, and processes that have already
joined the region will continue to run in that region without change.
However, processes attempting to join the environment will either fail
or create new regions. On other systems in which the m4_manref(unlink,
2) system call will fail if any process has an open file descriptor for
the file (for example Windows/NT), the region removal will fail.])
m4_p([dnl
Calling m4_ref(dbenv_remove) should not be necessary for most applications
because the m4_db environment is cleaned up as part of normal database
recovery procedures. However, applications may want to call
m4_ref(dbenv_remove) as part of application shut down to free up system
resources. For example, if the m4_ref(DB_SYSTEM_MEM) flag was specified
to m4_ref(dbenv_open), it may be useful to call m4_ref(dbenv_remove) in
order to release system shared memory segments that have been allocated.
Or, on architectures in which mutexes require allocation of underlying
system resources, it may be useful to call m4_ref(dbenv_remove) in order
to release those resources. Alternatively, if recovery is not required
because no database state is maintained across failures, and no system
resources need to be released, it is possible to clean up an environment
by simply removing all the m4_db files in the database environment's
directories.])
m4_p([dnl
In multithreaded applications, only a single thread may call
m4_ref(dbenv_remove).])
m4_p([dnl
A m4_ref(DbEnv) handle that has already been used to open an environment
should not be used to call the m4_refT(dbenv_remove); a new
m4_ref(DbEnv) handle should be created for that purpose.])
m4_p([dnl
After m4_ref(dbenv_remove) has been called, regardless of its return,
the m4_db environment handle may not be accessed again.])
m4_return(dbenv_remove, std)
m4_parambegin
m4_param_utf8(db_home, [dnl
The m4_arg(db_home) parameter names the database environment to be removed.])
m4_param(flags, [dnl
m4_sf_or_may
m4_tagbegin
m4_tag(m4_idef(DB_FORCE), [dnl
If the m4_ref(DB_FORCE) flag is set, the environment is removed, regardless
of any processes that may still using it, and no locks are acquired
during this process. (Generally, the m4_ref(DB_FORCE) flag is
specified only when applications were unable to shut down cleanly, and there
is a risk that an application may have died holding a m4_db lock.)])
m4_env_flags
m4_tagend])
m4_paramend
m4_err(dbenv_remove,
EBUSY, [The shared memory region was in use and the force flag was not set.])
m4_seealso(DbEnv)
m4_page_footer

124
docs_src/env/env_set_alloc.so vendored Normal file
View File

@@ -0,0 +1,124 @@
m4_comment([$Id: env_set_alloc.so,v 1.24 2008/01/19 14:12:57 bostic Exp $])
ifdef([M4INTERFACE],, [define(M4INTERFACE, dbenv_set_alloc)])
define(M4PAGELOCAL, M4INTERFACE)
include(m4/m4.seealso)
ifelse(M4INTERFACE, dbenv_set_alloc, [dnl
m4_pf_header(m4_ref(dbenv_set_alloc),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__set_alloc(DB_ENV *dbenv,
void *(*app_malloc)(size_t),
void *(*app_realloc)(void *, size_t),
void (*app_free)(void *));
])dnl
ifelse(M4API, CXX_API, [dnl
extern "C" {
typedef void *(*db_malloc_fcn_type)(size_t);
typedef void *(*db_realloc_fcn_type)(void *, size_t);
typedef void *(*db_free_fcn_type)(void *);
};
m4_blank
int
DbEnv::set_alloc(db_malloc_fcn_type app_malloc,
db_realloc_fcn_type app_realloc,
db_free_fcn_type app_free);
]))],[dnl
m4_pf_header(m4_ref(dbh_set_alloc),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_alloc(DB *db,
void *(*app_malloc)(size_t),
void *(*app_realloc)(void *, size_t),
void (*app_free)(void *));
])dnl
ifelse(M4API, CXX_API, [dnl
extern "C" {
typedef void *(*db_malloc_fcn_type)(size_t);
typedef void *(*db_realloc_fcn_type)(void *, size_t);
typedef void *(*db_free_fcn_type)(void *);
};
m4_blank
int
Db::set_alloc(db_malloc_fcn_type app_malloc,
db_realloc_fcn_type app_realloc,
db_free_fcn_type app_free);
]))])
m4_p([dnl
Set the allocation functions used by the m4_ref(DbEnv) and m4_ref(Db)
methods to allocate or free memory owned by the application.])
m4_p([dnl
There are a number of interfaces in m4_db where memory is allocated by
the library and then given to the application. For example, the
m4_ref(DB_DBT_MALLOC) flag, when specified in the m4_ref(Dbt) object,
will cause the m4_ref(Db) methods to allocate and reallocate memory
which then becomes the responsibility of the calling application. (See
m4_ref(Dbt) for more information.) Other examples are the m4_db
interfaces which return statistical information to the application:
m4_ref(dbh_stat), m4_ref(lock_stat), m4_ref(log_archive),
m4_ref(log_stat), m4_ref(memp_stat), and m4_ref(txn_stat). There is one
method in m4_db where memory is allocated by the application and then
given to the library: m4_ref(dbh_associate).])
m4_p([dnl
On systems in which there may be multiple library versions of the
standard allocation routines (notably Windows NT), transferring memory
between the library and the application will fail because the m4_db
library allocates memory from a different heap than the application uses
to free it. To avoid this problem, the m4_ref(dbenv_set_alloc) and
m4_refT(dbh_set_alloc)s can be used to pass m4_db references to the
application's allocation routines.])
m4_p([dnl
It is not an error to specify only one or two of the possible allocation
function parameters to these interfaces; however, in that case the
specified interfaces must be compatible with the standard library
interfaces, as they will be used together. The functions specified must
match the calling conventions of the m4_ansic_name library routines of
the same name.])
ifelse(M4INTERFACE, dbenv_set_alloc, [dnl
m4_scope_dbenv(dbenv_set_alloc)
m4_when_envopen(dbenv_set_alloc)
m4_return(dbenv_set_alloc, std)
m4_parambegin
m4_param(app_malloc, [dnl
The m4_arg(app_malloc) parameter is the application-specified malloc
function.])
m4_param(app_realloc, [dnl
The m4_arg(app_realloc) parameter is the application-specified realloc
function.])
m4_param(app_free, [dnl
The m4_arg(app_free) parameter is the application-specified free function.])
m4_paramend
m4_err(dbenv_set_alloc,
einval, [the method was called after m4_ref(dbenv_open) was called])
m4_seealso(DbEnv)
],[dnl
m4_p([dnl
Because databases opened within m4_db environments use the allocation
interfaces specified to the environment, it is an error to attempt to
set those interfaces in a database created within an environment.])
m4_when_dbopen(dbh_set_alloc)
m4_return(dbh_set_alloc, std)
m4_err(dbh_set_alloc,
einval, [dnl
called in a database environment, or called after m4_ref(dbh_open) was
called])
m4_seealso(Db)
])
m4_page_footer

105
docs_src/env/env_set_app_dispatch.so vendored Normal file
View File

@@ -0,0 +1,105 @@
m4_comment([$Id: env_set_app_dispatch.so,v 10.54 2004/08/13 03:38:57 bostic Exp $])
define(M4PAGELOCAL,
[dbenv_set_app_dispatch, DB_TXN_BACKWARD_ROLL, DB_TXN_FORWARD_ROLL,
DB_TXN_ABORT, DB_TXN_APPLY, DB_TXN_PRINT])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_set_app_dispatch),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__set_app_dispatch(DB_ENV *dbenv,
int (*tx_recover)(DB_ENV *dbenv,
DBT *log_rec, DB_LSN *lsn, db_recops op));
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::set_app_dispatch(int (*tx_recover)(DbEnv *dbenv,
Dbt *log_rec, DbLsn *lsn, db_recops op));
]))
define(__appDispatch_param, [dnl
ifelse([$1], internal, [dnl
The m4_arg(tx_recover) parameter is the application's abort and recovery
function. The function takes four parameters:
m4_tagbegin
m4_tag(m4_arg(dbenv), [dnl
The m4_arg(dbenv) parameter is the enclosing database environment handle.])
m4_tag(m4_arg(log_rec), [dnl
The m4_arg(log_rec) parameter is a log record.])
m4_tag(m4_arg(lsn), [dnl
The m4_arg(lsn) parameter is a log sequence number.])
m4_tag(m4_arg(op), [dnl
The m4_arg(op) parameter is one of the following values:])],[dnl
m4_parambegin
m4_param(dbenv, [dnl
The m4_arg(dbenv) parameter is the enclosing database environment handle.])
m4_param(log_rec, [dnl
The m4_arg(log_rec) parameter is a log record.])
m4_param(lsn, [dnl
The m4_arg(lsn) parameter is a log sequence number.])
m4_param(op, [dnl
The m4_arg(op) parameter is one of the following values:])])
m4_tagbegin
m4_tag(m4_idef(DB_TXN_BACKWARD_ROLL), [dnl
The log is being read backward to determine which transactions have been
committed and to abort those operations that were not; undo the operation
described by the log record.])
m4_tag(m4_idef(DB_TXN_FORWARD_ROLL), [dnl
The log is being played forward; redo the operation described by the log
record.])
m4_tag(m4_idef(DB_TXN_ABORT), [dnl
The log is being read backward during a transaction abort; undo the
operation described by the log record.])
m4_tag(m4_idef(DB_TXN_APPLY), [dnl
The log is being applied on a replica site; redo the operation
described by the log record.])
m4_tag(m4_idef(DB_TXN_PRINT), [dnl
The log is being printed for debugging purposes; print the contents of
this log record in the desired format.])
m4_tagend
m4_p([dnl
The m4_ref(DB_TXN_FORWARD_ROLL) and m4_ref(DB_TXN_APPLY) operations
frequently imply the same actions, redoing changes that appear in the
log record, although if a recovery function is to be used on a
replication client where reads may be taking place concurrently with the
processing of incoming messages, m4_ref(DB_TXN_APPLY) operations should
also perform appropriate locking. The macro DB_REDO(op) checks that the
operation is one of m4_ref(DB_TXN_FORWARD_ROLL) or m4_ref(DB_TXN_APPLY),
and should be used in the recovery code to refer to the conditions under
which operations should be redone. Similarly, the macro DB_UNDO(op)
checks if the operation is one of m4_ref(DB_TXN_BACKWARD_ROLL) or
m4_ref(DB_TXN_ABORT).])
ifelse([$1], internal, [m4_tagend], [m4_paramend])])
define(__appDispatch_return, [dnl
The function must return 0 on success and either m4_envvar(errno) or a
value outside of the m4_db error name space on failure.])
m4_p([dnl
Declare a function to be called during transaction abort and recovery
to process application-specific log records.])
m4_scope_dbenv(dbenv_set_app_dispatch)
m4_when_envopen(dbenv_set_app_dispatch, corrupt)
m4_return(dbenv_set_app_dispatch, std)
m4_parambegin
m4_param(tx_recover, [dnl
__appDispatch_param(internal)
m4_p([__appDispatch_return])])
m4_paramend
m4_err(dbenv_set_app_dispatch,
einval, [the method was called after m4_ref(dbenv_open) was called])
m4_seealso(DbTxn)
m4_page_footer

131
docs_src/env/env_set_cachesize.so vendored Normal file
View File

@@ -0,0 +1,131 @@
m4_comment([$Id: env_set_cachesize.so,v 10.51 2007/07/06 00:22:52 mjc Exp $])
ifdef([M4INTERFACE],, [define(M4INTERFACE, dbenv_set_cachesize)])
define(M4GETINTERFACE, ifelse(M4INTERFACE,
dbenv_set_cachesize, dbenv_get_cachesize, dbh_get_cachesize))
define(M4PAGELOCAL, [M4INTERFACE, M4GETINTERFACE, dbenv_get_cachesize_ncache])
include(m4/m4.seealso)
ifelse(M4INTERFACE, dbenv_set_cachesize, [dnl
m4_pf_header(m4_ref(dbenv_set_cachesize),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__set_cachesize(DB_ENV *dbenv,
u_int32_t gbytes, u_int32_t bytes, int ncache);
m4_blank
int
DB_ENV-__GT__get_cachesize(DB_ENV *dbenv,
u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::set_cachesize(u_int32_t gbytes, u_int32_t bytes, int ncache);
m4_blank
int
DbEnv::get_cachesize(u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
]))],[dnl
m4_pf_header(m4_ref(dbh_set_cachesize),
ifelse(M4API, C_API, [dnl
int
DB-__GT__set_cachesize(DB *db,
u_int32_t gbytes, u_int32_t bytes, int ncache);
m4_blank
int
DB-__GT__get_cachesize(DB *db,
u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
])dnl
ifelse(M4API, CXX_API, [dnl
int
Db::set_cachesize(u_int32_t gbytes, u_int32_t bytes, int ncache);
int
Db::get_cachesize(u_int32_t *gbytesp, u_int32_t *bytesp, int *ncachep);
]))])
m4_p([dnl
Set the size of the shared memory buffer pool -- that is, the cache.
The cache should be the size of the normal working data set of the
application, with some small amount of additional memory for unusual
situations. (Note: the working set is not the same as the number of
pages accessed simultaneously, and is usually much larger.)])
m4_p([dnl
The default cache size is 256KB, and may not be specified as less than
20KB. Any cache size less than 500MB is automatically increased by 25%
to account for buffer pool overhead; cache sizes larger than 500MB are
used as specified. The maximum size of a single cache is 4GB on 32-bit
systems and 10TB on 64-bit systems. (All sizes are in powers-of-two,
that is, 256KB is 2^18 not 256,000.) For information on tuning the m4_db
cache size, see m4_link(M4RELDIR/ref/am_conf/cachesize, [Selecting a
cache size]).])
m4_p([dnl
It is possible to specify caches to m4_db large enough they cannot be
allocated contiguously on some architectures. For example, some
releases of Solaris limit the amount of memory that may be allocated
contiguously by a process. If m4_arg(ncache) is 0 or 1, the cache will
be allocated contiguously in memory. If it is greater than 1, the cache
will be split across m4_arg(ncache) separate regions, where the
m4_bold(region size) is equal to the initial cache size divided by
m4_arg(ncache).])
ifelse(M4INTERFACE, dbenv_set_cachesize, [dnl
m4_p([dnl
The memory pool may be resized by calling m4_ref(dbenv_set_cachesize)
after the environment is open. The supplied size will be rounded to
the nearest multiple of the region size and may not be larger than the
maximum size configured with m4_ref(dbenv_set_cache_max). The
m4_arg(ncache) parameter is ignored when resizing the cache.])])
ifelse(M4INTERFACE, dbenv_set_cachesize, [dnl
m4_env_config(dbenv_set_cachesize, [initial cache size], set_cachesize,
[the initial cache size specified in three parts: the gigabytes of
cache, the additional bytes of cache, and the number of caches, also
separated by whitespace characters. For example, "set_cachesize 2
524288000 3" would create a 2.5GB logical cache, split between three
physical caches])
m4_scope_env(dbenv_set_cachesize)
m4_when_any(dbenv_set_cachesize)
m4_return(dbenv_set_cachesize, std)
],[dnl
m4_p([dnl
Because databases opened within m4_db environments use the cache
specified to the environment, it is an error to attempt to set a cache
in a database created within an environment.])
m4_when_dbopen(dbh_set_cachesize)
m4_return(dbh_set_cachesize, std)])
m4_parambegin
m4_param(bytes, [dnl
The size of the cache is set to m4_arg(gbytes) gigabytes plus m4_arg(bytes).])
m4_param(gbytes, [dnl
The size of the cache is set to m4_arg(gbytes) gigabytes plus m4_arg(bytes).])
m4_param(ncache, [dnl
The m4_arg(ncache) parameter is the number of caches to create.])
m4_paramend
m4_err(M4INTERFACE, einval,
[the specified cache size was impossibly small;
ifelse(M4INTERFACE, dbh_set_cachesize, [the method was called after
m4_ref(dbh_open) was called])])
m4_pf_description(m4_ref(M4GETINTERFACE))
m4_p([dnl
The m4_refT(M4GETINTERFACE) returns the current size and composition of the
cache.])
m4_when_any(M4GETINTERFACE)
m4_return(M4GETINTERFACE, std)
m4_parambegin
m4_param_co(bytesp, additional bytes of memory in the cache)
m4_param_co(gbytesp, gigabytes of memory in the cache)
m4_param_co(ncachep, number of caches)
m4_paramend
ifelse(M4INTERFACE, dbenv_set_cachesize, [m4_seealso(DbEnv)], [m4_seealso(Db)])
m4_page_footer

59
docs_src/env/env_set_data_dir.so vendored Normal file
View File

@@ -0,0 +1,59 @@
m4_comment([$Id: env_set_data_dir.so,v 10.28 2004/09/28 15:04:20 bostic Exp $])
define(M4PAGELOCAL, [dbenv_set_data_dir, dbenv_get_data_dirs])
include(m4/m4.seealso)
m4_pf_header(m4_ref(dbenv_set_data_dir),
ifelse(M4API, C_API, [dnl
int
DB_ENV-__GT__set_data_dir(DB_ENV *dbenv, const char *dir);
m4_blank
int
DB_ENV-__GT__get_data_dirs(DB_ENV *dbenv, const char ***dirpp);
])
ifelse(M4API, CXX_API, [dnl
int
DbEnv::set_data_dir(const char *dir);
m4_blank
int
DbEnv::get_data_dirs(const char ***dirpp);
]))
m4_p([dnl
Set the path of a directory to be used as the location of the access
method database files. Paths specified to the m4_ref(dbh_open) function
will be searched relative to this path. Paths set using this method
are additive, and specifying more than one will result in each specified
directory being searched for database files. If any directories are
specified, created database files will always be created in the first
path specified.])
m4_p([dnl
If no database directories are specified, database files must be named
either by absolute paths or relative to the environment home directory.
See m4_link(M4RELDIR/ref/env/naming, [m4_db File Naming]) for more
information.])
m4_env_config(dbenv_set_data_dir,
data directories, set_data_dir, the directory name, no)
m4_scope_dbenv(dbenv_set_data_dir)
m4_when_envopen(dbenv_set_data_dir, corrupt)
m4_return(dbenv_set_data_dir, std)
m4_parambegin
m4_param_utf8(dir, [dnl
The m4_arg(dir) parameter is a directory to be used as a location for
database files.])
m4_paramend
m4_err(dbenv_set_data_dir,
einval, [the method was called after m4_ref(dbenv_open) was called])
m4_pf_getter(dbenv_get_data_dirs,
NULL-terminated array of directories,, dirpp, reference)
m4_seealso(DbEnv)
m4_page_footer

Some files were not shown because too many files have changed in this diff Show More