docs/installation/build_unix_notes.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <head>
   5     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6     <title>Architecture independent FAQ</title>
   7     <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
   8     <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
   9     <link rel="start" href="index.html" title="Berkeley DB Installation and Build Guide" />
  10     <link rel="up" href="build_unix.html" title="Chapter 7.  Building Berkeley DB for UNIX/POSIX" />
  11     <link rel="prev" href="build_unix_test.html" title="Running the test suite under UNIX" />
  12     <link rel="next" href="build_unix_aix.html" title="AIX" />
  13   </head>
  14   <body>
  15     <div xmlns="" class="navheader">
  16       <div class="libver">
  17         <p>Library Version 11.2.5.3</p>
  18       </div>
  19       <table width="100%" summary="Navigation header">
  20         <tr>
  21           <th colspan="3" align="center">Architecture independent FAQ</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="build_unix_test.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 7.
  26                 Building Berkeley DB for UNIX/POSIX
  27         </th>
  28           <td width="20%" align="right"> <a accesskey="n" href="build_unix_aix.html">Next</a></td>
  29         </tr>
  30       </table>
  31       <hr />
  32     </div>
  33     <div class="sect1" lang="en" xml:lang="en">
  34       <div class="titlepage">
  35         <div>
  36           <div>
  37             <h2 class="title" style="clear: both"><a id="build_unix_notes"></a>Architecture independent FAQ</h2>
  38           </div>
  39         </div>
  40       </div>
  41       <div class="orderedlist">
  42         <ol type="1">
  43           <li>
  44             <span class="bold">
  45               <strong>I have gcc installed, but configure fails to find it.</strong>
  46             </span>
  47             <p>Berkeley DB defaults to using the native C compiler if none is specified.
  48 That is usually "cc", but some platforms require a different compiler
  49 to build multithreaded code.  To configure Berkeley DB to build with gcc, run
  50 configure as follows:</p>
  51             <pre class="programlisting">env CC=gcc ../dist/configure ...</pre>
  52           </li>
  53           <li>
  54             <span class="bold">
  55               <strong>When compiling with gcc, I get unreferenced symbols; for example
  56 the following:
  57 <pre class="programlisting">symbol __muldi3: referenced symbol not found
  58 symbol __cmpdi2: referenced symbol not found</pre></strong>
  59             </span>
  60             <p>Berkeley DB often uses 64-bit integral types on systems supporting large
  61 files, and gcc performs operations on those types by calling library
  62 functions.  These unreferenced symbol errors are usually caused by
  63 linking an application by calling "ld" rather than by calling "gcc":
  64 gcc will link in libgcc.a and will resolve the symbols.  If that does
  65 not help, another possible workaround is to reconfigure Berkeley DB using the
  66 <a class="link" href="build_unix_conf.html#build_unix_conf.--disable-largefile">--disable-largefile</a> configuration option and then rebuild.</p>
  67           </li>
  68           <li>
  69             <span class="bold">
  70               <strong>My C++ program traps during a failure in a DB call on my
  71 gcc-based system.</strong>
  72             </span>
  73             <p>We believe there are some severe bugs in the implementation of
  74 exceptions for some gcc compilers.  Exceptions require some interaction
  75 between compiler, assembler, and runtime libraries.  We're not sure
  76 exactly what is at fault, but one failing combination is gcc 2.7.2.3
  77 running on SuSE Linux 6.0.  The problem on this system can be seen with
  78 a rather simple test case of an exception thrown from a shared library
  79 and caught in the main program.</p>
  80             <p>A variation of this problem seems to occur on AIX, although we believe it
  81 does not necessarily involve shared libraries on that platform.</p>
  82             <p>If you see a trap that occurs when an exception might be thrown by the
  83 Berkeley DB runtime, we suggest that you use static libraries instead of
  84 shared libraries.  See the documentation for configuration.  If this
  85 doesn't work and you have a choice of compilers, try using a more recent
  86 gcc- or a non-gcc based compiler to build Berkeley DB.</p>
  87             <p>Finally, you can disable the use of exceptions in the C++ runtime for
  88 Berkeley DB by using the <a href="../api_reference/CXX/envcreate.html#env_DB_CXX_NO_EXCEPTIONS" class="olink">DB_CXX_NO_EXCEPTIONS</a> flag with the <a href="../api_reference/CXX/env.html" class="olink">DbEnv</a> or <a href="../api_reference/CXX/db.html" class="olink">Db</a> constructors.  When this flag is on, all C++ methods fail by returning an error code rather than throwing an exception.</p>
  89           </li>
  90           <li>
  91             <span class="bold">
  92               <strong>I get unexpected results and database corruption when running threaded programs.</strong>
  93             </span>
  94             <p>
  95               <span class="bold">
  96                 <strong>I get error messages that mutex (for example, pthread_mutex_XXX or mutex_XXX) functions are undefined when linking applications with Berkeley DB.</strong>
  97               </span>
  98             </p>
  99             <p>On some architectures, the Berkeley DB library uses the ISO POSIX standard pthreads and UNIX International (UI) threads interfaces for underlying mutex support; Solaris is an example.  You can specify compilers or compiler flags, or link with the appropriate thread library when loading your application to resolve the undefined references:</p>
 100             <pre class="programlisting">cc ... -lpthread ...
 101 cc ... -lthread ...
 102 xlc_r ...
 103 cc ... -mt ...</pre>
 104             <p>See the appropriate architecture-specific Reference Guide pages for more
 105 information.</p>
 106             <p>On systems where more than one type of mutex is available, it may be
 107 necessary for applications to use the same threads package from which
 108 Berkeley DB draws its mutexes.  For example, if Berkeley DB was built to use the
 109 POSIX pthreads mutex calls for mutex support, the application may need
 110 to be written to use the POSIX pthreads interfaces for its threading
 111 model.  This is only conjecture at this time, and although we know of
 112 no systems that actually have this requirement, it's not unlikely that
 113 some exist.</p>
 114             <p>In a few cases, Berkeley DB can be configured to use specific underlying mutex
 115 interfaces.  You can use the <a class="link" href="build_unix_conf.html#build_unix_conf.--enable-posixmutexes">--enable-posixmutexes</a> and
 116 <a class="link" href="build_unix_conf.html#build_unix_conf.--enable-uimutexes">--enable-uimutexes</a> configuration options to specify the POSIX and Unix
 117 International (UI) threads packages.  This should not, however, be
 118 necessary in most cases.</p>
 119             <p>In some cases, it is vitally important to make sure that you load the
 120 correct library.  For example, on Solaris systems, there are POSIX
 121 pthread interfaces in the C library, so applications can link Berkeley DB
 122 using only C library and not see any undefined symbols.  However, the
 123 C library POSIX pthread mutex support is insufficient for Berkeley DB, and
 124 Berkeley DB cannot detect that fact.  Similar errors can arise when
 125 applications (for example, tclsh) use dlopen to dynamically load Berkeley DB
 126 as a library.</p>
 127             <p>If you are seeing problems in this area after you confirm that you're
 128 linking with the correct libraries, there are two other things you can
 129 try.  First, if your platform supports interlibrary dependencies, we
 130 recommend that you change the Berkeley DB Makefile to specify the appropriate
 131 threads library when creating the Berkeley DB shared library, as an
 132 interlibrary dependency.  Second, if your application is using dlopen
 133 to dynamically load Berkeley DB, specify the appropriate thread library on
 134 the link line when you load the application itself.</p>
 135           </li>
 136           <li>
 137             <span class="bold">
 138               <strong>I get core dumps when running programs that fork children.</strong>
 139             </span>
 140             <p>Berkeley DB handles should not be shared across process forks, each forked
 141 child should acquire its own Berkeley DB handles.</p>
 142           </li>
 143           <li>
 144             <span class="bold">
 145               <strong>I get reports of uninitialized memory reads and writes when
 146 running software analysis tools (for example, Rational Software Corp.'s
 147 Purify tool).</strong>
 148             </span>
 149             <p>For performance reasons, Berkeley DB does not write the unused portions of
 150 database pages or fill in unused structure fields.  To turn off these
 151 errors when running software analysis tools, build with the
 152 <a class="link" href="build_unix_conf.html#build_unix_conf.--enable-umrw">--enable-umrw</a>
 153 configuration option.</p>
 154           </li>
 155           <li>
 156             <span class="bold">
 157               <strong>Berkeley DB programs or the test suite fail unexpectedly.</strong>
 158             </span>
 159             <p>The Berkeley DB architecture does not support placing the shared memory
 160 regions on remote filesystems -- for example, the Network File System
 161 (NFS) or the Andrew File System (AFS).  For this reason, the shared
 162 memory regions (normally located in the database home directory) must
 163 reside on a local filesystem.  See <a href="../programmer_reference/env_region.html" class="olink">Shared memory region</a> for more information.</p>
 164             <p>With respect to running the test suite, always check to make sure that
 165 TESTDIR is not on a remote mounted filesystem.</p>
 166           </li>
 167           <li>
 168             <span class="bold">
 169               <strong>The <a href="../api_reference/C/db_dump.html" class="olink">db_dump</a> utility fails to build.</strong>
 170             </span>
 171             <p>The <a href="../api_reference/C/db_dump.html" class="olink">db_dump185</a> utility is the utility that supports the conversion of Berkeley DB 1.85 and earlier databases to current database formats.  If the build errors look something like the following, it means the db.h include file being loaded is not a Berkeley DB 1.85 version include file:</p>
 172             <pre class="programlisting">db_dump185.c: In function `main':
 173 db_dump185.c:210: warning: assignment makes pointer from integer
 174 without a cast
 175 db_dump185.c:212: warning: assignment makes pointer from integer
 176 without a cast
 177 db_dump185.c:227: structure has no member named `seq'
 178 db_dump185.c:227: `R_NEXT' undeclared (first use in this function)</pre>
 179             <p>If the build errors look something like the following, it means that
 180 the Berkeley DB 1.85 code was not found in the standard libraries:</p>
 181             <pre class="programlisting">cc -o db_dump185 db_dump185.o
 182 ld:
 183 Unresolved:
 184 dbopen</pre>
 185             <p>To build the <a href="../api_reference/C/db_dump.html" class="olink">db_dump185</a> utility, the Berkeley DB version 1.85 code must already
 186 been built and available on the system.  If the Berkeley DB 1.85 header file
 187 is not found in a standard place, or if the library is not part of the
 188 standard libraries used for loading, you will need to edit your
 189 Makefile, and change the following lines:</p>
 190             <pre class="programlisting">DB185INC=
 191 DB185LIB=</pre>
 192             <p>So that the system Berkeley DB 1.85 header file and library are found; for
 193 example:</p>
 194             <pre class="programlisting">DB185INC=/usr/local/include
 195 DB185LIB=-ldb185</pre>
 196           </li>
 197         </ol>
 198       </div>
 199     </div>
 200     <div class="navfooter">
 201       <hr />
 202       <table width="100%" summary="Navigation footer">
 203         <tr>
 204           <td width="40%" align="left"><a accesskey="p" href="build_unix_test.html">Prev</a> </td>
 205           <td width="20%" align="center">
 206             <a accesskey="u" href="build_unix.html">Up</a>
 207           </td>
 208           <td width="40%" align="right"> <a accesskey="n" href="build_unix_aix.html">Next</a></td>
 209         </tr>
 210         <tr>
 211           <td width="40%" align="left" valign="top">Running the test suite under UNIX </td>
 212           <td width="20%" align="center">
 213             <a accesskey="h" href="index.html">Home</a>
 214           </td>
 215           <td width="40%" align="right" valign="top"> AIX</td>
 216         </tr>
 217       </table>
 218     </div>
 219   </body>
 220 </html>