← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/api_cxx/db_open.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

Lines of Context:
libdb/docs/api_cxx/db_open.html
1
 
<!--$Id$-->
2
 
<!--$Id$-->
3
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
4
 
<!--All rights reserved.-->
5
 
<!--See the file LICENSE for redistribution information.-->
6
 
<html>
7
 
<head>
8
 
<title>Berkeley DB: Db::open</title>
9
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
10
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
11
 
</head>
12
 
<body bgcolor=white>
13
 
<a name="2"><!--meow--></a>
14
 
<table width="100%"><tr valign=top>
15
 
<td>
16
 
<h1>Db::open</h1>
17
 
</td>
18
 
<td align=right>
19
 
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
20
 
</td></tr></table>
21
 
<hr size=1 noshade>
22
 
<tt>
23
 
<h3><pre>
24
 
#include &lt;db_cxx.h&gt;
25
 
<p>
26
 
int
27
 
Db::open(DbTxn *txnid, const char *file,
28
 
    const char *database, DBTYPE type, u_int32_t flags, int mode);
29
 
</pre></h3>
30
 
<h1>Description</h1>
31
 
<p>The currently supported Berkeley DB file formats (or <i>access methods</i>)
32
 
are Btree, Hash, Queue, and Recno.  The Btree format is a representation
33
 
of a sorted, balanced tree structure.  The Hash format is an extensible,
34
 
dynamic hashing scheme.  The Queue format supports fast access to
35
 
fixed-length records accessed sequentially or by logical record number.
36
 
The Recno format supports fixed- or variable-length records, accessed
37
 
sequentially or by logical record number, and optionally backed by a
38
 
flat text file.
39
 
<p>Storage and retrieval for the Berkeley DB access methods are based on key/data
40
 
pairs; see <a href="../api_cxx/dbt_class.html">Dbt</a> for more information.
41
 
<p>The Db::open interface opens the database represented by the
42
 
<b>file</b> and <b>database</b> arguments for both reading and
43
 
writing.  The <b>file</b> argument is used as the name of an underlying
44
 
file that will be used to back the database.  The <b>database</b>
45
 
argument is optional, and allows applications to have multiple databases
46
 
in a single file.  Although no <b>database</b> argument needs to be
47
 
specified, it is an error to attempt to open a second database in a
48
 
<b>file</b> that was not initially created using a <b>database</b>
49
 
name.  Further, the <b>database</b> argument is not supported by the
50
 
Queue format.  Finally, when opening multiple databases in the same
51
 
physical file, it is important to consider locking and memory cache
52
 
issues; see <a href="../ref/am/opensub.html">Opening multiple databases
53
 
in a single file</a> for more information.
54
 
<p>In-memory databases never intended to be preserved on disk may be
55
 
created by setting both the <b>file</b> and <b>database</b> arguments
56
 
to NULL.  Note that in-memory databases can only ever be shared by
57
 
sharing the single database handle that created them, in circumstances
58
 
where doing so is safe.
59
 
<p>The <b>type</b> argument is of type DBTYPE, and must be set to one of <a name="DB_BTREE">DB_BTREE</a>,
60
 
<a name="DB_HASH">DB_HASH</a>, <a name="DB_QUEUE">DB_QUEUE</a>,
61
 
<a name="DB_RECNO">DB_RECNO</a>, or <a name="DB_UNKNOWN">DB_UNKNOWN</a>.  If
62
 
<b>type</b> is DB_UNKNOWN, the database must already exist
63
 
and Db::open will automatically determine its type.  The
64
 
<a href="../api_cxx/db_get_type.html">Db::get_type</a> method may be used to determine the underlying type of
65
 
databases opened using DB_UNKNOWN.
66
 
<p>If the operation is to be transaction-protected (other than by specifying
67
 
the DB_AUTO_COMMIT flag), the <b>txnid</b> parameter is a
68
 
transaction handle returned from <a href="../api_cxx/txn_begin.html">DbEnv::txn_begin</a>; otherwise, NULL.
69
 
<p>The <b>flags</b> and <b>mode</b> arguments specify how files will be opened
70
 
and/or created if they do not already exist.
71
 
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
72
 
more of the following values:
73
 
<p><dl compact>
74
 
<p><dt><a name="DB_AUTO_COMMIT">DB_AUTO_COMMIT</a><dd>Enclose the Db::open call within a transaction.  If the call succeeds,
75
 
the open operation will be recoverable.  If the call fails, no database will
76
 
have been created.
77
 
<p><dt><a name="DB_CREATE">DB_CREATE</a><dd>Create the database.  If the database does not already exist and the DB_CREATE
78
 
flag is not specified, the Db::open will fail.
79
 
<p><dt><a name="DB_DIRTY_READ">DB_DIRTY_READ</a><dd>Support dirty reads; that is, read operations on the database may request the
80
 
return of modified but not yet committed data.
81
 
<p><dt><a name="DB_EXCL">DB_EXCL</a><dd>Return an error if the database already exists.  The DB_EXCL flag is
82
 
only meaningful when specified with the DB_CREATE flag.
83
 
<p><dt><a name="DB_NOMMAP">DB_NOMMAP</a><dd>Do not map this database into process memory (see the description of the
84
 
<a href="../api_cxx/env_set_mp_mmapsize.html">DbEnv::set_mp_mmapsize</a> method for further information).
85
 
<p><dt><a name="DB_RDONLY">DB_RDONLY</a><dd>Open the database for reading only.  Any attempt to modify items in the database
86
 
will fail, regardless of the actual permissions of any underlying files.
87
 
<p><dt><a name="DB_THREAD">DB_THREAD</a><dd>Cause the <a href="../api_cxx/db_class.html">Db</a> handle returned by Db::open to be
88
 
<i>free-threaded</i>; that is, usable by multiple threads within a
89
 
single address space.
90
 
<p><dt><a name="DB_TRUNCATE">DB_TRUNCATE</a><dd>Physically truncate the underlying file, discarding all previous
91
 
databases it might have held.  Underlying filesystem primitives are used
92
 
to implement this flag.  For this reason, it is applicable only to the
93
 
file and cannot be used to discard databases within a file.
94
 
<p>The DB_TRUNCATE flag cannot be transaction-protected, and it is
95
 
an error to specify it in a transaction-protected environment.
96
 
</dl>
97
 
<p>On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, all files created by
98
 
the database open are created with mode <b>mode</b> (as described in <b>chmod</b>(2)) and modified by the process' umask value at the time of creation
99
 
(see <b>umask</b>(2)).  If <b>mode</b> is 0, the database open will use a default
100
 
mode of readable and writable by both owner and group.  On Windows
101
 
systems, the mode argument is ignored. The group ownership of created
102
 
files is based on the system and directory defaults, and is not further
103
 
specified by Berkeley DB.
104
 
<p>Calling Db::open is a reasonably expensive operation, and maintaining
105
 
a set of open databases will normally be preferable to repeatedly opening
106
 
and closing the database for each new query.
107
 
<p>The Db::open method either returns a non-zero error value or throws an exception that
108
 
encapsulates a non-zero error value on failure, and returns 0 on success.
109
 
If Db::open fails, the <a href="../api_cxx/db_close.html">Db::close</a> method should be called to discard the
110
 
<a href="../api_cxx/db_class.html">Db</a> handle.
111
 
<h1>Environment Variables</h1>
112
 
<p><dl compact>
113
 
<p><dt>DB_HOME<dd>If a <b>dbenv</b> argument to <a href="../api_c/db_create.html">db_create</a> was specified, the
114
 
environment variable <b>DB_HOME</b> may be used as the path of the
115
 
database environment home.
116
 
<p>Db::open is affected by any database directory specified using the
117
 
<a href="../api_cxx/env_set_data_dir.html">DbEnv::set_data_dir</a> method, or by setting the "set_data_dir" string
118
 
in the environment's <b>DB_CONFIG</b> file.
119
 
</dl>
120
 
<p><dl compact>
121
 
<p><dt>TMPDIR<dd>If the <b>file</b> and <b>dbenv</b> arguments to Db::open are
122
 
NULL, the environment variable <b>TMPDIR</b> may be used as a
123
 
directory in which to create temporary backing files
124
 
</dl>
125
 
<h1>Errors</h1>
126
 
<p>The Db::open method may fail and throw an exception or return a non-zero error for the following conditions:
127
 
<p><dl compact>
128
 
<p><dt><a name="DB_OLD_VERSION">DB_OLD_VERSION</a><dd>The database cannot be opened without being first upgraded.
129
 
<p><dt>EEXIST<dd>DB_CREATE and DB_EXCL were specified and the database exists.
130
 
<p><dt>EINVAL<dd>An invalid flag value or parameter was specified.
131
 
(For example, unknown database type, page size, hash function, pad byte,
132
 
byte order) or a flag value or parameter that is incompatible with the
133
 
specified database.
134
 
<p>
135
 
The <a href="../api_cxx/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified and fast mutexes are not
136
 
available for this architecture.
137
 
<p>The <a href="../api_cxx/env_open.html#DB_THREAD">DB_THREAD</a> flag was specified to Db::open, but was not
138
 
specified to the <a href="../api_cxx/env_open.html">DbEnv::open</a> call for the environment in which the
139
 
<a href="../api_cxx/db_class.html">Db</a> handle was created.
140
 
<p>A backing flat text file was specified with either the <a href="../api_cxx/env_open.html#DB_THREAD">DB_THREAD</a>
141
 
flag or the provided database environment supports transaction
142
 
processing.
143
 
<p><dt>ENOENT<dd>A nonexistent <b>re_source</b> file was specified.
144
 
</dl>
145
 
<p>The Db::open method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods.
146
 
If a catastrophic error has occurred, the Db::open method may fail and
147
 
either return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> or throw a
148
 
<a href="../api_cxx/runrec_class.html">DbRunRecoveryException</a>,
149
 
in which case all subsequent Berkeley DB calls will fail in the same way.
150
 
<h1>Class</h1>
151
 
<a href="../api_cxx/db_class.html">Db</a>
152
 
<h1>See Also</h1>
153
 
<a href="../api_cxx/db_list.html">Databases and Related Methods</a>
154
 
</tt>
155
 
<table width="100%"><tr><td><br></td><td align=right>
156
 
<a href="../api_cxx/c_index.html"><img src="../images/api.gif" alt="API"></a><a href="../reftoc.html"><img src="../images/ref.gif" alt="Ref"></a>
157
 
</td></tr></table>
158
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
159
 
</body>
160
 
</html>