Initial revision

CVS patchset: 5721 CVS date: 2002/09/19 20:33:51
author: jbj <devnull@localhost> 2002-09-19 20:33:51 +0000
committer: jbj <devnull@localhost> 2002-09-19 20:33:51 +0000
commit: 4a15060bcbf38c550f7dcc86ceff277854f9eecf (patch)
tree: aa3e3172c87f3f74ea72d72f342f68c4be652c73 /db/docs/ref
parent: 0fd303f38a72c9a465081a7b1b9a77f7d181fd84 (diff)
download: rpm-4a15060bcbf38c550f7dcc86ceff277854f9eecf.tar.gz
rpm-4a15060bcbf38c550f7dcc86ceff277854f9eecf.tar.bz2
rpm-4a15060bcbf38c550f7dcc86ceff277854f9eecf.zip
5 files changed, 263 insertions, 0 deletions
diff --git a/db/docs/ref/distrib/port.html b/db/docs/ref/distrib/port.html
new file mode 100644
index 000000000..d453973e9
--- /dev/null
+++ b/db/docs/ref/distrib/port.html
@@ -0,0 +1,110 @@
+<!--Id: port.so,v 10.3 2002/08/30 19:57:07 bostic Exp -->
+<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
+<!--All rights reserved.-->
+<!--See the file LICENSE for redistribution information.-->
+<html>
+<head>
+<title>Berkeley DB Reference Guide: Porting Berkeley DB to new architectures</title>
+<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
+<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
+</head>
+<body bgcolor=white>
+<table width="100%"><tr valign=top>
+<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Distribution</dl></h3></td>
+<td align=right><a href="../../ref/test/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/distrib/layout.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p>
+<h1 align=center>Porting Berkeley DB to new architectures</h1>
+<p>Berkeley DB is generally easy to port to new architectures.  Berkeley DB was
+designed to be as portable as possible, and has been ported to a wide
+variety of systems, from Wind River's Tornado system, to VMS, to
+Windows/NT and Windows/95, and most existing UNIX platforms.  It runs
+on 16, 32 and 64-bit machines, little or big-endian.  The difficulty of
+a port depends on how much of the ANSI C and POSIX 1003.1 standards the
+new architecture offers.
+<p>An abstraction layer separates the main Berkeley DB code from the operating
+system and architecture specific components.   This layer is comprised
+of approximately 2500 lines of C language code, found in the <b>os</b>
+subdirectory of the Berkeley DB distribution.  The following list of files
+include functionality that may need to be modified or implemented in
+order to support a new architecture.  Within each file, there is usually
+one, but sometimes several functions (for example, the
+<b>os_alloc.c</b> file contains the malloc, calloc, realloc, free,
+and strdup functions).
+<p><table border=1 align=center>
+<tr><th>Source file</th><th>Description</th></tr>
+<tr><td>os_abs.c</td><td>Return if a filename is an absolute pathname</td></tr>
+<tr><td>os_alloc.c</td><td>ANSI C malloc, calloc, realloc, strdup, free front-ends</td></tr>
+<tr><td>os_clock.c</td><td>Return the current time-of-day</td></tr>
+<tr><td>os_config.c</td><td>Return run-time configuration information</td></tr>
+<tr><td>os_dir.c</td><td>Read the filenames from a directory</td></tr>
+<tr><td>os_errno.c</td><td>Set/get the ANSI C errno value</td></tr>
+<tr><td>os_fid.c</td><td>Create a unique ID for a file</td></tr>
+<tr><td>os_fsync.c</td><td>POSIX 1003.1 fsync front-end</td></tr>
+<tr><td>os_handle.c</td><td>Open file handles</td></tr>
+<tr><td>os_id.c</td><td>Return thread ID</td></tr>
+<tr><td>os_map.c</td><td>Map a shared memory area</td></tr>
+<tr><td>os_method.c</td><td>Run-time replacement of system calls</td></tr>
+<tr><td>os_oflags.c</td><td>Convert POSIX 1003.1 open flags, modes to Berkeley DB flags</td></tr>
+<tr><td>os_open.c</td><td>Open file handles</td></tr>
+<tr><td>os_region.c</td><td>Map a shared memory area</td></tr>
+<tr><td>os_rename.c</td><td>POSIX 1003.1 rename call</td></tr>
+<tr><td>os_root.c</td><td>Return if application has special permissions</td></tr>
+<tr><td>os_rpath.c</td><td>Return last pathname separator</td></tr>
+<tr><td>os_rw.c</td><td>POSIX 1003.1 read/write calls</td></tr>
+<tr><td>os_seek.c</td><td>POSIX 1003.1 seek call</td></tr>
+<tr><td>os_sleep.c</td><td>Cause a thread of control to release the CPU</td></tr>
+<tr><td>os_spin.c</td><td>Return the times to spin while waiting for a mutex</td></tr>
+<tr><td>os_stat.c</td><td>POSIX 1003.1 stat call</td></tr>
+<tr><td>os_tmpdir.c</td><td>Set the path for temporary files</td></tr>
+<tr><td>os_unlink.c</td><td>POSIX 1003.1 unlink call</td></tr>
+</table>
+<p>All but a few of these files contain relatively trivial pieces of code.
+Typically, there is only a single version of the code for all platforms
+Berkeley DB supports, and that code lives in the <b>os</b> directory of the
+distribution.  Where different code is required, the code is either
+conditionally compiled or an entirely different version is written. For
+example, VxWorks versions of some of these files can be found in the
+distribution directory os_vxworks, and Win32 versions can be found in
+os_win32.
+<p>Historically, there are only two difficult questions to answer for each
+new port.  The first question is how to handle shared memory.  In order
+to write multiprocess database applications (not multithreaded, but
+threads of control running in different address spaces), Berkeley DB must be
+able to name pieces of shared memory and access them from multiple
+processes.  On UNIX/POSIX systems, we use <b>mmap</b> and
+<b>shmget</b> for that purpose, but any interface that provides access
+to named shared memory is sufficient.  If you have a simple, flat
+address space, you should be able to use the code in
+<b>os_vxworks/os_map.c</b> as a starting point for the port.  If you
+are not intending to write multiprocess database applications, then
+this won't be necessary, as Berkeley DB can simply allocate memory from the
+heap if all threads of control will live in a single address space.
+<p>The second question is mutex support.  Berkeley DB requires some form of
+<b>self-blocking</b> mutual exclusion mutex.  Blocking mutexes are
+preferred as they tend to be less CPU-expensive and less likely to cause
+thrashing.  If blocking mutexes are not available, however, test-and-set
+will work as well.  The code for mutexes is in two places in the system:
+the include file <b>dbinc/mutex.h</b>, and the distribution directory
+<b>mutex</b>.
+<p>Berkeley DB uses the GNU autoconf tools for configuration on almost all of
+the platforms it supports.  Specifically, the include file
+<b>db_config.h</b> configures the Berkeley DB build.  The simplest way to
+begin a port is to configure and build Berkeley DB on a UNIX or UNIX-like
+system, and then take the <b>Makefile</b> and <b>db_config.h</b>
+file created by that configuration, and modify it by hand to reflect
+the needs of the new architecture.  Unless you're already familiar with
+the GNU autoconf toolset, we don't recommend you take the time to
+integrate your changes back into the Berkeley DB autoconfiguration framework.
+Instead, send Sleepycat Software context diffs of your changes and any
+new source files you created, and we'll integrate the changes into our
+source tree.
+<p>Finally, we're happy to work with you on the port, or potentially, do
+the port ourselves, if that is of interest to you.  Regardless, if you
+have any porting questions, just let us know, and we will be happy to
+answer them.
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/test/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/distrib/layout.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
+</body>
+</html>
diff --git a/db/docs/ref/env/db_config.html b/db/docs/ref/env/db_config.html
new file mode 100644
index 000000000..bfb2afce2
--- /dev/null
+++ b/db/docs/ref/env/db_config.html
@@ -0,0 +1,51 @@
+<!--Id: db_config.so,v 10.1 2002/09/03 20:09:29 bostic Exp -->
+<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
+<!--All rights reserved.-->
+<!--See the file LICENSE for redistribution information.-->
+<html>
+<head>
+<title>Berkeley DB Reference Guide: DB_CONFIG configuration file</title>
+<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
+<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
+</head>
+<body bgcolor=white>
+<a name="2"><!--meow--></a><a name="3"><!--meow--></a>
+<table width="100%"><tr valign=top>
+<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Environment</dl></h3></td>
+<td align=right><a href="../../ref/env/error.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/naming.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p>
+<h1 align=center>DB_CONFIG configuration file</h1>
+<p>Most of the configuration information that can be specified to
+<a href="../../api_c/env_class.html">DB_ENV</a> methods can also be specified using a configuration file.
+If an environment home directory has been specified (either by the
+application specifying a non-NULL <b>db_home</b> argument to
+<a href="../../api_c/env_open.html">DB_ENV-&gt;open</a>, or by the application setting the
+<a href="../../api_c/env_open.html#DB_USE_ENVIRON">DB_USE_ENVIRON</a> or <a href="../../api_c/env_open.html#DB_USE_ENVIRON_ROOT">DB_USE_ENVIRON_ROOT</a> flags and the
+<a href="../../ref/env/naming.html#DB_HOME">DB_HOME</a> environment variable being set), any file named
+DB_CONFIG in the database home directory will be read for lines
+of the format <b>NAME VALUE</b>.
+<p>One or more whitespace characters are used to delimit the two parts of
+the line, and trailing whitespace characters are discarded.  All empty
+lines or lines whose first character is a whitespace or hash
+(<b>#</b>) character will be ignored.  Each line must specify both
+the NAME and the VALUE of the pair.  The specific NAME VALUE pairs are
+documented in the manual for the corresponding methods (for example,
+the <a href="../../api_c/env_set_data_dir.html">DB_ENV-&gt;set_data_dir</a> documentation includes NAME VALUE pair
+information Berkeley DB administrators can use to configure locations for
+database files).
+<p>The DB_CONFIG configuration file is intended to allow database
+environment administrators to customize environments independent of
+applications using the environment.  For example, a database
+administrator can move the database log and data files to a different
+location without application recompilation.  In addition, because the
+DB_CONFIG file is read when the database environment is opened,
+it can be used to overrule application configuration done before that
+time.  For example a database administrator could override the
+compiled-in application cache size to a size more appropriate for a
+specific machine.
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/env/error.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/env/naming.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
+</body>
+</html>
diff --git a/db/docs/ref/upgrade.4.1/cxx.html b/db/docs/ref/upgrade.4.1/cxx.html
new file mode 100644
index 000000000..0e6958823
--- /dev/null
+++ b/db/docs/ref/upgrade.4.1/cxx.html
@@ -0,0 +1,48 @@
+<!--Id: cxx.so,v 1.3 2002/08/27 02:28:31 bostic Exp -->
+<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
+<!--All rights reserved.-->
+<!--See the file LICENSE for redistribution information.-->
+<html>
+<head>
+<title>Berkeley DB Reference Guide: Release 4.1: C++ exceptions</title>
+<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
+<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
+</head>
+<body bgcolor=white>
+<table width="100%"><tr valign=top>
+<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td>
+<td align=right><a href="../../ref/upgrade.4.1/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/app_dispatch.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p>
+<h1 align=center>Release 4.1: C++ exceptions</h1>
+<p>With default flags, the C++ <a href="../../api_cxx/env_class.html">DbEnv</a> and <a href="../../api_cxx/db_class.html">Db</a> classes
+can throw exceptions from their constructors.  For example, this can
+happen if invalid parameters are passed in or the underlying C
+structures could not be created.  If the objects are created in an
+environment that is not configured for exceptions (that is, the
+<a href="../../api_c/env_class.html#DB_CXX_NO_EXCEPTIONS">DB_CXX_NO_EXCEPTIONS</a> flag is specified), errors from the
+constructor will be returned when the handle's open method is called.
+<p>In addition, the behavior of the <a href="../../api_cxx/env_class.html">DbEnv</a> and <a href="../../api_cxx/db_class.html">Db</a>
+destructors has changed to simplify exception handling in applications.
+The destructors will now close the handle if the handle's close method
+was not called prior to the object being destroyed.  The return value
+of the call is discarded, and no exceptions will be thrown.
+Applications should call the close method in normal situations so any
+errors while closing can be handled by the application.
+<p>This change allows applications to be structured as follows:
+<p><blockquote><pre>try {
+	DbEnv env(0);
+	env.open(/* ... */);
+	Db db(&env, 0);
+	db.open(/* ... */);
+	/* ... */
+	db.close(0);
+	env.close(0);
+} catch (DbException &dbe) {
+	// Handle the exception, the handles have already been closed.
+}</pre></blockquote>
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/java.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/app_dispatch.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
+</body>
+</html>
diff --git a/db/docs/ref/upgrade.4.1/hash_nelem.html b/db/docs/ref/upgrade.4.1/hash_nelem.html
new file mode 100644
index 000000000..1da26083d
--- /dev/null
+++ b/db/docs/ref/upgrade.4.1/hash_nelem.html
@@ -0,0 +1,25 @@
+<!--Id: hash_nelem.so,v 1.2 2002/08/26 23:05:29 mjc Exp -->
+<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
+<!--All rights reserved.-->
+<!--See the file LICENSE for redistribution information.-->
+<html>
+<head>
+<title>Berkeley DB Reference Guide: Release 4.1: DB-&gt;stat.hash_nelem</title>
+<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
+<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
+</head>
+<body bgcolor=white>
+<table width="100%"><tr valign=top>
+<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td>
+<td align=right><a href="../../ref/upgrade.4.1/memp_sync.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/java.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p>
+<h1 align=center>Release 4.1: DB-&gt;stat.hash_nelem</h1>
+<p>The <b>hash_nelem</b> field of the <a href="../../api_c/db_stat.html">DB-&gt;stat</a> method for Hash
+databases has been removed from the 4.1 release, this information is no
+longer available to applications.
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/memp_sync.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/java.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
+</body>
+</html>
diff --git a/db/docs/ref/upgrade.4.1/java.html b/db/docs/ref/upgrade.4.1/java.html
new file mode 100644
index 000000000..ac1f17654
--- /dev/null
+++ b/db/docs/ref/upgrade.4.1/java.html
@@ -0,0 +1,29 @@
+<!--Id: java.so,v 1.2 2002/08/27 01:11:08 bostic Exp -->
+<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
+<!--All rights reserved.-->
+<!--See the file LICENSE for redistribution information.-->
+<html>
+<head>
+<title>Berkeley DB Reference Guide: Release 4.1: Java exceptions</title>
+<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
+<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
+</head>
+<body bgcolor=white>
+<table width="100%"><tr valign=top>
+<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Upgrading Berkeley DB Applications</dl></h3></td>
+<td align=right><a href="../../ref/upgrade.4.1/hash_nelem.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/cxx.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p>
+<h1 align=center>Release 4.1: Java exceptions</h1>
+<p>The Java <a href="../../api_java/env_class.html">DbEnv</a> constructor is now marked with "throws
+DbException".  This means applications must construct <a href="../../api_java/env_class.html">DbEnv</a>
+objects in a context where <a href="../../api_java/except_class.html">DbException</a> throwables are
+handled (either in a try/catch block or in a method that propagates the
+exception up the stack).  Note that previous versions of the Berkeley DB Java
+API could throw this exception from the constructor but it was not
+marked.
+<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/upgrade.4.1/hash_nelem.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/upgrade.4.1/cxx.html"><img src="../../images/next.gif" alt="Next"></a>
+</td></tr></table>
+<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
+</body>
+</html>
author	jbj <devnull@localhost>	2002-09-19 20:33:51 +0000
committer	jbj <devnull@localhost>	2002-09-19 20:33:51 +0000
commit	4a15060bcbf38c550f7dcc86ceff277854f9eecf (patch)
tree	aa3e3172c87f3f74ea72d72f342f68c4be652c73 /db/docs/ref
parent	0fd303f38a72c9a465081a7b1b9a77f7d181fd84 (diff)
download	rpm-4a15060bcbf38c550f7dcc86ceff277854f9eecf.tar.gz rpm-4a15060bcbf38c550f7dcc86ceff277854f9eecf.tar.bz2 rpm-4a15060bcbf38c550f7dcc86ceff277854f9eecf.zip