← 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/env_remove.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/env_remove.html
1
 
<!--$Id$-->
2
 
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB: DbEnv::remove</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<a name="2"><!--meow--></a>
13
 
<table width="100%"><tr valign=top>
14
 
<td>
15
 
<h1>DbEnv::remove</h1>
16
 
</td>
17
 
<td align=right>
18
 
<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>
19
 
</td></tr></table>
20
 
<hr size=1 noshade>
21
 
<tt>
22
 
<h3><pre>
23
 
#include &lt;db_cxx.h&gt;
24
 
<p>
25
 
int
26
 
DbEnv::remove(const char *db_home, u_int32_t flags);
27
 
</pre></h3>
28
 
<h1>Description</h1>
29
 
<p>The DbEnv::remove method destroys a Berkeley DB environment if it is not
30
 
currently in use.  The environment regions, including any backing files,
31
 
are removed.  Any log or database files and the environment directory are
32
 
not removed.
33
 
<p>The <b>db_home</b> argument to DbEnv::remove is described in
34
 
<a href="../ref/env/naming.html">Berkeley DB File Naming</a>.
35
 
<p>If there are processes that have called <a href="../api_cxx/env_open.html">DbEnv::open</a> without
36
 
calling <a href="../api_cxx/env_close.html">DbEnv::close</a> (that is, there are processes currently
37
 
using the environment), DbEnv::remove will fail without further
38
 
action unless the <a href="../api_cxx/env_remove.html#DB_FORCE">DB_FORCE</a> flag is set, in which case
39
 
DbEnv::remove will attempt to remove the environment, regardless
40
 
of any processes still using it.
41
 
<p>The result of attempting to forcibly destroy the environment when it is
42
 
in use is unspecified.  Processes using an environment often maintain open
43
 
file descriptors for shared regions within it.  On UNIX systems, the
44
 
environment removal will usually succeed, and processes that have already
45
 
joined the region will continue to run in that region without change.
46
 
However, processes attempting to join the environment will either fail
47
 
or create new regions.  On other systems in which the <b>unlink</b>(2) system call will fail if any process has an open file descriptor for
48
 
the file (for example Windows/NT), the region removal will fail.
49
 
<p>Calling DbEnv::remove should not be necessary for most applications
50
 
because the Berkeley DB environment is cleaned up as part of normal database
51
 
recovery procedures. However, applications may want to call
52
 
DbEnv::remove as part of application shut down to free up system
53
 
resources.  For example, if the <a href="../api_cxx/env_open.html#DB_SYSTEM_MEM">DB_SYSTEM_MEM</a> flag was specified
54
 
to <a href="../api_cxx/env_open.html">DbEnv::open</a>, it may be useful to call DbEnv::remove in
55
 
order to release system shared memory segments that have been allocated.
56
 
Or, on architectures in which mutexes require allocation of underlying
57
 
system resources, it may be useful to call DbEnv::remove in order
58
 
to release those resources.  Alternatively, if recovery is not required
59
 
because no database state is maintained across failures, and no system
60
 
resources need to be released, it is possible to clean up an environment
61
 
by simply removing all the Berkeley DB files in the database environment's
62
 
directories.
63
 
<p>The <b>flags</b> value must be set to 0 or by bitwise inclusively <b>OR</b>'ing together one or
64
 
more of the following values:
65
 
<p><dl compact>
66
 
<p><dt><a name="DB_FORCE">DB_FORCE</a><dd>If the <a href="../api_cxx/env_remove.html#DB_FORCE">DB_FORCE</a> flag is set, the environment is removed, regardless
67
 
of any processes that may still using it, and no locks are acquired
68
 
during this process.  (Generally, the <a href="../api_cxx/env_remove.html#DB_FORCE">DB_FORCE</a> flag is
69
 
specified only when applications were unable to shut down cleanly, and there
70
 
is a risk that an application may have died holding a Berkeley DB lock.)
71
 
<a name="3"><!--meow--></a>
72
 
<p><dt><a name="DB_USE_ENVIRON">DB_USE_ENVIRON</a><dd>The Berkeley DB process' environment may be permitted to specify information
73
 
to be used when naming files; see <a href="../ref/env/naming.html">Berkeley DB File Naming</a>.  Because permitting users to specify which files
74
 
are used can create security problems, environment information will be
75
 
used in file naming for all users only if the DB_USE_ENVIRON
76
 
flag is set.
77
 
<p><dt><a name="DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a><dd>The Berkeley DB process' environment may be permitted to specify information
78
 
to be used when naming files; see <a href="../ref/env/naming.html">Berkeley DB File Naming</a>.  Because permitting users to specify which files
79
 
are used can create security problems, if the
80
 
DB_USE_ENVIRON_ROOT flag is set, environment information will
81
 
be used for file naming only for users with appropriate permissions (for
82
 
example, users with a user-ID of 0 on UNIX systems).
83
 
</dl>
84
 
<p>In multithreaded applications, only a single thread may call
85
 
DbEnv::remove.
86
 
<p>A <a href="../api_cxx/env_class.html">DbEnv</a> handle that has already been used to open an environment
87
 
should not be used to call the DbEnv::remove method; a new
88
 
<a href="../api_cxx/env_class.html">DbEnv</a> handle should be created for that purpose.
89
 
<p>After DbEnv::remove has been called, regardless of its return,
90
 
the Berkeley DB environment handle may not be accessed again.
91
 
<p>The DbEnv::remove method either returns a non-zero error value or throws an exception that
92
 
encapsulates a non-zero error value on failure, and returns 0 on success.
93
 
<h1>Errors</h1>
94
 
<p><dl compact>
95
 
<p><dt>EBUSY<dd>The shared memory region was in use and the force flag was not set.
96
 
</dl>
97
 
<p>If the file or directory does not exist, the DbEnv::remove method will
98
 
fail and
99
 
and either return ENOENT or
100
 
throw a FileNotFoundException exception.
101
 
<p>The DbEnv::remove 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.
102
 
If a catastrophic error has occurred, the DbEnv::remove method may fail and
103
 
either return <a href="../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> or throw a
104
 
<a href="../api_cxx/runrec_class.html">DbRunRecoveryException</a>,
105
 
in which case all subsequent Berkeley DB calls will fail in the same way.
106
 
<h1>Class</h1>
107
 
<a href="../api_cxx/env_class.html">DbEnv</a>
108
 
<h1>See Also</h1>
109
 
<a href="../api_cxx/env_list.html">Database Environments and Related Methods</a>
110
 
</tt>
111
 
<table width="100%"><tr><td><br></td><td align=right>
112
 
<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>
113
 
</td></tr></table>
114
 
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
115
 
</body>
116
 
</html>