DB_File Version 1.804 2nd June 2002 Copyright (c) 1995-2002 Paul Marquess. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. IMPORTANT NOTICE ================ If are using the locking technique described in older versions of DB_File, please read the section called "Locking: The Trouble with fd" in DB_File.pm immediately. The locking method has been found to be unsafe. You risk corrupting your data if you continue to use it. DESCRIPTION ----------- DB_File is a module which allows Perl programs to make use of the facilities provided by Berkeley DB version 1. (DB_File can be built version 2, 3 or 4 of Berkeley DB, but it will only support the 1.x features), If you want to make use of the new features available in Berkeley DB 2.x, 3.x or 4.x, use the Perl module BerkeleyDB instead. Berkeley DB is a C library which provides a consistent interface to a number of database formats. DB_File provides an interface to all three of the database types (hash, btree and recno) currently supported by Berkeley DB. For further details see the documentation included at the end of the file DB_File.pm. PREREQUISITES ------------- Before you can build DB_File you must have the following installed on your system: * Perl 5.004_05 or greater. * Berkeley DB. The official web site for Berkeley DB is http://www.sleepycat.com. The latest version of Berkeley DB is always available there. It is recommended that you use the most recent version available at the Sleepycat site. The one exception to this advice is where you want to use DB_File to access database files created by a third-party application, like Sendmail or Netscape. In these cases you must build DB_File with a compatible version of Berkeley DB. If you want to use Berkeley DB 2.x, you must have version 2.3.4 or greater. If you want to use Berkeley DB 3.x or 4.x, any version will do. For Berkeley DB 1.x, use either version 1.85 or 1.86. BUILDING THE MODULE ------------------- Assuming you have met all the prerequisites, building the module should be relatively straightforward. Step 1 : If you are running either Solaris 2.5 or HP-UX 10 and want to use Berkeley DB version 2, 3 or 4, read either the Solaris Notes or HP-UX Notes sections below. If you are running Linux please read the Linux Notes section before proceeding. Step 2 : Edit the file config.in to suit you local installation. Instructions are given in the file. Step 3 : Build and test the module using this sequence of commands: perl Makefile.PL make make test NOTE: If you have a very old version of Berkeley DB (i.e. pre 1.85), three of the tests in the recno test harness may fail (tests 51, 53 and 55). You can safely ignore the errors if you're never going to use the broken functionality (recno databases with a modified bval). Otherwise you'll have to upgrade your DB library. INSTALLATION ------------ make install TROUBLESHOOTING =============== Here are some of the common problems people encounter when building DB_File. Missing db.h or libdb.a ----------------------- If you get an error like this: cc -c -I/usr/local/include -Dbool=char -DHAS_BOOL -O2 -DVERSION=\"1.64\" -DXS_VERSION=\"1.64\" -fpic -I/usr/local/lib/perl5/i586-linux/5.00404/CORE -DmDB_Prefix_t=size_t -DmDB_Hash_t=u_int32_t DB_File.c DB_File.xs:101: db.h: No such file or directory or this: LD_RUN_PATH="/lib" cc -o blib/arch/auto/DB_File/DB_File.so -shared -L/usr/local/lib DB_File.o -L/usr/local/lib -ldb ld: cannot open -ldb: No such file or directory This symptom can imply: 1. You don't have Berkeley DB installed on your system at all. Solution: get & install Berkeley DB. 2. You do have Berkeley DB installed, but it isn't in a standard place. Solution: Edit config.in and set the LIB and INCLUDE variables to point to the directories where libdb.a and db.h are installed. Undefined symbol db_version --------------------------- DB_File seems to have built correctly, but you get an error like this when you run the test harness: $ make test PERL_DL_NONLAZY=1 /usr/bin/perl5.00404 -I./blib/arch -I./blib/lib -I/usr/local/lib/perl5/i586-linux/5.00404 -I/usr/local/lib/perl5 -e 'use Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t t/db-btree..........Can't load './blib/arch/auto/DB_File/DB_File.so' for module DB_File: ./blib/arch/auto/DB_File/DB_File.so: undefined symbol: db_version at /usr/local/lib/perl5/i586-linux/5.00404/DynaLoader.pm line 166. at t/db-btree.t line 21 BEGIN failed--compilation aborted at t/db-btree.t line 21. dubious Test returned status 2 (wstat 512, 0x200) This error usually happens when you have both version 1 and version 2 of Berkeley DB installed on your system and DB_File attempts to build using the db.h for Berkeley DB version 2 and the version 1 library. Unfortunately the two versions aren't compatible with each other. The undefined symbol error is actually caused because Berkeley DB version 1 doesn't have the symbol db_version. Solution: Setting the LIB & INCLUDE variables in config.in to point to the correct directories can sometimes be enough to fix this problem. If that doesn't work the easiest way to fix the problem is to either delete or temporarily rename the copies of db.h and libdb.a that you don't want DB_File to use. Incompatible versions of db.h and libdb --------------------------------------- BerkeleyDB seems to have built correctly, but you get an error like this when you run the test harness: $ make test PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00560 -Iblib/arch -Iblib/lib -I/home/paul/perl/install/5.005_60/lib/5.00560/i586-linux -I/home/paul/perl/install/5.005_60/lib/5.00560 -e 'use Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t t/db-btree.......... DB_File needs compatible versions of libdb & db.h you have db.h version 2.3.7 and libdb version 2.7.5 BEGIN failed--compilation aborted at t/db-btree.t line 21. ... Another variation on the theme of having two versions of Berkeley DB on your system. Solution: Setting the LIB & INCLUDE variables in config.in to point to the correct directories can sometimes be enough to fix this problem. If that doesn't work the easiest way to fix the problem is to either delete or temporarily rename the copies of db.h and libdb.a that you don't want BerkeleyDB to use. If you are running Linux, please read the Linux Notes section below. Linux Notes ----------- Newer versions of Linux (e.g. RedHat 6, SuSe 6) ship with a C library that has version 2.x of Berkeley DB linked into it. This makes it difficult to build this module with anything other than the version of Berkeley DB that shipped with your Linux release. If you do try to use a different version of Berkeley DB you will most likely get the error described in the "Incompatible versions of db.h and libdb" section of this file. To make matters worse, prior to Perl 5.6.1, the perl binary itself *always* included the Berkeley DB library. If you want to use a newer version of Berkeley DB with this module, the easiest solution is to use Perl 5.6.1 (or better) and Berkeley DB 3.x (or better). There are two approaches you can use to get older versions of Perl to work with specific versions of Berkeley DB. Both have their advantages and disadvantages. The first approach will only work when you want to build a version of Perl older than 5.6.1 along with Berkeley DB 3.x. If you want to use Berkeley DB 2.x, you must use the next approach. This approach involves rebuilding your existing version of Perl after applying an unofficial patch. The "patches" directory in the this module's source distribution contains a number of patch files. There is one patch file for every stable version of Perl since 5.004. Apply the appropriate patch to your Perl source tree before re-building and installing Perl from scratch. For example, assuming you are in the top-level source directory for Perl 5.6.0, the command below will apply the necessary patch. Remember to replace the path shown below with one that points to this module's patches directory. patch -p1 -N </path/to/DB_File/patches/5.6.0 Now rebuild & install perl. You should now have a perl binary that can be used to build this module. Follow the instructions in "BUILDING THE MODULE", remembering to set the INCLUDE and LIB variables in config.in. The second approach will work with both Berkeley DB 2.x and 3.x. Start by building Berkeley DB as a shared library. This is from the Berkeley DB build instructions: Building Shared Libraries for the GNU GCC compiler If you're using gcc and there's no better shared library example for your architecture, the following shared library build procedure will probably work. Add the -fpic option to the CFLAGS value in the Makefile. Rebuild all of your .o files. This will create a Berkeley DB library that contains .o files with PIC code. To build the shared library, then take the following steps in the library build directory: % mkdir tmp % cd tmp % ar xv ../libdb.a % gcc -shared -o libdb.so *.o % mv libdb.so .. % cd .. % rm -rf tmp Note, you may have to change the gcc line depending on the requirements of your system. The file libdb.so is your shared library Once you have built libdb.so, you will need to store it somewhere safe. cp libdb.so /usr/local/BerkeleyDB/lib If you now set the LD_PRELOAD environment variable to point to this shared library, Perl will use it instead of the version of Berkeley DB that shipped with your Linux distribution. export LD_PRELOAD=/usr/local/BerkeleyDB/lib/libdb.so Finally follow the instructions in "BUILDING THE MODULE" to build, test and install this module. Don't forget to set the INCLUDE and LIB variables in config.in. Remember, you will need to have the LD_PRELOAD variable set anytime you want to use Perl with Berkeley DB. Also note that if you have LD_PRELOAD permanently set it will affect ALL commands you execute. This may be a problem if you run any commands that access a database created by the version of Berkeley DB that shipped with your Linux distribution. Solaris Notes ------------- If you are running Solaris 2.5, and you get this error when you run the DB_File test harness: libc internal error: _rmutex_unlock: rmutex not held. you probably need to install a Sun patch. It has been reported that Sun patch 103187-25 (or later revisions) fixes this problem. To find out if you have the patch installed, the command "showrev -p" will display the patches that are currently installed on your system. HP-UX 10 Notes -------------- Some people running HP-UX 10 have reported getting an error like this when building DB_File with the native HP-UX compiler. ld: (Warning) At least one PA 2.0 object file (DB_File.o) was detected. The linked output may not run on a PA 1.x system. ld: Invalid loader fixup for symbol "$000000A5". If this is the case for you, Berkeley DB needs to be recompiled with the +z or +Z option and the resulting library placed in a .sl file. The following steps should do the trick: 1: Configure the Berkeley DB distribution with the +z or +Z C compiler flag: env "CFLAGS=+z" ../dist/configure ... 2: Edit the Berkeley DB Makefile and change: "libdb= libdb.a" to "libdb= libdb.sl". 3: Build and install the Berkeley DB distribution as usual. HP-UX 11 Notes -------------- Some people running the combination of HP-UX 11 and Berkeley DB 2.7.7 have reported getting this error when the run the test harness for DB_File ... lib/db-btree.........Can't call method "DELETE" on an undefined value at lib/db-btree.t line 216. FAILED at test 26 lib/db-hash..........Can't call method "DELETE" on an undefined value at lib/db-hash.t line 183. FAILED at test 22 ... The fix for this is to rebuild and install Berkeley DB with the bigfile option disabled. IRIX NOTES ---------- If you are running IRIX, and want to use Berkeley DB version 1, you can get it from http://reality.sgi.com/ariel. It has the patches necessary to compile properly on IRIX 5.3. FEEDBACK ======== How to report a problem with DB_File. When reporting any problem, I need the information requested below. 1. The *complete* output from running this perl -V Do not edit the output in any way. Note, I want you to run "perl -V" and NOT "perl -v". If your perl does not understand the "-V" option it is too old. DB_File needs Perl version 5.00405 or better. 2. The version of DB_File you have. If you have successfully installed DB_File, this one-liner will tell you: perl -e 'use DB_File; print qq{DB_File ver $DB_File::VERSION\n}' If you haven't installed DB_File then search DB_File.pm for a line like this: $VERSION = "1.20" ; 3. The version of Berkeley DB you are using. If you are using a version older than 1.85, think about upgrading. One point to note if you are considering upgrading Berkeley DB - the file formats for 1.85, 1.86, 2.0, 3.0 & 3.1 are all different. If you have successfully installed DB_File, this command will display the version of Berkeley DB it was built with: perl -e 'use DB_File; print qq{Berkeley DB ver $DB_File::db_ver\n}' 4. A copy the file config.in from the DB_File main source directory. 5. A listing of directories where Berkeley DB is installed. For example, if Berkeley DB is installed in /usr/BerkeleDB/lib and /usr/BerkeleyDB/include, I need the output from running this ls -l /usr/BerkeleyDB/lib ls -l /usr/BerkeleyDB/include 6. If you are having problems building DB_File, send me a complete log of what happened. Start by unpacking the DB_File module into a fresh directory and keep a log of all the steps [edit config.in, if necessary] perl Makefile.PL make make test TEST_VERBOSE=1 7. Now the difficult one. If you think you have found a bug in DB_File and you want me to fix it, you will *greatly* enhance the chances of me being able to track it down by sending me a small self-contained Perl script that illustrates the problem you are encountering. Include a summary of what you think the problem is and a log of what happens when you run the script, in case I can't reproduce your problem on my system. If possible, don't have the script dependent on an existing 20Meg database. If the script you send me can create the database itself then that is preferred. I realise that in some cases this is easier said than done, so if you can only reproduce the problem in your existing script, then you can post me that if you want. Just don't expect me to find your problem in a hurry, or at all. :-) CHANGES ------- See the Changes file. Paul Marquess <Paul.Marquess@btinternet.com>