diff options
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 |
Initial revision
CVS patchset: 5721
CVS date: 2002/09/19 20:33:51
Diffstat (limited to 'db/docs/ref')
-rw-r--r-- | db/docs/ref/distrib/port.html | 110 | ||||
-rw-r--r-- | db/docs/ref/env/db_config.html | 51 | ||||
-rw-r--r-- | db/docs/ref/upgrade.4.1/cxx.html | 48 | ||||
-rw-r--r-- | db/docs/ref/upgrade.4.1/hash_nelem.html | 25 | ||||
-rw-r--r-- | db/docs/ref/upgrade.4.1/java.html | 29 |
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->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->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->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->stat.hash_nelem</h1> +<p>The <b>hash_nelem</b> field of the <a href="../../api_c/db_stat.html">DB->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> |