Debian Codegraph @

lang/perl/DB_File/README

raw
1 DB_File
2
3 Version 1.824
4
5 6th August 2011
6
7 Copyright (c) 1995-2011 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
12 IMPORTANT NOTICE
13 ================
14
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.
19
20 DESCRIPTION
21 -----------
22
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
26 features),
27
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.
30
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
34 Berkeley DB.
35
36 For further details see the documentation included at the end of the
37 file DB_File.pm.
38
39 PREREQUISITES
40 -------------
41
42 Before you can build DB_File you must have the following installed on
43 your 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
66 BUILDING THE MODULE
67 -------------------
68
69 Assuming you have met all the prerequisites, building the module should
70 be relatively straightforward.
71
72 Step 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
77 Step 2 : Edit the file config.in to suit you local installation.
78 Instructions are given in the file.
79
80 Step 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
96 INSTALLATION
97 ------------
98
99 make install
100
101 UPDATES
102 =======
103
104 The most recent version of DB_File is always available at
105
106 http://www.cpan.org/modules/by-module/DB_File/
107
108 TROUBLESHOOTING
109 ===============
110
111 Here are some of the common problems people encounter when building
112 DB_File.
113
114 Missing db.h or libdb.a
115 -----------------------
116
117 If 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
125 or 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
131 This 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
143 Undefined symbol db_version
144 ---------------------------
145
146 DB_File seems to have built correctly, but you get an error like this
147 when 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
162 This error usually happens when you have two version of Berkeley DB
163 installed on your system -- specifically, if you have both version 1 and
164 a newer version (i.e. version 2 or better) of Berkeley DB installed. If
165 DB_File is built using the db.h for the newer Berkeley DB and the version
166 1 Berkeley DB library you will trigger this error. Unfortunately the two
167 versions aren't compatible with each other. The undefined symbol error is
168 caused because Berkeley DB version 1 doesn't have the symbol db_version.
169
170 Solution: 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
177 Undefined symbol dbopen
178 -----------------------
179
180 DB_File seems to have built correctly, but you get an error like this
181 when 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
191 This error usually happens when you have both version 1 and a more recent
192 version of Berkeley DB installed on your system and DB_File attempts
193 to build using the db.h for Berkeley DB version 1 and the newer version
194 library. Unfortunately the two versions aren't compatible with each
195 other. The undefined symbol error is actually caused because versions
196 of Berkeley DB newer than version 1 doesn't have the symbol dbopen.
197
198 Solution: 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
205 Incompatible versions of db.h and libdb
206 ---------------------------------------
207
208 BerkeleyDB seems to have built correctly, but you get an error like this
209 when 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
222 Another variation on the theme of having two versions of Berkeley DB on
223 your system.
224
225 Solution: 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
234 Solaris build fails with "language optional software package not installed"
235 ---------------------------------------------------------------------------
236
237 If you are trying to build this module under Solaris and you get an
238 error message like this
239
240 /usr/ucb/cc: language optional software package not installed
241
242 it means that Perl cannot find the C compiler on your system. The cryptic
243 message is just Sun's way of telling you that you haven't bought their
244 C compiler.
245
246 When you build a Perl module that needs a C compiler, the Perl build
247 system tries to use the same C compiler that was used to build perl
248 itself. In this case your Perl binary was built with a C compiler that
249 lived in /usr/ucb.
250
251 To continue with building this module, you need to get a C compiler,
252 or tell Perl where your C compiler is, if you already have one.
253
254 Assuming you have now got a C compiler, what you do next will be dependant
255 on what C compiler you have installed. If you have just installed Sun's
256 C compiler, you shouldn't have to do anything. Just try rebuilding
257 this module.
258
259 If you have installed another C compiler, say gcc, you have to tell perl
260 how to use it instead of /usr/ucb/cc.
261
262 This set of options seems to work if you want to use gcc. Your mileage
263 may vary.
264
265 perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" "
266 make test
267
268 If that doesn't work for you, it's time to make changes to the Makefile
269 by hand. Good luck!
270
271
272
273 Solaris build fails with "gcc: unrecognized option `-KPIC'"
274 -----------------------------------------------------------
275
276 You are running Solaris and you get an error like this when you try to
277 build this Perl module
278
279 gcc: unrecognized option `-KPIC'
280
281 This symptom usually means that you are using a Perl binary that has been
282 built with the Sun C compiler, but you are using gcc to build this module.
283
284 When Perl builds modules that need a C compiler, it will attempt to use
285 the same C compiler and command line options that was used to build perl
286 itself. In this case "-KPIC" is a valid option for the Sun C compiler,
287 but not for gcc. The equivalent option for gcc is "-fPIC".
288
289 The 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
306 Linux Notes
307 -----------
308
309 Some older versions of Linux (e.g. RedHat 6, SuSe 6) ship with a C library
310 that has version 2.x of Berkeley DB linked into it. This makes it
311 difficult to build this module with anything other than the version of
312 Berkeley DB that shipped with your Linux release. If you do try to use
313 a different version of Berkeley DB you will most likely get the error
314 described in the "Incompatible versions of db.h and libdb" section of
315 this file.
316
317 To make matters worse, prior to Perl 5.6.1, the perl binary itself
318 *always* included the Berkeley DB library.
319
320 If you want to use a newer version of Berkeley DB with this module, the
321 easiest solution is to use Perl 5.6.1 (or better) and Berkeley DB 3.x
322 (or better).
323
324 There are two approaches you can use to get older versions of Perl to
325 work with specific versions of Berkeley DB. Both have their advantages
326 and disadvantages.
327
328 The first approach will only work when you want to build a version of
329 Perl older than 5.6.1 along with Berkeley DB 3.x. If you want to use
330 Berkeley DB 2.x, you must use the next approach. This approach involves
331 rebuilding your existing version of Perl after applying an unofficial
332 patch. The "patches" directory in the this module's source distribution
333 contains a number of patch files. There is one patch file for every
334 stable version of Perl since 5.004. Apply the appropriate patch to your
335 Perl source tree before re-building and installing Perl from scratch.
336 For example, assuming you are in the top-level source directory for
337 Perl 5.6.0, the command below will apply the necessary patch. Remember
338 to replace the path shown below with one that points to this module's
339 patches directory.
340
341 patch -p1 -N </path/to/DB_File/patches/5.6.0
342
343 Now rebuild & install perl. You should now have a perl binary that can
344 be used to build this module. Follow the instructions in "BUILDING THE
345 MODULE", remembering to set the INCLUDE and LIB variables in config.in.
346
347
348 The second approach will work with both Berkeley DB 2.x and 3.x.
349 Start by building Berkeley DB as a shared library. This is from
350 the 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
377 Once you have built libdb.so, you will need to store it somewhere safe.
378
379 cp libdb.so /usr/local/BerkeleyDB/lib
380
381 If you now set the LD_PRELOAD environment variable to point to this
382 shared library, Perl will use it instead of the version of Berkeley DB
383 that shipped with your Linux distribution.
384
385 export LD_PRELOAD=/usr/local/BerkeleyDB/lib/libdb.so
386
387 Finally follow the instructions in "BUILDING THE MODULE" to build,
388 test and install this module. Don't forget to set the INCLUDE and LIB
389 variables in config.in.
390
391 Remember, you will need to have the LD_PRELOAD variable set anytime you
392 want to use Perl with Berkeley DB. Also note that if you have LD_PRELOAD
393 permanently set it will affect ALL commands you execute. This may be a
394 problem if you run any commands that access a database created by the
395 version of Berkeley DB that shipped with your Linux distribution.
396
397
398 Solaris Notes
399 -------------
400
401 If you are running Solaris 2.5, and you get this error when you run the
402 DB_File test harness:
403
404 libc internal error: _rmutex_unlock: rmutex not held.
405
406 you probably need to install a Sun patch. It has been reported that
407 Sun patch 103187-25 (or later revisions) fixes this problem.
408
409 To find out if you have the patch installed, the command "showrev -p"
410 will display the patches that are currently installed on your system.
411
412
413 HP-UX 10 Notes
414 --------------
415
416 Some people running HP-UX 10 have reported getting an error like this
417 when 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
423 If this is the case for you, Berkeley DB needs to be recompiled with
424 the +z or +Z option and the resulting library placed in a .sl file. The
425 following 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
439 HP-UX 11 Notes
440 --------------
441
442 Some people running the combination of HP-UX 11 and Berkeley DB 2.7.7 have
443 reported 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
452 The fix for this is to rebuild and install Berkeley DB with the bigfile
453 option disabled.
454
455
456 AIX NOTES
457 ---------
458
459 I've had reports of a build failure like this on AIX 5.2 using the
460 xlC compiler.
461
462 rm -f blib/arch/auto/DB_File/DB_File.so
463 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
464 -L/usr/local/lib version.o DB_File.o -o blib/arch/auto/DB_File/DB_File.so
465 -L/usr/local/BerkeleyDB/lib -ldb -lpthread
466 ld: 0711-317 ERROR: Undefined symbol: .mutex_lock
467 ld: 0711-317 ERROR: Undefined symbol: .cond_signal
468 ld: 0711-317 ERROR: Undefined symbol: .mutex_unlock
469 ld: 0711-317 ERROR: Undefined symbol: .mutex_trylock
470 ld: 0711-317 ERROR: Undefined symbol: .cond_wait
471 ld: 0711-317 ERROR: Undefined symbol: .mutex_init
472 ld: 0711-317 ERROR: Undefined symbol: .cond_init
473 ld: 0711-317 ERROR: Undefined symbol: .mutex_destroy
474 ld: 0711-345 Use the -bloadmap or -bnoquiet option to obtain more information.
475 make: 1254-004 The error code from the last command is 8.
476
477 Editing Makefile.PL, and changing the line
478
479 $LIBS .= " -lpthread" if $^O eq 'aix' ;
480
481 to this
482
483 $LIBS .= " -lthread" if $^O eq 'aix' ;
484
485 fixed the problem.
486
487
488 FEEDBACK
489 ========
490
491 General feedback/questions/bug reports can be sent to me at [email protected].
492
493 Alternatively, if you have Usenet access, you can try the
494 comp.databases.berkeley-db or comp.lang.perl.modules groups.
495
496
497
498 How to report a problem with DB_File.
499 -------------------------------------
500
501 When reporting any problem, I need the information requested below.
502
503 1. The *complete* output from running this
504
505 perl -V
506
507 Do not edit the output in any way.
508 Note, I want you to run "perl -V" and NOT "perl -v".
509
510 If your perl does not understand the "-V" option it is too
511 old. DB_File needs Perl version 5.00405 or better.
512
513 2. The version of DB_File you have.
514 If you have successfully installed DB_File, this one-liner will
515 tell you:
516
517 perl -e 'use DB_File; print qq{DB_File ver $DB_File::VERSION\n}'
518
519 If you are running windows use this
520
521 perl -e "use DB_File; print qq{DB_File ver $DB_File::VERSION\n}"
522
523 If you haven't installed DB_File then search DB_File.pm for a line
524 like this:
525
526 $VERSION = "1.20" ;
527
528 3. The version of Berkeley DB used to build DB_File and the version
529 that is used at runtime. (These are usually the same)
530
531 If you are using a version older than 1.85, think about upgrading. One
532 point to note if you are considering upgrading Berkeley DB - the
533 file formats for 1.85, 1.86, 2.0, 3.0 & 3.1 are all different.
534
535 If you have successfully installed DB_File, these commands will display
536 the versions I need
537
538 perl -MDB_File -e 'print qq{Built with Berkeley DB ver $DB_File::db_ver\n}'
539 perl -MDB_File -e 'print qq{Running with Berkeley DB ver $DB_File::db_version\n}'
540
541 If you are running windows use this
542
543 perl -e "use DB_File; print qq{Built with Berkeley DB ver $DB_File::db_ver\n}"
544 perl -e "use DB_File; print qq{Running Berkeley DB ver $DB_File::db_version\n}"
545
546 4. A copy the file config.in from the DB_File main source directory.
547
548 5. A listing of directories where Berkeley DB is installed.
549 For example, if Berkeley DB is installed in /usr/BerkeleDB/lib and
550 /usr/BerkeleyDB/include, I need the output from running this
551
552 ls -l /usr/BerkeleyDB/lib
553 ls -l /usr/BerkeleyDB/include
554
555 6. If you are having problems building DB_File, send me a complete log
556 of what happened. Start by unpacking the DB_File module into a fresh
557 directory and keep a log of all the steps
558
559 [edit config.in, if necessary]
560 perl Makefile.PL
561 make
562 make test TEST_VERBOSE=1
563
564 7. Now the difficult one. If you think you have found a bug in DB_File
565 and you want me to fix it, you will *greatly* enhance the chances
566 of me being able to track it down by sending me a small
567 self-contained Perl script that illustrates the problem you are
568 encountering. Include a summary of what you think the problem is
569 and a log of what happens when you run the script, in case I can't
570 reproduce your problem on my system. If possible, don't have the
571 script dependent on an existing 20Meg database. If the script you
572 send me can create the database itself then that is preferred.
573
574 I realise that in some cases this is easier said than done, so if
575 you can only reproduce the problem in your existing script, then
576 you can post me that if you want. Just don't expect me to find your
577 problem in a hurry, or at all. :-)
578
579
580 CHANGES
581 -------
582
583 See the Changes file.
584
585 Paul Marquess <[email protected]>