"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "mysql-4.0.27/bdb/perl.BerkeleyDB/README" of archive mysql-4.0.27-win-src.zip:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 BerkeleyDB
2
3 Version 0.13
4
5 15th Jan 2001
6
7 Copyright (c) 1997-2001 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 DESCRIPTION
13 -----------
14
15 BerkeleyDB is a module which allows Perl programs to make use of the
16 facilities provided by Berkeley DB version 2 or 3. (Note: if you want
17 to use version 1 of Berkeley DB with Perl you need the DB_File module).
18
19 Berkeley DB is a C library which provides a consistent interface to a
20 number of database formats. BerkeleyDB provides an interface to all
21 four of the database types (hash, btree, queue and recno) currently
22 supported by Berkeley DB.
23
24 For further details see the documentation in the file BerkeleyDB.pod.
25
26 PREREQUISITES
27 -------------
28
29 Before you can build BerkeleyDB you need to have the following
30 installed on your system:
31
32 * Perl 5.004_04 or greater.
33
34 * Berkeley DB Version 2.6.4 or greater
35
36 The official web site for Berkeley DB is http://www.sleepycat.com
37
38 The latest version of Berkeley DB is always available there. It
39 is recommended that you use the most recent version available at
40 the Sleepycat site.
41
42 The one exception to this advice is where you want to use BerkeleyDB
43 to access database files created by a third-party application,
44 like Sendmail. In these cases you must build BerkeleyDB with a
45 compatible version of Berkeley DB.
46
47
48 BUILDING THE MODULE
49 -------------------
50
51 Assuming you have met all the prerequisites, building the module should
52 be relatively straightforward.
53
54 Step 1 : If you are running Solaris 2.5, 2.7 or HP-UX 10 read either
55 the Solaris Notes or HP-UX Notes sections below.
56 If you are running Linux please read the Linux Notes section
57 before proceeding.
58
59
60 Step 2 : Edit the file config.in to suit you local installation.
61 Instructions are given in the file.
62
63 Step 3 : Build and test the module using this sequence of commands:
64
65 perl Makefile.PL
66 make
67 make test
68
69 INSTALLATION
70 ------------
71
72 make install
73
74 TROUBLESHOOTING
75 ===============
76
77 Here are some of the problems that people encounter when building BerkeleyDB.
78
79 Missing db.h or libdb.a
80 -----------------------
81
82 If you get an error like this:
83
84 cc -c -I./libraries/ -Dbool=char -DHAS_BOOL -I/usr/local/include -O2
85 -DVERSION=\"0.07\" -DXS_VERSION=\"0.07\" -fpic
86 -I/usr/local/lib/perl5/5.00503/i586-linux/CORE BerkeleyDB.c
87 BerkeleyDB.xs:52: db.h: No such file or directory
88
89 or this:
90
91 cc -c -I./libraries/2.7.5 -Dbool=char -DHAS_BOOL -I/usr/local/include -O2
92 -DVERSION=\"0.07\" -DXS_VERSION=\"0.07\" -fpic
93 -I/usr/local/lib/perl5/5.00503/i586-linux/CORE BerkeleyDB.c
94 LD_RUN_PATH="/lib" cc -o blib/arch/auto/BerkeleyDB/BerkeleyDB.so -shared
95 -L/usr/local/lib BerkeleyDB.o
96 -L/home/paul/perl/ext/BerkDB/BerkeleyDB/libraries -ldb
97 ld: cannot open -ldb: No such file or directory
98
99 This symptom can imply:
100
101 1. You don't have Berkeley DB installed on your system at all.
102 Solution: get & install Berkeley DB.
103
104 2. You do have Berkeley DB installed, but it isn't in a standard place.
105 Solution: Edit config.in and set the LIB and INCLUDE variables to point
106 to the directories where libdb.a and db.h are installed.
107
108 Wrong db.h
109 ----------
110
111 If you get an error like this when building this module:
112
113 cc -c -I./libraries/ -Dbool=char -DHAS_BOOL -I/usr/local/include -O2
114 -DVERSION=\"0.07\" -DXS_VERSION=\"0.07\" -fpic
115 -I/usr/local/lib/perl5/5.00503/i586-linux/CORE BerkeleyDB.c
116 BerkeleyDB.xs:93: parse error before `DB_INFO'
117 BerkeleyDB.xs:93: warning: no semicolon at end of struct or union
118 BerkeleyDB.xs:94: warning: data definition has no type or storage class
119 BerkeleyDB.xs:95: parse error before `0x80000000'
120 BerkeleyDB.xs:110: parse error before `}'
121 BerkeleyDB.xs:110: warning: data definition has no type or storage class
122 BerkeleyDB.xs:117: parse error before `DB_ENV'
123 ...
124
125 This error usually happens when if you only have Berkeley DB version 1
126 on your system or you have both version 1 and version 2 (or 3) of Berkeley
127 DB installed on your system. When building BerkeleyDB it attempts
128 to use the db.h for Berkeley DB version 1. This perl module can only
129 be built with Berkeley DB version 2 or 3.
130
131 This symptom can imply:
132
133 1. You don't have Berkeley DB version 2 or 3 installed on your system
134 at all.
135 Solution: get & install Berkeley DB.
136
137 2. You do have Berkeley DB 2 or 3 installed, but it isn't in a standard
138 place.
139 Solution: Edit config.in and set the LIB and INCLUDE variables
140 to point to the directories where libdb.a and db.h are
141 installed.
142
143 Undefined Symbol: txn_stat
144 --------------------------
145
146 BerkeleyDB 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 /home/paul/perl/install/bin/perl5.00503
151 -Iblib/arch -Iblib/lib -I/usr/local/lib/perl5/5.00503/i586-linux
152 -I/usr/local/lib/perl5/5.00503 -e 'use Test::Harness qw(&runtests $verbose);
153 $verbose=0; runtests @ARGV;' t/*.t
154 t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for
155 module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so:
156 undefined symbol: txn_stat
157 at /usr/local/lib/perl5/5.00503/i586-linux/DynaLoader.pm line 169.
158 ...
159
160 This error usually happens when you have both version 1 and version
161 2 (or 3) of Berkeley DB installed on your system and BerkeleyDB attempts
162 to build using the db.h for Berkeley DB version 2/3 and the version 1
163 library. Unfortunately the two versions aren't compatible with each
164 other. BerkeleyDB can only be built with Berkeley DB version 2 or 3.
165
166 Solution: Setting the LIB & INCLUDE variables in config.in to point to the
167 correct directories can sometimes be enough to fix this
168 problem. If that doesn't work the easiest way to fix the
169 problem is to either delete or temporarily rename the copies
170 of db.h and libdb.a that you don't want BerkeleyDB to use.
171
172 Undefined Symbol: db_appinit
173 ----------------------------
174
175 BerkeleyDB seems to have built correctly, but you get an error like this
176 when you run the test harness:
177
178 $ make test
179 PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00561 -Iblib/arch
180 -Iblib/lib -I/home/paul/perl/install/5.005_61/lib/5.00561/i586-linux
181 -I/home/paul/perl/install/5.005_61/lib/5.00561 -e 'use Test::Harness
182 qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
183 t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for
184 module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so:
185 undefined symbol: db_appinit
186 at /home/paul/perl/install/5.005_61/lib/5.00561/i586-linux/DynaLoader.pm
187 ...
188
189
190 This error usually happens when you have both version 2 and version
191 3 of Berkeley DB installed on your system and BerkeleyDB attempts
192 to build using the db.h for Berkeley DB version 2 and the version 3
193 library. Unfortunately the two versions aren't compatible with each
194 other.
195
196 Solution: Setting the LIB & INCLUDE variables in config.in to point to the
197 correct directories can sometimes be enough to fix this
198 problem. If that doesn't work the easiest way to fix the
199 problem is to either delete or temporarily rename the copies
200 of db.h and libdb.a that you don't want BerkeleyDB to use.
201
202 Undefined Symbol: db_create
203 ---------------------------
204
205 BerkeleyDB seems to have built correctly, but you get an error like this
206 when you run the test harness:
207
208 $ make test
209 PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00561 -Iblib/arch
210 -Iblib/lib -I/home/paul/perl/install/5.005_61/lib/5.00561/i586-linux
211 -I/home/paul/perl/install/5.005_61/lib/5.00561 -e 'use Test::Harness
212 qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
213 t/btree.............Can't load 'blib/arch/auto/BerkeleyDB/BerkeleyDB.so' for
214 module BerkeleyDB: blib/arch/auto/BerkeleyDB/BerkeleyDB.so:
215 undefined symbol: db_create
216 at /home/paul/perl/install/5.005_61/lib/5.00561/i586-linux/DynaLoader.pm
217 ...
218
219 This error usually happens when you have both version 2 and version
220 3 of Berkeley DB installed on your system and BerkeleyDB attempts
221 to build using the db.h for Berkeley DB version 3 and the version 2
222 library. Unfortunately the two versions aren't compatible with each
223 other.
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
231
232 Incompatible versions of db.h and libdb
233 ---------------------------------------
234
235 BerkeleyDB seems to have built correctly, but you get an error like this
236 when you run the test harness:
237
238 $ make test
239 PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00503
240 -Iblib/arch -Iblib/lib -I/usr/local/lib/perl5/5.00503/i586-linux
241 -I/usr/local/lib/perl5/5.00503 -e 'use Test::Harness qw(&runtests $verbose);
242 $verbose=0; runtests @ARGV;' t/*.t
243 t/btree.............
244 BerkeleyDB needs compatible versions of libdb & db.h
245 you have db.h version 2.6.4 and libdb version 2.7.5
246 BEGIN failed--compilation aborted at t/btree.t line 25.
247 dubious
248 Test returned status 255 (wstat 65280, 0xff00)
249 ...
250
251 Another variation on the theme of having two versions of Berkeley DB on
252 your system.
253
254 Solution: Setting the LIB & INCLUDE variables in config.in to point to the
255 correct directories can sometimes be enough to fix this
256 problem. If that doesn't work the easiest way to fix the
257 problem is to either delete or temporarily rename the copies
258 of db.h and libdb.a that you don't want BerkeleyDB to use.
259 If you are running Linux, please read the Linux Notes section below.
260
261
262 Linux Notes
263 -----------
264
265 Newer versions of Linux (e.g. RedHat 6, SuSe 6) ship with a C library
266 that has version 2.x of Berkeley DB linked into it. This makes it
267 difficult to build this module with anything other than the version of
268 Berkeley DB that shipped with your Linux release. If you do try to use
269 a different version of Berkeley DB you will most likely get the error
270 described in the "Incompatible versions of db.h and libdb" section of
271 this file.
272
273 To make matters worse, prior to Perl 5.6.1, the perl binary itself
274 *always* included the Berkeley DB library.
275
276 If you want to use a newer version of Berkeley DB with this module, the
277 easiest solution is to use Perl 5.6.1 (or better) and Berkeley DB 3.x
278 (or better).
279
280 There are two approaches you can use to get older versions of Perl to
281 work with specific versions of Berkeley DB. Both have their advantages
282 and disadvantages.
283
284 The first approach will only work when you want to build a version of
285 Perl older than 5.6.1 along with Berkeley DB 3.x. If you want to use
286 Berkeley DB 2.x, you must use the next approach. This approach involves
287 rebuilding your existing version of Perl after applying an unofficial
288 patch. The "patches" directory in the this module's source distribution
289 contains a number of patch files. There is one patch file for every
290 stable version of Perl since 5.004. Apply the appropriate patch to your
291 Perl source tree before re-building and installing Perl from scratch.
292 For example, assuming you are in the top-level source directory for
293 Perl 5.6.0, the command below will apply the necessary patch. Remember
294 to replace the path shown below with one that points to this module's
295 patches directory.
296
297 patch -p1 -N </path/to/BerkeleyDB/patches/5.6.0
298
299 Now rebuild & install perl. You should now have a perl binary that can
300 be used to build this module. Follow the instructions in "BUILDING THE
301 MODULE", remembering to set the INCLUDE and LIB variables in config.in.
302
303
304 The second approach will work with both Berkeley DB 2.x and 3.x.
305 Start by building Berkeley DB as a shared library. This is from
306 the Berkeley DB build instructions:
307
308 Building Shared Libraries for the GNU GCC compiler
309
310 If you're using gcc and there's no better shared library example for
311 your architecture, the following shared library build procedure will
312 probably work.
313
314 Add the -fpic option to the CFLAGS value in the Makefile.
315
316 Rebuild all of your .o files. This will create a Berkeley DB library
317 that contains .o files with PIC code. To build the shared library,
318 then take the following steps in the library build directory:
319
320 % mkdir tmp
321 % cd tmp
322 % ar xv ../libdb.a
323 % gcc -shared -o libdb.so *.o
324 % mv libdb.so ..
325 % cd ..
326 % rm -rf tmp
327
328 Note, you may have to change the gcc line depending on the
329 requirements of your system.
330
331 The file libdb.so is your shared library
332
333 Once you have built libdb.so, you will need to store it somewhere safe.
334
335 cp libdb.so /usr/local/BerkeleyDB/lib
336
337 If you now set the LD_PRELOAD environment variable to point to this
338 shared library, Perl will use it instead of the version of Berkeley DB
339 that shipped with your Linux distribution.
340
341 export LD_PRELOAD=/usr/local/BerkeleyDB/lib/libdb.so
342
343 Finally follow the instructions in "BUILDING THE MODULE" to build,
344 test and install this module. Don't forget to set the INCLUDE and LIB
345 variables in config.in.
346
347 Remember, you will need to have the LD_PRELOAD variable set anytime you
348 want to use Perl with Berkeley DB. Also note that if you have LD_PRELOAD
349 permanently set it will affect ALL commands you execute. This may be a
350 problem if you run any commands that access a database created by the
351 version of Berkeley DB that shipped with your Linux distribution.
352
353
354
355 Solaris 2.5 Notes
356 -----------------
357
358 If you are running Solaris 2.5, and you get this error when you run the
359 BerkeleyDB test harness:
360
361 libc internal error: _rmutex_unlock: rmutex not held.
362
363 you probably need to install a Sun patch. It has been reported that
364 Sun patch 103187-25 (or later revisions) fixes this problem.
365
366 To find out if you have the patch installed, the command "showrev -p"
367 will display the patches that are currently installed on your system.
368
369 Solaris 2.7 Notes
370 -----------------
371
372 If you are running Solaris 2.7 and all the tests in the test harness
373 generate a core dump, try applying Sun patch 106980-09 (or better).
374
375 To find out if you have the patch installed, the command "showrev -p"
376 will display the patches that are currently installed on your system.
377
378
379 HP-UX Notes
380 -----------
381
382 Some people running HP-UX 10 have reported getting an error like this
383 when building this module with the native HP-UX compiler.
384
385 ld: (Warning) At least one PA 2.0 object file (BerkeleyDB.o) was detected.
386 The linked output may not run on a PA 1.x system.
387 ld: Invalid loader fixup for symbol "$000000A5".
388
389 If this is the case for you, Berkeley DB needs to be recompiled with
390 the +z or +Z option and the resulting library placed in a .sl file. The
391 following steps should do the trick:
392
393 1: Configure the Berkeley DB distribution with the +z or +Z C compiler
394 flag:
395
396 env "CFLAGS=+z" ../dist/configure ...
397
398 2: Edit the Berkeley DB Makefile and change:
399
400 "libdb= libdb.a" to "libdb= libdb.sl".
401
402 3: Build and install the Berkeley DB distribution as usual.
403
404
405
406 FEEDBACK
407 --------
408
409 How to report a problem with BerkeleyDB.
410
411 To help me help you, I need of the following information:
412
413 1. The version of Perl and the operating system name and version you
414 are running. The complete output from running "perl -V" will tell
415 me all I need to know.
416 If your perl does not understand the "-V" option is too old.
417 BerkeleyDB needs Perl version 5.004_04 or better.
418
419 2. The version of BerkeleyDB you have. If you have successfully
420 installed BerkeleyDB, this one-liner will tell you:
421
422 perl -MBerkeleyDB -e 'print "BerkeleyDB ver $BerkeleyDB::VERSION\n"'
423
424 If you haven't installed BerkeleyDB then search BerkeleyDB.pm for a
425 line like this:
426
427 $VERSION = "1.20" ;
428
429 3. The version of Berkeley DB you have installed. If you have
430 successfully installed BerkeleyDB, this one-liner will tell you:
431
432 perl -MBerkeleyDB -e 'print BerkeleyDB::DB_VERSION_STRING."\n"'
433
434 If you haven't installed BerkeleyDB then search db.h for a line
435 like this:
436
437 #define DB_VERSION_STRING
438
439 4. If you are having problems building BerkeleyDB, send me a complete
440 log of what happened.
441
442 5. Now the difficult one. If you think you have found a bug in
443 BerkeleyDB and you want me to fix it, you will *greatly* enhance
444 the chances of me being able to track it down by sending me a small
445 self-contained Perl script that illustrates the problem you are
446 encountering. Include a summary of what you think the problem is
447 and a log of what happens when you run the script, in case I can't
448 reproduce your problem on my system. If possible, don't have the
449 script dependent on an existing 20Meg database. If the script you
450 send me can create the database itself then that is preferred.
451
452 I realise that in some cases this is easier said than done, so if
453 you can only reproduce the problem in your existing script, then
454 you can post me that if you want. Just don't expect me to find your
455 problem in a hurry, or at all. :-)
456
457
458 CHANGES
459 -------
460
461 See the Changes file.
462
463 Paul Marquess <Paul.Marquess@btinternet.com>
464