7
Copyright (c) 1995-2002 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.
15
If are using the locking technique described in older versions of
16
DB_File, please read the section called "Locking: The Trouble with fd"
17
in DB_File.pm immediately. The locking method has been found to be
18
unsafe. You risk corrupting your data if you continue to use it.
23
DB_File is a module which allows Perl programs to make use of the
24
facilities provided by Berkeley DB version 1. (DB_File can be built
25
version 2, 3 or 4 of Berkeley DB, but it will only support the 1.x
28
If you want to make use of the new features available in Berkeley DB
29
2.x, 3.x or 4.x, use the Perl module BerkeleyDB instead.
31
Berkeley DB is a C library which provides a consistent interface to a
32
number of database formats. DB_File provides an interface to all three
33
of the database types (hash, btree and recno) currently supported by
36
For further details see the documentation included at the end of the
42
Before you can build DB_File you must have the following installed on
45
* Perl 5.004_05 or greater.
49
The official web site for Berkeley DB is http://www.sleepycat.com.
50
The latest version of Berkeley DB is always available there. It
51
is recommended that you use the most recent version available at
54
The one exception to this advice is where you want to use DB_File
55
to access database files created by a third-party application, like
56
Sendmail or Netscape. In these cases you must build DB_File with a
57
compatible version of Berkeley DB.
59
If you want to use Berkeley DB 2.x, you must have version 2.3.4
60
or greater. If you want to use Berkeley DB 3.x or 4.x, any version
61
will do. For Berkeley DB 1.x, use either version 1.85 or 1.86.
67
Assuming you have met all the prerequisites, building the module should
68
be relatively straightforward.
70
Step 1 : If you are running either Solaris 2.5 or HP-UX 10 and want
71
to use Berkeley DB version 2, 3 or 4, read either the Solaris Notes
72
or HP-UX Notes sections below. If you are running Linux please
73
read the Linux Notes section before proceeding.
75
Step 2 : Edit the file config.in to suit you local installation.
76
Instructions are given in the file.
78
Step 3 : Build and test the module using this sequence of commands:
86
If you have a very old version of Berkeley DB (i.e. pre 1.85),
87
three of the tests in the recno test harness may fail (tests 51,
88
53 and 55). You can safely ignore the errors if you're never
89
going to use the broken functionality (recno databases with a
90
modified bval). Otherwise you'll have to upgrade your DB
103
Here are some of the common problems people encounter when building
106
Missing db.h or libdb.a
107
-----------------------
109
If you get an error like this:
111
cc -c -I/usr/local/include -Dbool=char -DHAS_BOOL
112
-O2 -DVERSION=\"1.64\" -DXS_VERSION=\"1.64\" -fpic
113
-I/usr/local/lib/perl5/i586-linux/5.00404/CORE -DmDB_Prefix_t=size_t
114
-DmDB_Hash_t=u_int32_t DB_File.c
115
DB_File.xs:101: db.h: No such file or directory
119
LD_RUN_PATH="/lib" cc -o blib/arch/auto/DB_File/DB_File.so -shared
120
-L/usr/local/lib DB_File.o -L/usr/local/lib -ldb
121
ld: cannot open -ldb: No such file or directory
123
This symptom can imply:
125
1. You don't have Berkeley DB installed on your system at all.
126
Solution: get & install Berkeley DB.
128
2. You do have Berkeley DB installed, but it isn't in a standard place.
129
Solution: Edit config.in and set the LIB and INCLUDE variables to point
130
to the directories where libdb.a and db.h are installed.
133
Undefined symbol db_version
134
---------------------------
136
DB_File seems to have built correctly, but you get an error like this
137
when you run the test harness:
140
PERL_DL_NONLAZY=1 /usr/bin/perl5.00404 -I./blib/arch -I./blib/lib
141
-I/usr/local/lib/perl5/i586-linux/5.00404 -I/usr/local/lib/perl5 -e 'use
142
Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
143
t/db-btree..........Can't load './blib/arch/auto/DB_File/DB_File.so' for
144
module DB_File: ./blib/arch/auto/DB_File/DB_File.so: undefined symbol:
145
db_version at /usr/local/lib/perl5/i586-linux/5.00404/DynaLoader.pm
148
at t/db-btree.t line 21
149
BEGIN failed--compilation aborted at t/db-btree.t line 21.
150
dubious Test returned status 2 (wstat 512, 0x200)
152
This error usually happens when you have both version 1 and version
153
2 of Berkeley DB installed on your system and DB_File attempts to
154
build using the db.h for Berkeley DB version 2 and the version 1
155
library. Unfortunately the two versions aren't compatible with each
156
other. The undefined symbol error is actually caused because Berkeley
157
DB version 1 doesn't have the symbol db_version.
159
Solution: Setting the LIB & INCLUDE variables in config.in to point to the
160
correct directories can sometimes be enough to fix this
161
problem. If that doesn't work the easiest way to fix the
162
problem is to either delete or temporarily rename the copies
163
of db.h and libdb.a that you don't want DB_File to use.
166
Undefined symbol dbopen
167
-----------------------
169
DB_File seems to have built correctly, but you get an error like this
170
when you run the test harness:
173
t/db-btree..........Can't load 'blib/arch/auto/DB_File/DB_File.so' for
174
module DB_File: blib/arch/auto/DB_File/DB_File.so: undefined symbol:
175
dbopen at /usr/local/lib/perl5/5.6.1/i586-linux/DynaLoader.pm line 206.
176
at t/db-btree.t line 23
177
Compilation failed in require at t/db-btree.t line 23.
180
This error usually happens when you have both version 1 and a more recent
181
version of Berkeley DB installed on your system and DB_File attempts
182
to build using the db.h for Berkeley DB version 1 and the newer version
183
library. Unfortunately the two versions aren't compatible with each
184
other. The undefined symbol error is actually caused because versions
185
of Berkeley DB newer than version 1 doesn't have the symbol dbopen.
187
Solution: Setting the LIB & INCLUDE variables in config.in to point to the
188
correct directories can sometimes be enough to fix this
189
problem. If that doesn't work the easiest way to fix the
190
problem is to either delete or temporarily rename the copies
191
of db.h and libdb.a that you don't want DB_File to use.
194
Incompatible versions of db.h and libdb
195
---------------------------------------
197
BerkeleyDB seems to have built correctly, but you get an error like this
198
when you run the test harness:
201
PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00560 -Iblib/arch
202
-Iblib/lib -I/home/paul/perl/install/5.005_60/lib/5.00560/i586-linux
203
-I/home/paul/perl/install/5.005_60/lib/5.00560 -e 'use Test::Harness
204
qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
206
DB_File needs compatible versions of libdb & db.h
207
you have db.h version 2.3.7 and libdb version 2.7.5
208
BEGIN failed--compilation aborted at t/db-btree.t line 21.
211
Another variation on the theme of having two versions of Berkeley DB on
214
Solution: Setting the LIB & INCLUDE variables in config.in to point to the
215
correct directories can sometimes be enough to fix this
216
problem. If that doesn't work the easiest way to fix the
217
problem is to either delete or temporarily rename the copies
218
of db.h and libdb.a that you don't want BerkeleyDB to use.
219
If you are running Linux, please read the Linux Notes section
226
Newer versions of Linux (e.g. RedHat 6, SuSe 6) ship with a C library
227
that has version 2.x of Berkeley DB linked into it. This makes it
228
difficult to build this module with anything other than the version of
229
Berkeley DB that shipped with your Linux release. If you do try to use
230
a different version of Berkeley DB you will most likely get the error
231
described in the "Incompatible versions of db.h and libdb" section of
234
To make matters worse, prior to Perl 5.6.1, the perl binary itself
235
*always* included the Berkeley DB library.
237
If you want to use a newer version of Berkeley DB with this module, the
238
easiest solution is to use Perl 5.6.1 (or better) and Berkeley DB 3.x
241
There are two approaches you can use to get older versions of Perl to
242
work with specific versions of Berkeley DB. Both have their advantages
245
The first approach will only work when you want to build a version of
246
Perl older than 5.6.1 along with Berkeley DB 3.x. If you want to use
247
Berkeley DB 2.x, you must use the next approach. This approach involves
248
rebuilding your existing version of Perl after applying an unofficial
249
patch. The "patches" directory in the this module's source distribution
250
contains a number of patch files. There is one patch file for every
251
stable version of Perl since 5.004. Apply the appropriate patch to your
252
Perl source tree before re-building and installing Perl from scratch.
253
For example, assuming you are in the top-level source directory for
254
Perl 5.6.0, the command below will apply the necessary patch. Remember
255
to replace the path shown below with one that points to this module's
258
patch -p1 -N </path/to/DB_File/patches/5.6.0
260
Now rebuild & install perl. You should now have a perl binary that can
261
be used to build this module. Follow the instructions in "BUILDING THE
262
MODULE", remembering to set the INCLUDE and LIB variables in config.in.
265
The second approach will work with both Berkeley DB 2.x and 3.x.
266
Start by building Berkeley DB as a shared library. This is from
267
the Berkeley DB build instructions:
269
Building Shared Libraries for the GNU GCC compiler
271
If you're using gcc and there's no better shared library example for
272
your architecture, the following shared library build procedure will
275
Add the -fpic option to the CFLAGS value in the Makefile.
277
Rebuild all of your .o files. This will create a Berkeley DB library
278
that contains .o files with PIC code. To build the shared library,
279
then take the following steps in the library build directory:
284
% gcc -shared -o libdb.so *.o
289
Note, you may have to change the gcc line depending on the
290
requirements of your system.
292
The file libdb.so is your shared library
294
Once you have built libdb.so, you will need to store it somewhere safe.
296
cp libdb.so /usr/local/BerkeleyDB/lib
298
If you now set the LD_PRELOAD environment variable to point to this
299
shared library, Perl will use it instead of the version of Berkeley DB
300
that shipped with your Linux distribution.
302
export LD_PRELOAD=/usr/local/BerkeleyDB/lib/libdb.so
304
Finally follow the instructions in "BUILDING THE MODULE" to build,
305
test and install this module. Don't forget to set the INCLUDE and LIB
306
variables in config.in.
308
Remember, you will need to have the LD_PRELOAD variable set anytime you
309
want to use Perl with Berkeley DB. Also note that if you have LD_PRELOAD
310
permanently set it will affect ALL commands you execute. This may be a
311
problem if you run any commands that access a database created by the
312
version of Berkeley DB that shipped with your Linux distribution.
318
If you are running Solaris 2.5, and you get this error when you run the
319
DB_File test harness:
321
libc internal error: _rmutex_unlock: rmutex not held.
323
you probably need to install a Sun patch. It has been reported that
324
Sun patch 103187-25 (or later revisions) fixes this problem.
326
To find out if you have the patch installed, the command "showrev -p"
327
will display the patches that are currently installed on your system.
333
Some people running HP-UX 10 have reported getting an error like this
334
when building DB_File with the native HP-UX compiler.
336
ld: (Warning) At least one PA 2.0 object file (DB_File.o) was detected.
337
The linked output may not run on a PA 1.x system.
338
ld: Invalid loader fixup for symbol "$000000A5".
340
If this is the case for you, Berkeley DB needs to be recompiled with
341
the +z or +Z option and the resulting library placed in a .sl file. The
342
following steps should do the trick:
344
1: Configure the Berkeley DB distribution with the +z or +Z C compiler
347
env "CFLAGS=+z" ../dist/configure ...
349
2: Edit the Berkeley DB Makefile and change:
351
"libdb= libdb.a" to "libdb= libdb.sl".
354
3: Build and install the Berkeley DB distribution as usual.
359
Some people running the combination of HP-UX 11 and Berkeley DB 2.7.7 have
360
reported getting this error when the run the test harness for DB_File
363
lib/db-btree.........Can't call method "DELETE" on an undefined value at lib/db-btree.t line 216.
365
lib/db-hash..........Can't call method "DELETE" on an undefined value at lib/db-hash.t line 183.
369
The fix for this is to rebuild and install Berkeley DB with the bigfile
376
If you are running IRIX, and want to use Berkeley DB version 1, you can
377
get it from http://reality.sgi.com/ariel. It has the patches necessary
378
to compile properly on IRIX 5.3.
384
How to report a problem with DB_File.
386
When reporting any problem, I need the information requested below.
388
1. The *complete* output from running this
392
Do not edit the output in any way.
393
Note, I want you to run "perl -V" and NOT "perl -v".
395
If your perl does not understand the "-V" option it is too
396
old. DB_File needs Perl version 5.00405 or better.
398
2. The version of DB_File you have.
399
If you have successfully installed DB_File, this one-liner will
402
perl -e 'use DB_File; print qq{DB_File ver $DB_File::VERSION\n}'
404
If you haven't installed DB_File then search DB_File.pm for a line
409
3. The version of Berkeley DB you are using.
410
If you are using a version older than 1.85, think about upgrading. One
411
point to note if you are considering upgrading Berkeley DB - the
412
file formats for 1.85, 1.86, 2.0, 3.0 & 3.1 are all different.
414
If you have successfully installed DB_File, this command will display
415
the version of Berkeley DB it was built with:
417
perl -e 'use DB_File; print qq{Berkeley DB ver $DB_File::db_ver\n}'
419
4. A copy the file config.in from the DB_File main source directory.
421
5. A listing of directories where Berkeley DB is installed.
422
For example, if Berkeley DB is installed in /usr/BerkeleDB/lib and
423
/usr/BerkeleyDB/include, I need the output from running this
425
ls -l /usr/BerkeleyDB/lib
426
ls -l /usr/BerkeleyDB/include
428
6. If you are having problems building DB_File, send me a complete log
429
of what happened. Start by unpacking the DB_File module into a fresh
430
directory and keep a log of all the steps
432
[edit config.in, if necessary]
435
make test TEST_VERBOSE=1
437
7. Now the difficult one. If you think you have found a bug in DB_File
438
and you want me to fix it, you will *greatly* enhance the chances
439
of me being able to track it down by sending me a small
440
self-contained Perl script that illustrates the problem you are
441
encountering. Include a summary of what you think the problem is
442
and a log of what happens when you run the script, in case I can't
443
reproduce your problem on my system. If possible, don't have the
444
script dependent on an existing 20Meg database. If the script you
445
send me can create the database itself then that is preferred.
447
I realise that in some cases this is easier said than done, so if
448
you can only reproduce the problem in your existing script, then
449
you can post me that if you want. Just don't expect me to find your
450
problem in a hurry, or at all. :-)
456
See the Changes file.
458
Paul Marquess <Paul.Marquess@btinternet.com>
added
removed
libdb/perl/DB_File/README
