"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "mysql-4.0.27/bdb/perl.DB_File/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 DB_File
2
3 Version 1.76
4
5 15th January 2001
6
7 Copyright (c) 1995-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 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 or 3 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 or 3.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 or greater.
46
47 * Berkeley DB.
48
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
52 the Sleepycat site.
53
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.
58
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, any version will
61 do. For Berkeley DB 1.x, use either version 1.85 or 1.86.
62
63
64 BUILDING THE MODULE
65 -------------------
66
67 Assuming you have met all the prerequisites, building the module should
68 be relatively straightforward.
69
70 Step 1 : If you are running either Solaris 2.5 or HP-UX 10 and want
71 to use Berkeley DB version 2 or 3, 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.
74
75 Step 2 : Edit the file config.in to suit you local installation.
76 Instructions are given in the file.
77
78 Step 3 : Build and test the module using this sequence of commands:
79
80 perl Makefile.PL
81 make
82 make test
83
84
85 NOTE:
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
91 library.
92
93
94 INSTALLATION
95 ------------
96
97 make install
98
99
100 TROUBLESHOOTING
101 ===============
102
103 Here are some of the common problems people encounter when building
104 DB_File.
105
106 Missing db.h or libdb.a
107 -----------------------
108
109 If you get an error like this:
110
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
116
117 or this:
118
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
122
123 This symptom can imply:
124
125 1. You don't have Berkeley DB installed on your system at all.
126 Solution: get & install Berkeley DB.
127
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.
131
132
133 Undefined symbol db_version
134 ---------------------------
135
136 DB_File seems to have built correctly, but you get an error like this
137 when you run the test harness:
138
139 $ make test
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
146 line 166.
147
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)
151
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.
158
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.
164
165 Incompatible versions of db.h and libdb
166 ---------------------------------------
167
168 BerkeleyDB seems to have built correctly, but you get an error like this
169 when you run the test harness:
170
171 $ make test
172 PERL_DL_NONLAZY=1 /home/paul/perl/install/bin/perl5.00560 -Iblib/arch
173 -Iblib/lib -I/home/paul/perl/install/5.005_60/lib/5.00560/i586-linux
174 -I/home/paul/perl/install/5.005_60/lib/5.00560 -e 'use Test::Harness
175 qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
176 t/db-btree..........
177 DB_File needs compatible versions of libdb & db.h
178 you have db.h version 2.3.7 and libdb version 2.7.5
179 BEGIN failed--compilation aborted at t/db-btree.t line 21.
180 ...
181
182 Another variation on the theme of having two versions of Berkeley DB on
183 your system.
184
185 Solution: Setting the LIB & INCLUDE variables in config.in to point to the
186 correct directories can sometimes be enough to fix this
187 problem. If that doesn't work the easiest way to fix the
188 problem is to either delete or temporarily rename the copies
189 of db.h and libdb.a that you don't want BerkeleyDB to use.
190 If you are running Linux, please read the Linux Notes section
191 below.
192
193
194 Linux Notes
195 -----------
196
197 Newer versions of Linux (e.g. RedHat 6, SuSe 6) ship with a C library
198 that has version 2.x of Berkeley DB linked into it. This makes it
199 difficult to build this module with anything other than the version of
200 Berkeley DB that shipped with your Linux release. If you do try to use
201 a different version of Berkeley DB you will most likely get the error
202 described in the "Incompatible versions of db.h and libdb" section of
203 this file.
204
205 To make matters worse, prior to Perl 5.6.1, the perl binary itself
206 *always* included the Berkeley DB library.
207
208 If you want to use a newer version of Berkeley DB with this module, the
209 easiest solution is to use Perl 5.6.1 (or better) and Berkeley DB 3.x
210 (or better).
211
212 There are two approaches you can use to get older versions of Perl to
213 work with specific versions of Berkeley DB. Both have their advantages
214 and disadvantages.
215
216 The first approach will only work when you want to build a version of
217 Perl older than 5.6.1 along with Berkeley DB 3.x. If you want to use
218 Berkeley DB 2.x, you must use the next approach. This approach involves
219 rebuilding your existing version of Perl after applying an unofficial
220 patch. The "patches" directory in the this module's source distribution
221 contains a number of patch files. There is one patch file for every
222 stable version of Perl since 5.004. Apply the appropriate patch to your
223 Perl source tree before re-building and installing Perl from scratch.
224 For example, assuming you are in the top-level source directory for
225 Perl 5.6.0, the command below will apply the necessary patch. Remember
226 to replace the path shown below with one that points to this module's
227 patches directory.
228
229 patch -p1 -N </path/to/DB_File/patches/5.6.0
230
231 Now rebuild & install perl. You should now have a perl binary that can
232 be used to build this module. Follow the instructions in "BUILDING THE
233 MODULE", remembering to set the INCLUDE and LIB variables in config.in.
234
235
236 The second approach will work with both Berkeley DB 2.x and 3.x.
237 Start by building Berkeley DB as a shared library. This is from
238 the Berkeley DB build instructions:
239
240 Building Shared Libraries for the GNU GCC compiler
241
242 If you're using gcc and there's no better shared library example for
243 your architecture, the following shared library build procedure will
244 probably work.
245
246 Add the -fpic option to the CFLAGS value in the Makefile.
247
248 Rebuild all of your .o files. This will create a Berkeley DB library
249 that contains .o files with PIC code. To build the shared library,
250 then take the following steps in the library build directory:
251
252 % mkdir tmp
253 % cd tmp
254 % ar xv ../libdb.a
255 % gcc -shared -o libdb.so *.o
256 % mv libdb.so ..
257 % cd ..
258 % rm -rf tmp
259
260 Note, you may have to change the gcc line depending on the
261 requirements of your system.
262
263 The file libdb.so is your shared library
264
265 Once you have built libdb.so, you will need to store it somewhere safe.
266
267 cp libdb.so /usr/local/BerkeleyDB/lib
268
269 If you now set the LD_PRELOAD environment variable to point to this
270 shared library, Perl will use it instead of the version of Berkeley DB
271 that shipped with your Linux distribution.
272
273 export LD_PRELOAD=/usr/local/BerkeleyDB/lib/libdb.so
274
275 Finally follow the instructions in "BUILDING THE MODULE" to build,
276 test and install this module. Don't forget to set the INCLUDE and LIB
277 variables in config.in.
278
279 Remember, you will need to have the LD_PRELOAD variable set anytime you
280 want to use Perl with Berkeley DB. Also note that if you have LD_PRELOAD
281 permanently set it will affect ALL commands you execute. This may be a
282 problem if you run any commands that access a database created by the
283 version of Berkeley DB that shipped with your Linux distribution.
284
285
286 Solaris Notes
287 -------------
288
289 If you are running Solaris 2.5, and you get this error when you run the
290 DB_File test harness:
291
292 libc internal error: _rmutex_unlock: rmutex not held.
293
294 you probably need to install a Sun patch. It has been reported that
295 Sun patch 103187-25 (or later revisions) fixes this problem.
296
297 To find out if you have the patch installed, the command "showrev -p"
298 will display the patches that are currently installed on your system.
299
300
301 HP-UX Notes
302 -----------
303
304 Some people running HP-UX 10 have reported getting an error like this
305 when building DB_File with the native HP-UX compiler.
306
307 ld: (Warning) At least one PA 2.0 object file (DB_File.o) was detected.
308 The linked output may not run on a PA 1.x system.
309 ld: Invalid loader fixup for symbol "$000000A5".
310
311 If this is the case for you, Berkeley DB needs to be recompiled with
312 the +z or +Z option and the resulting library placed in a .sl file. The
313 following steps should do the trick:
314
315 1: Configure the Berkeley DB distribution with the +z or +Z C compiler
316 flag:
317
318 env "CFLAGS=+z" ../dist/configure ...
319
320 2: Edit the Berkeley DB Makefile and change:
321
322 "libdb= libdb.a" to "libdb= libdb.sl".
323
324
325 3: Build and install the Berkeley DB distribution as usual.
326
327
328 IRIX NOTES
329 ----------
330
331 If you are running IRIX, and want to use Berkeley DB version 1, you can
332 get it from http://reality.sgi.com/ariel. It has the patches necessary
333 to compile properly on IRIX 5.3.
334
335
336 FEEDBACK
337 ========
338
339 How to report a problem with DB_File.
340
341 To help me help you, I need the following information:
342
343 1. The version of Perl and the operating system name and version you
344 are running. The *complete* output from running "perl -V" will
345 tell me all I need to know. Don't edit the output in any way. Note,
346 I want you to run "perl -V" and NOT "perl -v".
347
348 If your perl does not understand the "-V" option it is too old. DB_File
349 needs Perl version 5.004 or better.
350
351 2. The version of DB_File you have.
352 If you have successfully installed DB_File, this one-liner will
353 tell you:
354
355 perl -e 'use DB_File; print "DB_File ver $DB_File::VERSION\n"'
356
357 If you haven't installed DB_File then search DB_File.pm for a line
358 like this:
359
360 $VERSION = "1.20" ;
361
362 3. The version of Berkeley DB you are using.
363 If you are using a version older than 1.85, think about upgrading. One
364 point to note if you are considering upgrading Berkeley DB - the
365 file formats for 1.85, 1.86, 2.0, 3.0 & 3.1 are all different.
366
367 If you have successfully installed DB_File, this command will display
368 the version of Berkeley DB it was built with:
369
370 perl -e 'use DB_File; print "Berkeley DB ver $DB_File::db_ver\n"'
371
372 4. If you are having problems building DB_File, send me a complete log
373 of what happened.
374
375 5. Now the difficult one. If you think you have found a bug in DB_File
376 and you want me to fix it, you will *greatly* enhance the chances
377 of me being able to track it down by sending me a small
378 self-contained Perl script that illustrates the problem you are
379 encountering. Include a summary of what you think the problem is
380 and a log of what happens when you run the script, in case I can't
381 reproduce your problem on my system. If possible, don't have the
382 script dependent on an existing 20Meg database. If the script you
383 send me can create the database itself then that is preferred.
384
385 I realise that in some cases this is easier said than done, so if
386 you can only reproduce the problem in your existing script, then
387 you can post me that if you want. Just don't expect me to find your
388 problem in a hurry, or at all. :-)
389
390
391 CHANGES
392 -------
393
394 See the Changes file.
395
396 Paul Marquess <Paul.Marquess@btinternet.com>