README 16.3 KB
Newer Older
unknown's avatar
unknown committed
1 2
                                     DB_File

unknown's avatar
unknown committed
3
                                  Version 1.805
unknown's avatar
unknown committed
4

unknown's avatar
unknown committed
5
                                  1st Sep 2002
unknown's avatar
unknown committed
6

unknown's avatar
unknown committed
7
 	Copyright (c) 1995-2002 Paul Marquess. All rights reserved. This
unknown's avatar
unknown committed
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24
	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
unknown's avatar
unknown committed
25
version 2, 3 or 4 of Berkeley DB, but it will only support the 1.x
unknown's avatar
unknown committed
26 27 28
features),

If you want to make use of the new features available in Berkeley DB
unknown's avatar
unknown committed
29
2.x, 3.x or 4.x, use the Perl module BerkeleyDB instead.
unknown's avatar
unknown committed
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44

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:

unknown's avatar
unknown committed
45
    * Perl 5.004_05 or greater.
unknown's avatar
unknown committed
46 47 48 49 50 51 52 53 54 55 56 57 58 59

    * 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
unknown's avatar
unknown committed
60 61
      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.
unknown's avatar
unknown committed
62 63 64 65 66 67 68 69 70


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
unknown's avatar
unknown committed
71
         to use Berkeley DB version 2, 3 or 4, read either the Solaris Notes
unknown's avatar
unknown committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
         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.

unknown's avatar
unknown committed
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193

Undefined symbol dbopen
-----------------------

DB_File seems to have built correctly, but you get an error like this
when you run the test harness:

  ...
  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:
  dbopen at /usr/local/lib/perl5/5.6.1/i586-linux/DynaLoader.pm line 206.
   at t/db-btree.t line 23
  Compilation failed in require at t/db-btree.t line 23.
  ...

This error usually happens when you have both version 1 and a more recent
version of Berkeley DB installed on your system and DB_File attempts
to build using the db.h for Berkeley DB version 1 and the newer version
library. Unfortunately the two versions aren't compatible with each
other. The undefined symbol error is actually caused because versions
of Berkeley DB newer than version 1 doesn't have the symbol dbopen.

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.


unknown's avatar
unknown committed
194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329
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.


unknown's avatar
unknown committed
330 331
HP-UX 10 Notes
--------------
unknown's avatar
unknown committed
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355

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.

unknown's avatar
unknown committed
356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371
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.

unknown's avatar
unknown committed
372 373 374 375 376 377 378 379 380 381 382 383 384 385

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.

unknown's avatar
unknown committed
386 387 388
When reporting any problem, I need the information requested below. 

 1. The *complete* output from running this
unknown's avatar
unknown committed
389

unknown's avatar
unknown committed
390
        perl -V
unknown's avatar
unknown committed
391

unknown's avatar
unknown committed
392 393 394 395 396
    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.
unknown's avatar
unknown committed
397 398 399 400 401

 2. The version of DB_File you have.
    If you have successfully installed DB_File, this one-liner will
    tell you:

unknown's avatar
unknown committed
402
       perl -e 'use DB_File; print qq{DB_File ver $DB_File::VERSION\n}'
unknown's avatar
unknown committed
403 404 405 406 407 408 409 410 411 412 413 414 415 416

    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:

unknown's avatar
unknown committed
417 418 419 420 421 422 423 424 425 426 427 428 429 430
       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
unknown's avatar
unknown committed
431

unknown's avatar
unknown committed
432 433 434 435
        [edit config.in, if necessary]
        perl Makefile.PL
        make 
        make test TEST_VERBOSE=1
unknown's avatar
unknown committed
436

unknown's avatar
unknown committed
437
 7. Now the difficult one. If you think you have found a bug in DB_File
unknown's avatar
unknown committed
438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458
    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>