246 lines
9.4 KiB
Plaintext
246 lines
9.4 KiB
Plaintext
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
|