Import BSDDB 4.7.25 (as of svn r89086)
This commit is contained in:
Zachary Ware
245
docs_src/db/db_open.so
Normal file
245
docs_src/db/db_open.so
Normal 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
|
||||
Reference in New Issue
Block a user