1 DB_File 2 3 Version 1.817 4 5 27th March 2008 6 7 Copyright (c) 1995-2008 Paul Marquess. All rights reserved. This 8 program is free software; you can redistribute it and/or modify 9 it under the same terms as Perl itself. 10 11 12IMPORTANT NOTICE 13================ 14 15If are using the locking technique described in older versions of 16DB_File, please read the section called "Locking: The Trouble with fd" 17in DB_File.pm immediately. The locking method has been found to be 18unsafe. You risk corrupting your data if you continue to use it. 19 20DESCRIPTION 21----------- 22 23DB_File is a module which allows Perl programs to make use of the 24facilities provided by Berkeley DB version 1. (DB_File can be built 25version 2, 3 or 4 of Berkeley DB, but it will only support the 1.x 26features), 27 28If you want to make use of the new features available in Berkeley DB 292.x, 3.x or 4.x, use the Perl module BerkeleyDB instead. 30 31Berkeley DB is a C library which provides a consistent interface to a 32number of database formats. DB_File provides an interface to all three 33of the database types (hash, btree and recno) currently supported by 34Berkeley DB. 35 36For further details see the documentation included at the end of the 37file DB_File.pm. 38 39PREREQUISITES 40------------- 41 42Before you can build DB_File you must have the following installed on 43your system: 44 45 * Perl 5.004_05 or greater. 46 47 * Berkeley DB. 48 49 The official web site for Berkeley DB is 50 51 http://www.oracle.com/technology/products/berkeley-db/db/index.html 52 53 The latest version of Berkeley DB is always available there. It 54 is recommended that you use the most recent version available. 55 56 The one exception to this advice is where you want to use DB_File 57 to access database files created by a third-party application, like 58 Sendmail or Netscape. In these cases you must build DB_File with a 59 compatible version of Berkeley DB. 60 61 If you want to use Berkeley DB 2.x, you must have version 2.3.4 62 or greater. If you want to use Berkeley DB 3.x or 4.x, any version 63 will do. For Berkeley DB 1.x, use either version 1.85 or 1.86. 64 65 66BUILDING THE MODULE 67------------------- 68 69Assuming you have met all the prerequisites, building the module should 70be relatively straightforward. 71 72Step 1 : If you are running either Solaris 2.5 or HP-UX 10 and want 73 to use Berkeley DB version 2, 3 or 4, read either the Solaris Notes 74 or HP-UX Notes sections below. If you are running Linux please 75 read the Linux Notes section before proceeding. 76 77Step 2 : Edit the file config.in to suit you local installation. 78 Instructions are given in the file. 79 80Step 3 : Build and test the module using this sequence of commands: 81 82 perl Makefile.PL 83 make 84 make test 85 86 87 NOTE: 88 If you have a very old version of Berkeley DB (i.e. pre 1.85), 89 three of the tests in the recno test harness may fail (tests 51, 90 53 and 55). You can safely ignore the errors if you're never 91 going to use the broken functionality (recno databases with a 92 modified bval). Otherwise you'll have to upgrade your DB 93 library. 94 95 96INSTALLATION 97------------ 98 99 make install 100 101UPDATES 102======= 103 104The most recent version of DB_File is always available at 105 106 http://www.cpan.org/modules/by-module/DB_File/ 107 108TROUBLESHOOTING 109=============== 110 111Here are some of the common problems people encounter when building 112DB_File. 113 114Missing db.h or libdb.a 115----------------------- 116 117If you get an error like this: 118 119 cc -c -I/usr/local/include -Dbool=char -DHAS_BOOL 120 -O2 -DVERSION=\"1.64\" -DXS_VERSION=\"1.64\" -fpic 121 -I/usr/local/lib/perl5/i586-linux/5.00404/CORE -DmDB_Prefix_t=size_t 122 -DmDB_Hash_t=u_int32_t DB_File.c 123 DB_File.xs:101: db.h: No such file or directory 124 125or this: 126 127 LD_RUN_PATH="/lib" cc -o blib/arch/auto/DB_File/DB_File.so -shared 128 -L/usr/local/lib DB_File.o -L/usr/local/lib -ldb 129 ld: cannot open -ldb: No such file or directory 130 131This symptom can imply: 132 133 1. You don't have Berkeley DB installed on your system at all. 134 Solution: get & install Berkeley DB. 135 136 2. You do have Berkeley DB installed, but it isn't in a standard place. 137 Solution: Edit config.in and set the LIB and INCLUDE variables to point 138 to the directories where libdb.a and db.h are installed. 139 140 141 142 143Undefined symbol db_version 144--------------------------- 145 146DB_File seems to have built correctly, but you get an error like this 147when you run the test harness: 148 149 $ make test 150 PERL_DL_NONLAZY=1 /usr/bin/perl5.00404 -I./blib/arch -I./blib/lib 151 -I/usr/local/lib/perl5/i586-linux/5.00404 -I/usr/local/lib/perl5 -e 'use 152 Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t 153 t/db-btree..........Can't load './blib/arch/auto/DB_File/DB_File.so' for 154 module DB_File: ./blib/arch/auto/DB_File/DB_File.so: undefined symbol: 155 db_version at /usr/local/lib/perl5/i586-linux/5.00404/DynaLoader.pm 156 line 166. 157 158 at t/db-btree.t line 21 159 BEGIN failed--compilation aborted at t/db-btree.t line 21. 160 dubious Test returned status 2 (wstat 512, 0x200) 161 162This error usually happens when you have two version of Berkeley DB 163installed on your system -- specifically, if you have both version 1 and 164a newer version (i.e. version 2 or better) of Berkeley DB installed. If 165DB_File is built using the db.h for the newer Berkeley DB and the version 1661 Berkeley DB library you will trigger this error. Unfortunately the two 167versions aren't compatible with each other. The undefined symbol error is 168caused because Berkeley DB version 1 doesn't have the symbol db_version. 169 170Solution: Setting the LIB & INCLUDE variables in config.in to point to the 171 correct directories can sometimes be enough to fix this 172 problem. If that doesn't work the easiest way to fix the 173 problem is to either delete or temporarily rename the copies 174 of db.h and libdb.a that you don't want DB_File to use. 175 176 177Undefined symbol dbopen 178----------------------- 179 180DB_File seems to have built correctly, but you get an error like this 181when you run the test harness: 182 183 ... 184 t/db-btree..........Can't load 'blib/arch/auto/DB_File/DB_File.so' for 185 module DB_File: blib/arch/auto/DB_File/DB_File.so: undefined symbol: 186 dbopen at /usr/local/lib/perl5/5.6.1/i586-linux/DynaLoader.pm line 206. 187 at t/db-btree.t line 23 188 Compilation failed in require at t/db-btree.t line 23. 189 ... 190 191This error usually happens when you have both version 1 and a more recent 192version of Berkeley DB installed on your system and DB_File attempts 193to build using the db.h for Berkeley DB version 1 and the newer version 194library. Unfortunately the two versions aren't compatible with each 195other. The undefined symbol error is actually caused because versions 196of Berkeley DB newer than version 1 doesn't have the symbol dbopen. 197 198Solution: Setting the LIB & INCLUDE variables in config.in to point to the 199 correct directories can sometimes be enough to fix this 200 problem. If that doesn't work the easiest way to fix the 201 problem is to either delete or temporarily rename the copies 202 of db.h and libdb.a that you don't want DB_File to use. 203 204 205Incompatible versions of db.h and libdb 206--------------------------------------- 207 208BerkeleyDB seems to have built correctly, but you get an error like this 209when you run the test harness: 210 211 $ make test 212 PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00560 -Iblib/arch 213 -Iblib/lib -I/home/paul/perl/install/5.005_60/lib/5.00560/i586-linux 214 -I/home/paul/perl/install/5.005_60/lib/5.00560 -e 'use Test::Harness 215 qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t 216 t/db-btree.......... 217 DB_File was build with libdb version 2.3.7 218 but you are attempting to run it with libdb version 2.7.5 219 BEGIN failed--compilation aborted at t/db-btree.t line 21. 220 ... 221 222Another variation on the theme of having two versions of Berkeley DB on 223your system. 224 225Solution: Setting the LIB & INCLUDE variables in config.in to point to the 226 correct directories can sometimes be enough to fix this 227 problem. If that doesn't work the easiest way to fix the 228 problem is to either delete or temporarily rename the copies 229 of db.h and libdb.a that you don't want BerkeleyDB to use. 230 If you are running Linux, please read the Linux Notes section 231 below. 232 233 234Solaris build fails with "language optional software package not installed" 235--------------------------------------------------------------------------- 236 237If you are trying to build this module under Solaris and you get an 238error message like this 239 240 /usr/ucb/cc: language optional software package not installed 241 242it means that Perl cannot find the C compiler on your system. The cryptic 243message is just Sun's way of telling you that you haven't bought their 244C compiler. 245 246When you build a Perl module that needs a C compiler, the Perl build 247system tries to use the same C compiler that was used to build perl 248itself. In this case your Perl binary was built with a C compiler that 249lived in /usr/ucb. 250 251To continue with building this module, you need to get a C compiler, 252or tell Perl where your C compiler is, if you already have one. 253 254Assuming you have now got a C compiler, what you do next will be dependant 255on what C compiler you have installed. If you have just installed Sun's 256C compiler, you shouldn't have to do anything. Just try rebuilding 257this module. 258 259If you have installed another C compiler, say gcc, you have to tell perl 260how to use it instead of /usr/ucb/cc. 261 262This set of options seems to work if you want to use gcc. Your mileage 263may vary. 264 265 perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " 266 make test 267 268If that doesn't work for you, it's time to make changes to the Makefile 269by hand. Good luck! 270 271 272 273Solaris build fails with "gcc: unrecognized option `-KPIC'" 274----------------------------------------------------------- 275 276You are running Solaris and you get an error like this when you try to 277build this Perl module 278 279 gcc: unrecognized option `-KPIC' 280 281This symptom usually means that you are using a Perl binary that has been 282built with the Sun C compiler, but you are using gcc to build this module. 283 284When Perl builds modules that need a C compiler, it will attempt to use 285the same C compiler and command line options that was used to build perl 286itself. In this case "-KPIC" is a valid option for the Sun C compiler, 287but not for gcc. The equivalent option for gcc is "-fPIC". 288 289The solution is either: 290 291 1. Build both Perl and this module with the same C compiler, either 292 by using the Sun C compiler for both or gcc for both. 293 294 2. Try generating the Makefile for this module like this perl 295 296 perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc 297 make test 298 299 This second option seems to work when mixing a Perl binary built 300 with the Sun C compiler and this module built with gcc. Your 301 mileage may vary. 302 303 304 305 306Linux Notes 307----------- 308 309Some older versions of Linux (e.g. RedHat 6, SuSe 6) ship with a C library 310that has version 2.x of Berkeley DB linked into it. This makes it 311difficult to build this module with anything other than the version of 312Berkeley DB that shipped with your Linux release. If you do try to use 313a different version of Berkeley DB you will most likely get the error 314described in the "Incompatible versions of db.h and libdb" section of 315this file. 316 317To make matters worse, prior to Perl 5.6.1, the perl binary itself 318*always* included the Berkeley DB library. 319 320If you want to use a newer version of Berkeley DB with this module, the 321easiest solution is to use Perl 5.6.1 (or better) and Berkeley DB 3.x 322(or better). 323 324There are two approaches you can use to get older versions of Perl to 325work with specific versions of Berkeley DB. Both have their advantages 326and disadvantages. 327 328The first approach will only work when you want to build a version of 329Perl older than 5.6.1 along with Berkeley DB 3.x. If you want to use 330Berkeley DB 2.x, you must use the next approach. This approach involves 331rebuilding your existing version of Perl after applying an unofficial 332patch. The "patches" directory in the this module's source distribution 333contains a number of patch files. There is one patch file for every 334stable version of Perl since 5.004. Apply the appropriate patch to your 335Perl source tree before re-building and installing Perl from scratch. 336For example, assuming you are in the top-level source directory for 337Perl 5.6.0, the command below will apply the necessary patch. Remember 338to replace the path shown below with one that points to this module's 339patches directory. 340 341 patch -p1 -N </path/to/DB_File/patches/5.6.0 342 343Now rebuild & install perl. You should now have a perl binary that can 344be used to build this module. Follow the instructions in "BUILDING THE 345MODULE", remembering to set the INCLUDE and LIB variables in config.in. 346 347 348The second approach will work with both Berkeley DB 2.x and 3.x. 349Start by building Berkeley DB as a shared library. This is from 350the Berkeley DB build instructions: 351 352 Building Shared Libraries for the GNU GCC compiler 353 354 If you're using gcc and there's no better shared library example for 355 your architecture, the following shared library build procedure will 356 probably work. 357 358 Add the -fpic option to the CFLAGS value in the Makefile. 359 360 Rebuild all of your .o files. This will create a Berkeley DB library 361 that contains .o files with PIC code. To build the shared library, 362 then take the following steps in the library build directory: 363 364 % mkdir tmp 365 % cd tmp 366 % ar xv ../libdb.a 367 % gcc -shared -o libdb.so *.o 368 % mv libdb.so .. 369 % cd .. 370 % rm -rf tmp 371 372 Note, you may have to change the gcc line depending on the 373 requirements of your system. 374 375 The file libdb.so is your shared library 376 377Once you have built libdb.so, you will need to store it somewhere safe. 378 379 cp libdb.so /usr/local/BerkeleyDB/lib 380 381If you now set the LD_PRELOAD environment variable to point to this 382shared library, Perl will use it instead of the version of Berkeley DB 383that shipped with your Linux distribution. 384 385 export LD_PRELOAD=/usr/local/BerkeleyDB/lib/libdb.so 386 387Finally follow the instructions in "BUILDING THE MODULE" to build, 388test and install this module. Don't forget to set the INCLUDE and LIB 389variables in config.in. 390 391Remember, you will need to have the LD_PRELOAD variable set anytime you 392want to use Perl with Berkeley DB. Also note that if you have LD_PRELOAD 393permanently set it will affect ALL commands you execute. This may be a 394problem if you run any commands that access a database created by the 395version of Berkeley DB that shipped with your Linux distribution. 396 397 398Solaris Notes 399------------- 400 401If you are running Solaris 2.5, and you get this error when you run the 402DB_File test harness: 403 404 libc internal error: _rmutex_unlock: rmutex not held. 405 406you probably need to install a Sun patch. It has been reported that 407Sun patch 103187-25 (or later revisions) fixes this problem. 408 409To find out if you have the patch installed, the command "showrev -p" 410will display the patches that are currently installed on your system. 411 412 413HP-UX 10 Notes 414-------------- 415 416Some people running HP-UX 10 have reported getting an error like this 417when building DB_File with the native HP-UX compiler. 418 419 ld: (Warning) At least one PA 2.0 object file (DB_File.o) was detected. 420 The linked output may not run on a PA 1.x system. 421 ld: Invalid loader fixup for symbol "$000000A5". 422 423If this is the case for you, Berkeley DB needs to be recompiled with 424the +z or +Z option and the resulting library placed in a .sl file. The 425following steps should do the trick: 426 427 1: Configure the Berkeley DB distribution with the +z or +Z C compiler 428 flag: 429 430 env "CFLAGS=+z" ../dist/configure ... 431 432 2: Edit the Berkeley DB Makefile and change: 433 434 "libdb= libdb.a" to "libdb= libdb.sl". 435 436 437 3: Build and install the Berkeley DB distribution as usual. 438 439HP-UX 11 Notes 440-------------- 441 442Some people running the combination of HP-UX 11 and Berkeley DB 2.7.7 have 443reported getting this error when the run the test harness for DB_File 444 445 ... 446 lib/db-btree.........Can't call method "DELETE" on an undefined value at lib/db-btree.t line 216. 447 FAILED at test 26 448 lib/db-hash..........Can't call method "DELETE" on an undefined value at lib/db-hash.t line 183. 449 FAILED at test 22 450 ... 451 452The fix for this is to rebuild and install Berkeley DB with the bigfile 453option disabled. 454 455 456IRIX NOTES 457---------- 458 459If you are running IRIX, and want to use Berkeley DB version 1, you can 460get it from http://reality.sgi.com/ariel. It has the patches necessary 461to compile properly on IRIX 5.3. 462 463AIX NOTES 464--------- 465 466I've had reports of a build failure like this on AIX 5.2 using the 467xlC compiler. 468 469 rm -f blib/arch/auto/DB_File/DB_File.so 470 LD_RUN_PATH="" ld -bhalt:4 -bM:SRE -bI:/usr/local/5.8.1/lib/perl5/5.8.1/aix/CORE/perl.exp -bE:DB_File.exp -bnoentry -lc 471 -L/usr/local/lib version.o DB_File.o -o blib/arch/auto/DB_File/DB_File.so 472 -L/usr/local/BerkeleyDB/lib -ldb -lpthread 473 ld: 0711-317 ERROR: Undefined symbol: .mutex_lock 474 ld: 0711-317 ERROR: Undefined symbol: .cond_signal 475 ld: 0711-317 ERROR: Undefined symbol: .mutex_unlock 476 ld: 0711-317 ERROR: Undefined symbol: .mutex_trylock 477 ld: 0711-317 ERROR: Undefined symbol: .cond_wait 478 ld: 0711-317 ERROR: Undefined symbol: .mutex_init 479 ld: 0711-317 ERROR: Undefined symbol: .cond_init 480 ld: 0711-317 ERROR: Undefined symbol: .mutex_destroy 481 ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more information. 482 make: 1254-004 The error code from the last command is 8. 483 484Editing Makefile.PL, and changing the line 485 486 $LIBS .= " -lpthread" if $^O eq 'aix' ; 487 488to this 489 490 $LIBS .= " -lthread" if $^O eq 'aix' ; 491 492fixed the problem. 493 494 495FEEDBACK 496======== 497 498General feedback/questions/bug reports can be sent to me at pmqs@cpan.org. 499 500Alternatively, if you have Usenet access, you can try the 501comp.databases.berkeley-db or comp.lang.perl.modules groups. 502 503 504 505How to report a problem with DB_File. 506------------------------------------- 507 508When reporting any problem, I need the information requested below. 509 510 1. The *complete* output from running this 511 512 perl -V 513 514 Do not edit the output in any way. 515 Note, I want you to run "perl -V" and NOT "perl -v". 516 517 If your perl does not understand the "-V" option it is too 518 old. DB_File needs Perl version 5.00405 or better. 519 520 2. The version of DB_File you have. 521 If you have successfully installed DB_File, this one-liner will 522 tell you: 523 524 perl -e 'use DB_File; print qq{DB_File ver $DB_File::VERSION\n}' 525 526 If you are running windows use this 527 528 perl -e "use DB_File; print qq{DB_File ver $DB_File::VERSION\n}" 529 530 If you haven't installed DB_File then search DB_File.pm for a line 531 like this: 532 533 $VERSION = "1.20" ; 534 535 3. The version of Berkeley DB used to build DB_File and the version 536 that is used at runtime. (These are usually the same) 537 538 If you are using a version older than 1.85, think about upgrading. One 539 point to note if you are considering upgrading Berkeley DB - the 540 file formats for 1.85, 1.86, 2.0, 3.0 & 3.1 are all different. 541 542 If you have successfully installed DB_File, these commands will display 543 the versions I need 544 545 perl -MDB_File -e 'print qq{Built with Berkeley DB ver $DB_File::db_ver\n}' 546 perl -MDB_File -e 'print qq{Running with Berkeley DB ver $DB_File::db_version\n}' 547 548 If you are running windows use this 549 550 perl -e "use DB_File; print qq{Built with Berkeley DB ver $DB_File::db_ver\n}" 551 perl -e "use DB_File; print qq{Running Berkeley DB ver $DB_File::db_version\n}" 552 553 4. A copy the file config.in from the DB_File main source directory. 554 555 5. A listing of directories where Berkeley DB is installed. 556 For example, if Berkeley DB is installed in /usr/BerkeleDB/lib and 557 /usr/BerkeleyDB/include, I need the output from running this 558 559 ls -l /usr/BerkeleyDB/lib 560 ls -l /usr/BerkeleyDB/include 561 562 6. If you are having problems building DB_File, send me a complete log 563 of what happened. Start by unpacking the DB_File module into a fresh 564 directory and keep a log of all the steps 565 566 [edit config.in, if necessary] 567 perl Makefile.PL 568 make 569 make test TEST_VERBOSE=1 570 571 7. Now the difficult one. If you think you have found a bug in DB_File 572 and you want me to fix it, you will *greatly* enhance the chances 573 of me being able to track it down by sending me a small 574 self-contained Perl script that illustrates the problem you are 575 encountering. Include a summary of what you think the problem is 576 and a log of what happens when you run the script, in case I can't 577 reproduce your problem on my system. If possible, don't have the 578 script dependent on an existing 20Meg database. If the script you 579 send me can create the database itself then that is preferred. 580 581 I realise that in some cases this is easier said than done, so if 582 you can only reproduce the problem in your existing script, then 583 you can post me that if you want. Just don't expect me to find your 584 problem in a hurry, or at all. :-) 585 586 587CHANGES 588------- 589 590See the Changes file. 591 592Paul Marquess <pmqs@cpan.org> 593