This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add socklen_t probe; Configure maintenance.
[perl5.git] / ext / DB_File / DB_File.pm
CommitLineData
a0d0e21e
LW
1# DB_File.pm -- Perl 5 interface to Berkeley DB
2#
6ca2e664 3# written by Paul Marquess (Paul.Marquess@btinternet.com)
b90e71be
GS
4# last modified 16th January 2000
5# version 1.72
36477c24 6#
b90e71be 7# Copyright (c) 1995-2000 Paul Marquess. All rights reserved.
36477c24
PP
8# This program is free software; you can redistribute it and/or
9# modify it under the same terms as Perl itself.
10
8e07c86e
AD
11
12package DB_File::HASHINFO ;
785da04d 13
610ab055
PM
14require 5.003 ;
15
785da04d 16use strict;
8e07c86e 17use Carp;
88108326
PP
18require Tie::Hash;
19@DB_File::HASHINFO::ISA = qw(Tie::Hash);
8e07c86e 20
88108326 21sub new
8e07c86e 22{
88108326
PP
23 my $pkg = shift ;
24 my %x ;
25 tie %x, $pkg ;
26 bless \%x, $pkg ;
8e07c86e
AD
27}
28
610ab055 29
88108326
PP
30sub TIEHASH
31{
32 my $pkg = shift ;
33
36477c24
PP
34 bless { VALID => { map {$_, 1}
35 qw( bsize ffactor nelem cachesize hash lorder)
36 },
37 GOT => {}
38 }, $pkg ;
88108326 39}
8e07c86e 40
610ab055 41
8e07c86e
AD
42sub FETCH
43{
88108326
PP
44 my $self = shift ;
45 my $key = shift ;
8e07c86e 46
36477c24 47 return $self->{GOT}{$key} if exists $self->{VALID}{$key} ;
88108326
PP
48
49 my $pkg = ref $self ;
50 croak "${pkg}::FETCH - Unknown element '$key'" ;
8e07c86e
AD
51}
52
53
54sub STORE
55{
88108326
PP
56 my $self = shift ;
57 my $key = shift ;
58 my $value = shift ;
59
36477c24 60 if ( exists $self->{VALID}{$key} )
8e07c86e 61 {
36477c24 62 $self->{GOT}{$key} = $value ;
8e07c86e
AD
63 return ;
64 }
65
88108326
PP
66 my $pkg = ref $self ;
67 croak "${pkg}::STORE - Unknown element '$key'" ;
8e07c86e
AD
68}
69
70sub DELETE
71{
88108326
PP
72 my $self = shift ;
73 my $key = shift ;
74
36477c24 75 if ( exists $self->{VALID}{$key} )
8e07c86e 76 {
36477c24 77 delete $self->{GOT}{$key} ;
8e07c86e
AD
78 return ;
79 }
80
88108326
PP
81 my $pkg = ref $self ;
82 croak "DB_File::HASHINFO::DELETE - Unknown element '$key'" ;
8e07c86e
AD
83}
84
88108326 85sub EXISTS
8e07c86e 86{
88108326
PP
87 my $self = shift ;
88 my $key = shift ;
8e07c86e 89
36477c24 90 exists $self->{VALID}{$key} ;
8e07c86e
AD
91}
92
88108326 93sub NotHere
8e07c86e 94{
18d2dc8c 95 my $self = shift ;
88108326 96 my $method = shift ;
8e07c86e 97
18d2dc8c 98 croak ref($self) . " does not define the method ${method}" ;
8e07c86e
AD
99}
100
18d2dc8c
PM
101sub FIRSTKEY { my $self = shift ; $self->NotHere("FIRSTKEY") }
102sub NEXTKEY { my $self = shift ; $self->NotHere("NEXTKEY") }
103sub CLEAR { my $self = shift ; $self->NotHere("CLEAR") }
8e07c86e
AD
104
105package DB_File::RECNOINFO ;
785da04d 106
88108326
PP
107use strict ;
108
045291aa 109@DB_File::RECNOINFO::ISA = qw(DB_File::HASHINFO) ;
8e07c86e
AD
110
111sub TIEHASH
112{
88108326
PP
113 my $pkg = shift ;
114
36477c24
PP
115 bless { VALID => { map {$_, 1}
116 qw( bval cachesize psize flags lorder reclen bfname )
117 },
118 GOT => {},
119 }, $pkg ;
8e07c86e
AD
120}
121
88108326 122package DB_File::BTREEINFO ;
8e07c86e 123
88108326 124use strict ;
8e07c86e 125
88108326 126@DB_File::BTREEINFO::ISA = qw(DB_File::HASHINFO) ;
8e07c86e 127
88108326 128sub TIEHASH
8e07c86e 129{
88108326
PP
130 my $pkg = shift ;
131
36477c24
PP
132 bless { VALID => { map {$_, 1}
133 qw( flags cachesize maxkeypage minkeypage psize
134 compare prefix lorder )
135 },
136 GOT => {},
137 }, $pkg ;
8e07c86e
AD
138}
139
140
8e07c86e 141package DB_File ;
785da04d
PM
142
143use strict;
b90e71be
GS
144use vars qw($VERSION @ISA @EXPORT $AUTOLOAD $DB_BTREE $DB_HASH $DB_RECNO
145 $db_version $use_XSLoader
146 ) ;
8e07c86e
AD
147use Carp;
148
785da04d 149
b90e71be 150$VERSION = "1.72" ;
8e07c86e
AD
151
152#typedef enum { DB_BTREE, DB_HASH, DB_RECNO } DBTYPE;
88108326
PP
153$DB_BTREE = new DB_File::BTREEINFO ;
154$DB_HASH = new DB_File::HASHINFO ;
155$DB_RECNO = new DB_File::RECNOINFO ;
8e07c86e 156
785da04d 157require Tie::Hash;
8e07c86e
AD
158require Exporter;
159use AutoLoader;
b90e71be
GS
160BEGIN {
161 $use_XSLoader = 1 ;
162 eval { require XSLoader } ;
163
164 if ($@) {
165 $use_XSLoader = 0 ;
166 require DynaLoader;
167 @ISA = qw(DynaLoader);
168 }
169}
170
171push @ISA, qw(Tie::Hash Exporter);
8e07c86e
AD
172@EXPORT = qw(
173 $DB_BTREE $DB_HASH $DB_RECNO
88108326 174
8e07c86e
AD
175 BTREEMAGIC
176 BTREEVERSION
177 DB_LOCK
178 DB_SHMEM
179 DB_TXN
180 HASHMAGIC
181 HASHVERSION
182 MAX_PAGE_NUMBER
183 MAX_PAGE_OFFSET
184 MAX_REC_NUMBER
185 RET_ERROR
186 RET_SPECIAL
187 RET_SUCCESS
188 R_CURSOR
189 R_DUP
190 R_FIRST
191 R_FIXEDLEN
192 R_IAFTER
193 R_IBEFORE
194 R_LAST
195 R_NEXT
196 R_NOKEY
197 R_NOOVERWRITE
198 R_PREV
199 R_RECNOSYNC
200 R_SETCURSOR
201 R_SNAPSHOT
202 __R_UNUSED
88108326 203
045291aa 204);
8e07c86e
AD
205
206sub AUTOLOAD {
785da04d 207 my($constname);
8e07c86e 208 ($constname = $AUTOLOAD) =~ s/.*:://;
785da04d 209 my $val = constant($constname, @_ ? $_[0] : 0);
8e07c86e 210 if ($! != 0) {
265f5c4a 211 if ($! =~ /Invalid/ || $!{EINVAL}) {
8e07c86e
AD
212 $AutoLoader::AUTOLOAD = $AUTOLOAD;
213 goto &AutoLoader::AUTOLOAD;
214 }
215 else {
785da04d 216 my($pack,$file,$line) = caller;
8e07c86e
AD
217 croak "Your vendor has not defined DB macro $constname, used at $file line $line.
218";
219 }
220 }
221 eval "sub $AUTOLOAD { $val }";
222 goto &$AUTOLOAD;
223}
224
f6b705ef 225
a6ed719b 226eval {
1f70e1ea
PM
227 # Make all Fcntl O_XXX constants available for importing
228 require Fcntl;
229 my @O = grep /^O_/, @Fcntl::EXPORT;
230 Fcntl->import(@O); # first we import what we want to export
231 push(@EXPORT, @O);
a6ed719b 232};
f6b705ef 233
b90e71be
GS
234if ($use_XSLoader)
235 { XSLoader::load("DB_File", $VERSION)}
236else
237 { bootstrap DB_File $VERSION }
8e07c86e
AD
238
239# Preloaded methods go here. Autoload methods go after __END__, and are
240# processed by the autosplit program.
241
05475680 242sub tie_hash_or_array
610ab055
PM
243{
244 my (@arg) = @_ ;
05475680 245 my $tieHASH = ( (caller(1))[3] =~ /TIEHASH/ ) ;
610ab055
PM
246
247 $arg[4] = tied %{ $arg[4] }
248 if @arg >= 5 && ref $arg[4] && $arg[4] =~ /=HASH/ && tied %{ $arg[4] } ;
249
1f70e1ea
PM
250 # make recno in Berkeley DB version 2 work like recno in version 1.
251 if ($db_version > 1 and defined $arg[4] and $arg[4] =~ /RECNO/ and
252 $arg[1] and ! -e $arg[1]) {
253 open(FH, ">$arg[1]") or return undef ;
254 close FH ;
255 chmod $arg[3] ? $arg[3] : 0666 , $arg[1] ;
256 }
257
05475680 258 DoTie_($tieHASH, @arg) ;
610ab055
PM
259}
260
05475680
PM
261sub TIEHASH
262{
263 tie_hash_or_array(@_) ;
264}
265
266sub TIEARRAY
267{
268 tie_hash_or_array(@_) ;
269}
88108326 270
045291aa
PM
271sub CLEAR
272{
1f70e1ea
PM
273 my $self = shift;
274 my $key = "" ;
275 my $value = "" ;
276 my $status = $self->seq($key, $value, R_FIRST());
277 my @keys;
278
279 while ($status == 0) {
280 push @keys, $key;
281 $status = $self->seq($key, $value, R_NEXT());
282 }
283 foreach $key (reverse @keys) {
284 my $s = $self->del($key);
285 }
286}
287
045291aa
PM
288sub EXTEND { }
289
290sub STORESIZE
291{
292 my $self = shift;
293 my $length = shift ;
294 my $current_length = $self->length() ;
295
296 if ($length < $current_length) {
297 my $key ;
298 for ($key = $current_length - 1 ; $key >= $length ; -- $key)
299 { $self->del($key) }
300 }
a9fd575d
PM
301 elsif ($length > $current_length) {
302 $self->put($length-1, "") ;
303 }
045291aa
PM
304}
305
6ca2e664
PM
306sub find_dup
307{
308 croak "Usage: \$db->find_dup(key,value)\n"
309 unless @_ == 3 ;
310
311 my $db = shift ;
312 my ($origkey, $value_wanted) = @_ ;
313 my ($key, $value) = ($origkey, 0);
314 my ($status) = 0 ;
315
316 for ($status = $db->seq($key, $value, R_CURSOR() ) ;
317 $status == 0 ;
318 $status = $db->seq($key, $value, R_NEXT() ) ) {
319
320 return 0 if $key eq $origkey and $value eq $value_wanted ;
321 }
322
323 return $status ;
324}
325
326sub del_dup
327{
328 croak "Usage: \$db->del_dup(key,value)\n"
329 unless @_ == 3 ;
330
331 my $db = shift ;
332 my ($key, $value) = @_ ;
333 my ($status) = $db->find_dup($key, $value) ;
334 return $status if $status != 0 ;
335
336 $status = $db->del($key, R_CURSOR() ) ;
337 return $status ;
338}
339
88108326
PP
340sub get_dup
341{
342 croak "Usage: \$db->get_dup(key [,flag])\n"
343 unless @_ == 2 or @_ == 3 ;
344
345 my $db = shift ;
346 my $key = shift ;
347 my $flag = shift ;
f6b705ef 348 my $value = 0 ;
88108326
PP
349 my $origkey = $key ;
350 my $wantarray = wantarray ;
f6b705ef 351 my %values = () ;
88108326
PP
352 my @values = () ;
353 my $counter = 0 ;
f6b705ef 354 my $status = 0 ;
88108326 355
f6b705ef
PP
356 # iterate through the database until either EOF ($status == 0)
357 # or a different key is encountered ($key ne $origkey).
358 for ($status = $db->seq($key, $value, R_CURSOR()) ;
359 $status == 0 and $key eq $origkey ;
360 $status = $db->seq($key, $value, R_NEXT()) ) {
88108326 361
f6b705ef
PP
362 # save the value or count number of matches
363 if ($wantarray) {
364 if ($flag)
365 { ++ $values{$value} }
366 else
367 { push (@values, $value) }
368 }
369 else
370 { ++ $counter }
88108326 371
88108326
PP
372 }
373
f6b705ef 374 return ($wantarray ? ($flag ? %values : @values) : $counter) ;
88108326
PP
375}
376
377
8e07c86e
AD
3781;
379__END__
380
3b35bae3
AD
381=head1 NAME
382
1f70e1ea 383DB_File - Perl5 access to Berkeley DB version 1.x
3b35bae3
AD
384
385=head1 SYNOPSIS
386
387 use DB_File ;
88108326
PP
388
389 [$X =] tie %hash, 'DB_File', [$filename, $flags, $mode, $DB_HASH] ;
390 [$X =] tie %hash, 'DB_File', $filename, $flags, $mode, $DB_BTREE ;
391 [$X =] tie @array, 'DB_File', $filename, $flags, $mode, $DB_RECNO ;
760ac839 392
3b35bae3
AD
393 $status = $X->del($key [, $flags]) ;
394 $status = $X->put($key, $value [, $flags]) ;
395 $status = $X->get($key, $value [, $flags]) ;
760ac839 396 $status = $X->seq($key, $value, $flags) ;
3b35bae3
AD
397 $status = $X->sync([$flags]) ;
398 $status = $X->fd ;
760ac839 399
f6b705ef 400 # BTREE only
88108326
PP
401 $count = $X->get_dup($key) ;
402 @list = $X->get_dup($key) ;
403 %list = $X->get_dup($key, 1) ;
6ca2e664
PM
404 $status = $X->find_dup($key, $value) ;
405 $status = $X->del_dup($key, $value) ;
88108326 406
f6b705ef
PP
407 # RECNO only
408 $a = $X->length;
409 $a = $X->pop ;
410 $X->push(list);
411 $a = $X->shift;
412 $X->unshift(list);
413
cad2e5aa
JH
414 # DBM Filters
415 $old_filter = $db->filter_store_key ( sub { ... } ) ;
416 $old_filter = $db->filter_store_value( sub { ... } ) ;
417 $old_filter = $db->filter_fetch_key ( sub { ... } ) ;
418 $old_filter = $db->filter_fetch_value( sub { ... } ) ;
419
3b35bae3
AD
420 untie %hash ;
421 untie @array ;
422
423=head1 DESCRIPTION
424
8e07c86e 425B<DB_File> is a module which allows Perl programs to make use of the
1f70e1ea 426facilities provided by Berkeley DB version 1.x (if you have a newer
039d031f
PM
427version of DB, see L<Using DB_File with Berkeley DB version 2 or 3>).
428It is assumed that you have a copy of the Berkeley DB manual pages at
429hand when reading this documentation. The interface defined here
430mirrors the Berkeley DB interface closely.
68dc0745 431
8e07c86e
AD
432Berkeley DB is a C library which provides a consistent interface to a
433number of database formats. B<DB_File> provides an interface to all
434three of the database types currently supported by Berkeley DB.
3b35bae3
AD
435
436The file types are:
437
438=over 5
439
88108326 440=item B<DB_HASH>
3b35bae3 441
88108326 442This database type allows arbitrary key/value pairs to be stored in data
8e07c86e
AD
443files. This is equivalent to the functionality provided by other
444hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though,
445the files created using DB_HASH are not compatible with any of the
446other packages mentioned.
3b35bae3 447
8e07c86e
AD
448A default hashing algorithm, which will be adequate for most
449applications, is built into Berkeley DB. If you do need to use your own
450hashing algorithm it is possible to write your own in Perl and have
451B<DB_File> use it instead.
3b35bae3 452
88108326
PP
453=item B<DB_BTREE>
454
455The btree format allows arbitrary key/value pairs to be stored in a
8e07c86e 456sorted, balanced binary tree.
3b35bae3 457
8e07c86e
AD
458As with the DB_HASH format, it is possible to provide a user defined
459Perl routine to perform the comparison of keys. By default, though, the
460keys are stored in lexical order.
3b35bae3 461
88108326 462=item B<DB_RECNO>
3b35bae3 463
8e07c86e
AD
464DB_RECNO allows both fixed-length and variable-length flat text files
465to be manipulated using the same key/value pair interface as in DB_HASH
466and DB_BTREE. In this case the key will consist of a record (line)
467number.
3b35bae3
AD
468
469=back
470
039d031f 471=head2 Using DB_File with Berkeley DB version 2 or 3
1f70e1ea
PM
472
473Although B<DB_File> is intended to be used with Berkeley DB version 1,
039d031f 474it can also be used with version 2.or 3 In this case the interface is
1f70e1ea 475limited to the functionality provided by Berkeley DB 1.x. Anywhere the
039d031f
PM
476version 2 or 3 interface differs, B<DB_File> arranges for it to work
477like version 1. This feature allows B<DB_File> scripts that were built
478with version 1 to be migrated to version 2 or 3 without any changes.
1f70e1ea
PM
479
480If you want to make use of the new features available in Berkeley DB
b90e71be 4812.x or greater, use the Perl module B<BerkeleyDB> instead.
1f70e1ea 482
039d031f
PM
483B<Note:> The database file format has changed in both Berkeley DB
484version 2 and 3. If you cannot recreate your databases, you must dump
485any existing databases with the C<db_dump185> utility that comes with
486Berkeley DB.
487Once you have rebuilt DB_File to use Berkeley DB version 2 or 3, your
1f70e1ea
PM
488databases can be recreated using C<db_load>. Refer to the Berkeley DB
489documentation for further details.
490
039d031f
PM
491Please read L<"COPYRIGHT"> before using version 2.x or 3.x of Berkeley
492DB with DB_File.
1f70e1ea 493
68dc0745 494=head2 Interface to Berkeley DB
3b35bae3
AD
495
496B<DB_File> allows access to Berkeley DB files using the tie() mechanism
8e07c86e
AD
497in Perl 5 (for full details, see L<perlfunc/tie()>). This facility
498allows B<DB_File> to access Berkeley DB files using either an
499associative array (for DB_HASH & DB_BTREE file types) or an ordinary
500array (for the DB_RECNO file type).
3b35bae3 501
88108326
PP
502In addition to the tie() interface, it is also possible to access most
503of the functions provided in the Berkeley DB API directly.
f6b705ef 504See L<THE API INTERFACE>.
3b35bae3 505
88108326 506=head2 Opening a Berkeley DB Database File
3b35bae3 507
8e07c86e 508Berkeley DB uses the function dbopen() to open or create a database.
f6b705ef 509Here is the C prototype for dbopen():
3b35bae3
AD
510
511 DB*
512 dbopen (const char * file, int flags, int mode,
513 DBTYPE type, const void * openinfo)
514
515The parameter C<type> is an enumeration which specifies which of the 3
516interface methods (DB_HASH, DB_BTREE or DB_RECNO) is to be used.
517Depending on which of these is actually chosen, the final parameter,
518I<openinfo> points to a data structure which allows tailoring of the
519specific interface method.
520
8e07c86e 521This interface is handled slightly differently in B<DB_File>. Here is
88108326 522an equivalent call using B<DB_File>:
3b35bae3 523
88108326 524 tie %array, 'DB_File', $filename, $flags, $mode, $DB_HASH ;
3b35bae3 525
8e07c86e
AD
526The C<filename>, C<flags> and C<mode> parameters are the direct
527equivalent of their dbopen() counterparts. The final parameter $DB_HASH
528performs the function of both the C<type> and C<openinfo> parameters in
529dbopen().
3b35bae3 530
88108326
PP
531In the example above $DB_HASH is actually a pre-defined reference to a
532hash object. B<DB_File> has three of these pre-defined references.
533Apart from $DB_HASH, there is also $DB_BTREE and $DB_RECNO.
3b35bae3 534
8e07c86e
AD
535The keys allowed in each of these pre-defined references is limited to
536the names used in the equivalent C structure. So, for example, the
537$DB_HASH reference will only allow keys called C<bsize>, C<cachesize>,
88108326
PP
538C<ffactor>, C<hash>, C<lorder> and C<nelem>.
539
540To change one of these elements, just assign to it like this:
541
542 $DB_HASH->{'cachesize'} = 10000 ;
543
544The three predefined variables $DB_HASH, $DB_BTREE and $DB_RECNO are
545usually adequate for most applications. If you do need to create extra
546instances of these objects, constructors are available for each file
547type.
548
549Here are examples of the constructors and the valid options available
550for DB_HASH, DB_BTREE and DB_RECNO respectively.
551
552 $a = new DB_File::HASHINFO ;
553 $a->{'bsize'} ;
554 $a->{'cachesize'} ;
555 $a->{'ffactor'};
556 $a->{'hash'} ;
557 $a->{'lorder'} ;
558 $a->{'nelem'} ;
559
560 $b = new DB_File::BTREEINFO ;
561 $b->{'flags'} ;
562 $b->{'cachesize'} ;
563 $b->{'maxkeypage'} ;
564 $b->{'minkeypage'} ;
565 $b->{'psize'} ;
566 $b->{'compare'} ;
567 $b->{'prefix'} ;
568 $b->{'lorder'} ;
569
570 $c = new DB_File::RECNOINFO ;
571 $c->{'bval'} ;
572 $c->{'cachesize'} ;
573 $c->{'psize'} ;
574 $c->{'flags'} ;
575 $c->{'lorder'} ;
576 $c->{'reclen'} ;
577 $c->{'bfname'} ;
578
579The values stored in the hashes above are mostly the direct equivalent
580of their C counterpart. Like their C counterparts, all are set to a
f6b705ef 581default values - that means you don't have to set I<all> of the
88108326
PP
582values when you only want to change one. Here is an example:
583
584 $a = new DB_File::HASHINFO ;
585 $a->{'cachesize'} = 12345 ;
586 tie %y, 'DB_File', "filename", $flags, 0777, $a ;
587
36477c24 588A few of the options need extra discussion here. When used, the C
88108326
PP
589equivalent of the keys C<hash>, C<compare> and C<prefix> store pointers
590to C functions. In B<DB_File> these keys are used to store references
591to Perl subs. Below are templates for each of the subs:
592
593 sub hash
594 {
595 my ($data) = @_ ;
596 ...
597 # return the hash value for $data
598 return $hash ;
599 }
3b35bae3 600
88108326
PP
601 sub compare
602 {
603 my ($key, $key2) = @_ ;
604 ...
605 # return 0 if $key1 eq $key2
606 # -1 if $key1 lt $key2
607 # 1 if $key1 gt $key2
608 return (-1 , 0 or 1) ;
609 }
3b35bae3 610
88108326
PP
611 sub prefix
612 {
613 my ($key, $key2) = @_ ;
614 ...
615 # return number of bytes of $key2 which are
616 # necessary to determine that it is greater than $key1
617 return $bytes ;
618 }
3b35bae3 619
f6b705ef
PP
620See L<Changing the BTREE sort order> for an example of using the
621C<compare> template.
88108326 622
36477c24 623If you are using the DB_RECNO interface and you intend making use of
9a2c4ce3 624C<bval>, you should check out L<The 'bval' Option>.
36477c24 625
88108326
PP
626=head2 Default Parameters
627
628It is possible to omit some or all of the final 4 parameters in the
629call to C<tie> and let them take default values. As DB_HASH is the most
630common file format used, the call:
631
632 tie %A, "DB_File", "filename" ;
633
634is equivalent to:
635
18d2dc8c 636 tie %A, "DB_File", "filename", O_CREAT|O_RDWR, 0666, $DB_HASH ;
88108326
PP
637
638It is also possible to omit the filename parameter as well, so the
639call:
640
641 tie %A, "DB_File" ;
642
643is equivalent to:
644
18d2dc8c 645 tie %A, "DB_File", undef, O_CREAT|O_RDWR, 0666, $DB_HASH ;
88108326 646
f6b705ef 647See L<In Memory Databases> for a discussion on the use of C<undef>
88108326
PP
648in place of a filename.
649
f6b705ef
PP
650=head2 In Memory Databases
651
652Berkeley DB allows the creation of in-memory databases by using NULL
653(that is, a C<(char *)0> in C) in place of the filename. B<DB_File>
654uses C<undef> instead of NULL to provide this functionality.
655
656=head1 DB_HASH
657
658The DB_HASH file format is probably the most commonly used of the three
659file formats that B<DB_File> supports. It is also very straightforward
660to use.
661
68dc0745 662=head2 A Simple Example
f6b705ef
PP
663
664This example shows how to create a database, add key/value pairs to the
665database, delete keys/value pairs and finally how to enumerate the
666contents of the database.
667
610ab055 668 use strict ;
f6b705ef 669 use DB_File ;
610ab055 670 use vars qw( %h $k $v ) ;
f6b705ef 671
2c2d71f5 672 unlink "fruit" ;
f6b705ef
PP
673 tie %h, "DB_File", "fruit", O_RDWR|O_CREAT, 0640, $DB_HASH
674 or die "Cannot open file 'fruit': $!\n";
675
676 # Add a few key/value pairs to the file
677 $h{"apple"} = "red" ;
678 $h{"orange"} = "orange" ;
679 $h{"banana"} = "yellow" ;
680 $h{"tomato"} = "red" ;
681
682 # Check for existence of a key
683 print "Banana Exists\n\n" if $h{"banana"} ;
684
685 # Delete a key/value pair.
686 delete $h{"apple"} ;
687
688 # print the contents of the file
689 while (($k, $v) = each %h)
690 { print "$k -> $v\n" }
691
692 untie %h ;
693
694here is the output:
695
696 Banana Exists
697
698 orange -> orange
699 tomato -> red
700 banana -> yellow
701
702Note that the like ordinary associative arrays, the order of the keys
703retrieved is in an apparently random order.
704
705=head1 DB_BTREE
706
707The DB_BTREE format is useful when you want to store data in a given
708order. By default the keys will be stored in lexical order, but as you
709will see from the example shown in the next section, it is very easy to
710define your own sorting function.
711
712=head2 Changing the BTREE sort order
713
714This script shows how to override the default sorting algorithm that
715BTREE uses. Instead of using the normal lexical ordering, a case
716insensitive compare function will be used.
88108326 717
610ab055 718 use strict ;
f6b705ef 719 use DB_File ;
610ab055
PM
720
721 my %h ;
f6b705ef
PP
722
723 sub Compare
724 {
725 my ($key1, $key2) = @_ ;
726 "\L$key1" cmp "\L$key2" ;
727 }
728
729 # specify the Perl sub that will do the comparison
730 $DB_BTREE->{'compare'} = \&Compare ;
731
2c2d71f5 732 unlink "tree" ;
f6b705ef
PP
733 tie %h, "DB_File", "tree", O_RDWR|O_CREAT, 0640, $DB_BTREE
734 or die "Cannot open file 'tree': $!\n" ;
735
736 # Add a key/value pair to the file
737 $h{'Wall'} = 'Larry' ;
738 $h{'Smith'} = 'John' ;
739 $h{'mouse'} = 'mickey' ;
740 $h{'duck'} = 'donald' ;
741
742 # Delete
743 delete $h{"duck"} ;
744
745 # Cycle through the keys printing them in order.
746 # Note it is not necessary to sort the keys as
747 # the btree will have kept them in order automatically.
748 foreach (keys %h)
749 { print "$_\n" }
750
751 untie %h ;
752
753Here is the output from the code above.
754
755 mouse
756 Smith
757 Wall
758
759There are a few point to bear in mind if you want to change the
760ordering in a BTREE database:
761
762=over 5
763
764=item 1.
765
766The new compare function must be specified when you create the database.
767
768=item 2.
769
770You cannot change the ordering once the database has been created. Thus
771you must use the same compare function every time you access the
88108326
PP
772database.
773
f6b705ef
PP
774=back
775
68dc0745 776=head2 Handling Duplicate Keys
f6b705ef
PP
777
778The BTREE file type optionally allows a single key to be associated
779with an arbitrary number of values. This option is enabled by setting
780the flags element of C<$DB_BTREE> to R_DUP when creating the database.
781
88108326
PP
782There are some difficulties in using the tied hash interface if you
783want to manipulate a BTREE database with duplicate keys. Consider this
784code:
785
610ab055 786 use strict ;
88108326 787 use DB_File ;
610ab055
PM
788
789 use vars qw($filename %h ) ;
790
88108326
PP
791 $filename = "tree" ;
792 unlink $filename ;
793
794 # Enable duplicate records
795 $DB_BTREE->{'flags'} = R_DUP ;
796
797 tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE
798 or die "Cannot open $filename: $!\n";
799
800 # Add some key/value pairs to the file
801 $h{'Wall'} = 'Larry' ;
802 $h{'Wall'} = 'Brick' ; # Note the duplicate key
f6b705ef 803 $h{'Wall'} = 'Brick' ; # Note the duplicate key and value
88108326
PP
804 $h{'Smith'} = 'John' ;
805 $h{'mouse'} = 'mickey' ;
806
807 # iterate through the associative array
808 # and print each key/value pair.
2c2d71f5 809 foreach (sort keys %h)
88108326
PP
810 { print "$_ -> $h{$_}\n" }
811
f6b705ef
PP
812 untie %h ;
813
88108326
PP
814Here is the output:
815
816 Smith -> John
817 Wall -> Larry
818 Wall -> Larry
f6b705ef 819 Wall -> Larry
88108326
PP
820 mouse -> mickey
821
f6b705ef 822As you can see 3 records have been successfully created with key C<Wall>
88108326 823- the only thing is, when they are retrieved from the database they
f6b705ef
PP
824I<seem> to have the same value, namely C<Larry>. The problem is caused
825by the way that the associative array interface works. Basically, when
826the associative array interface is used to fetch the value associated
827with a given key, it will only ever retrieve the first value.
88108326
PP
828
829Although it may not be immediately obvious from the code above, the
830associative array interface can be used to write values with duplicate
831keys, but it cannot be used to read them back from the database.
832
833The way to get around this problem is to use the Berkeley DB API method
834called C<seq>. This method allows sequential access to key/value
f6b705ef
PP
835pairs. See L<THE API INTERFACE> for details of both the C<seq> method
836and the API in general.
88108326
PP
837
838Here is the script above rewritten using the C<seq> API method.
839
610ab055 840 use strict ;
88108326 841 use DB_File ;
88108326 842
610ab055
PM
843 use vars qw($filename $x %h $status $key $value) ;
844
88108326
PP
845 $filename = "tree" ;
846 unlink $filename ;
847
848 # Enable duplicate records
849 $DB_BTREE->{'flags'} = R_DUP ;
850
851 $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE
852 or die "Cannot open $filename: $!\n";
853
854 # Add some key/value pairs to the file
855 $h{'Wall'} = 'Larry' ;
856 $h{'Wall'} = 'Brick' ; # Note the duplicate key
f6b705ef 857 $h{'Wall'} = 'Brick' ; # Note the duplicate key and value
88108326
PP
858 $h{'Smith'} = 'John' ;
859 $h{'mouse'} = 'mickey' ;
860
f6b705ef 861 # iterate through the btree using seq
88108326 862 # and print each key/value pair.
610ab055 863 $key = $value = 0 ;
f6b705ef
PP
864 for ($status = $x->seq($key, $value, R_FIRST) ;
865 $status == 0 ;
866 $status = $x->seq($key, $value, R_NEXT) )
88108326
PP
867 { print "$key -> $value\n" }
868
869 undef $x ;
870 untie %h ;
871
872that prints:
873
874 Smith -> John
875 Wall -> Brick
f6b705ef 876 Wall -> Brick
88108326
PP
877 Wall -> Larry
878 mouse -> mickey
879
f6b705ef 880This time we have got all the key/value pairs, including the multiple
88108326
PP
881values associated with the key C<Wall>.
882
6ca2e664
PM
883To make life easier when dealing with duplicate keys, B<DB_File> comes with
884a few utility methods.
885
68dc0745 886=head2 The get_dup() Method
f6b705ef 887
6ca2e664 888The C<get_dup> method assists in
88108326
PP
889reading duplicate values from BTREE databases. The method can take the
890following forms:
891
892 $count = $x->get_dup($key) ;
893 @list = $x->get_dup($key) ;
894 %list = $x->get_dup($key, 1) ;
895
896In a scalar context the method returns the number of values associated
897with the key, C<$key>.
898
899In list context, it returns all the values which match C<$key>. Note
f6b705ef 900that the values will be returned in an apparently random order.
88108326 901
7a2e2cd6
PP
902In list context, if the second parameter is present and evaluates
903TRUE, the method returns an associative array. The keys of the
904associative array correspond to the values that matched in the BTREE
905and the values of the array are a count of the number of times that
906particular value occurred in the BTREE.
88108326 907
f6b705ef 908So assuming the database created above, we can use C<get_dup> like
88108326
PP
909this:
910
2c2d71f5
JH
911 use strict ;
912 use DB_File ;
913
914 use vars qw($filename $x %h ) ;
915
916 $filename = "tree" ;
917
918 # Enable duplicate records
919 $DB_BTREE->{'flags'} = R_DUP ;
920
921 $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE
922 or die "Cannot open $filename: $!\n";
923
610ab055 924 my $cnt = $x->get_dup("Wall") ;
88108326
PP
925 print "Wall occurred $cnt times\n" ;
926
610ab055 927 my %hash = $x->get_dup("Wall", 1) ;
88108326 928 print "Larry is there\n" if $hash{'Larry'} ;
f6b705ef 929 print "There are $hash{'Brick'} Brick Walls\n" ;
88108326 930
2c2d71f5 931 my @list = sort $x->get_dup("Wall") ;
88108326
PP
932 print "Wall => [@list]\n" ;
933
f6b705ef 934 @list = $x->get_dup("Smith") ;
88108326
PP
935 print "Smith => [@list]\n" ;
936
f6b705ef 937 @list = $x->get_dup("Dog") ;
88108326
PP
938 print "Dog => [@list]\n" ;
939
940
941and it will print:
942
f6b705ef 943 Wall occurred 3 times
88108326 944 Larry is there
f6b705ef
PP
945 There are 2 Brick Walls
946 Wall => [Brick Brick Larry]
88108326
PP
947 Smith => [John]
948 Dog => []
3b35bae3 949
6ca2e664
PM
950=head2 The find_dup() Method
951
952 $status = $X->find_dup($key, $value) ;
953
b90e71be 954This method checks for the existence of a specific key/value pair. If the
6ca2e664
PM
955pair exists, the cursor is left pointing to the pair and the method
956returns 0. Otherwise the method returns a non-zero value.
957
958Assuming the database from the previous example:
959
960 use strict ;
961 use DB_File ;
962
963 use vars qw($filename $x %h $found) ;
964
965 my $filename = "tree" ;
966
967 # Enable duplicate records
968 $DB_BTREE->{'flags'} = R_DUP ;
969
970 $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE
971 or die "Cannot open $filename: $!\n";
972
973 $found = ( $x->find_dup("Wall", "Larry") == 0 ? "" : "not") ;
974 print "Larry Wall is $found there\n" ;
975
976 $found = ( $x->find_dup("Wall", "Harry") == 0 ? "" : "not") ;
977 print "Harry Wall is $found there\n" ;
978
979 undef $x ;
980 untie %h ;
981
982prints this
983
2c2d71f5 984 Larry Wall is there
6ca2e664
PM
985 Harry Wall is not there
986
987
988=head2 The del_dup() Method
989
990 $status = $X->del_dup($key, $value) ;
991
992This method deletes a specific key/value pair. It returns
9930 if they exist and have been deleted successfully.
994Otherwise the method returns a non-zero value.
995
b90e71be 996Again assuming the existence of the C<tree> database
6ca2e664
PM
997
998 use strict ;
999 use DB_File ;
1000
1001 use vars qw($filename $x %h $found) ;
1002
1003 my $filename = "tree" ;
1004
1005 # Enable duplicate records
1006 $DB_BTREE->{'flags'} = R_DUP ;
1007
1008 $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE
1009 or die "Cannot open $filename: $!\n";
1010
1011 $x->del_dup("Wall", "Larry") ;
1012
1013 $found = ( $x->find_dup("Wall", "Larry") == 0 ? "" : "not") ;
1014 print "Larry Wall is $found there\n" ;
1015
1016 undef $x ;
1017 untie %h ;
1018
1019prints this
1020
1021 Larry Wall is not there
1022
f6b705ef
PP
1023=head2 Matching Partial Keys
1024
1025The BTREE interface has a feature which allows partial keys to be
1026matched. This functionality is I<only> available when the C<seq> method
1027is used along with the R_CURSOR flag.
1028
1029 $x->seq($key, $value, R_CURSOR) ;
1030
1031Here is the relevant quote from the dbopen man page where it defines
1032the use of the R_CURSOR flag with seq:
1033
f6b705ef
PP
1034 Note, for the DB_BTREE access method, the returned key is not
1035 necessarily an exact match for the specified key. The returned key
1036 is the smallest key greater than or equal to the specified key,
1037 permitting partial key matches and range searches.
1038
f6b705ef
PP
1039In the example script below, the C<match> sub uses this feature to find
1040and print the first matching key/value pair given a partial key.
1041
610ab055 1042 use strict ;
f6b705ef
PP
1043 use DB_File ;
1044 use Fcntl ;
610ab055
PM
1045
1046 use vars qw($filename $x %h $st $key $value) ;
f6b705ef
PP
1047
1048 sub match
1049 {
1050 my $key = shift ;
610ab055 1051 my $value = 0;
f6b705ef
PP
1052 my $orig_key = $key ;
1053 $x->seq($key, $value, R_CURSOR) ;
1054 print "$orig_key\t-> $key\t-> $value\n" ;
1055 }
1056
1057 $filename = "tree" ;
1058 unlink $filename ;
1059
1060 $x = tie %h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_BTREE
1061 or die "Cannot open $filename: $!\n";
1062
1063 # Add some key/value pairs to the file
1064 $h{'mouse'} = 'mickey' ;
1065 $h{'Wall'} = 'Larry' ;
1066 $h{'Walls'} = 'Brick' ;
1067 $h{'Smith'} = 'John' ;
1068
1069
610ab055 1070 $key = $value = 0 ;
f6b705ef
PP
1071 print "IN ORDER\n" ;
1072 for ($st = $x->seq($key, $value, R_FIRST) ;
1073 $st == 0 ;
1074 $st = $x->seq($key, $value, R_NEXT) )
1075
2c2d71f5 1076 { print "$key -> $value\n" }
f6b705ef
PP
1077
1078 print "\nPARTIAL MATCH\n" ;
1079
1080 match "Wa" ;
1081 match "A" ;
1082 match "a" ;
1083
1084 undef $x ;
1085 untie %h ;
1086
1087Here is the output:
1088
1089 IN ORDER
1090 Smith -> John
1091 Wall -> Larry
1092 Walls -> Brick
1093 mouse -> mickey
1094
1095 PARTIAL MATCH
1096 Wa -> Wall -> Larry
1097 A -> Smith -> John
1098 a -> mouse -> mickey
1099
1100=head1 DB_RECNO
1101
1102DB_RECNO provides an interface to flat text files. Both variable and
1103fixed length records are supported.
3b35bae3 1104
6ca2e664 1105In order to make RECNO more compatible with Perl, the array offset for
88108326 1106all RECNO arrays begins at 0 rather than 1 as in Berkeley DB.
3b35bae3 1107
88108326
PP
1108As with normal Perl arrays, a RECNO array can be accessed using
1109negative indexes. The index -1 refers to the last element of the array,
1110-2 the second last, and so on. Attempting to access an element before
1111the start of the array will raise a fatal run-time error.
3b35bae3 1112
68dc0745 1113=head2 The 'bval' Option
36477c24
PP
1114
1115The operation of the bval option warrants some discussion. Here is the
1116definition of bval from the Berkeley DB 1.85 recno manual page:
1117
1118 The delimiting byte to be used to mark the end of a
1119 record for variable-length records, and the pad charac-
1120 ter for fixed-length records. If no value is speci-
1121 fied, newlines (``\n'') are used to mark the end of
1122 variable-length records and fixed-length records are
1123 padded with spaces.
1124
1125The second sentence is wrong. In actual fact bval will only default to
1126C<"\n"> when the openinfo parameter in dbopen is NULL. If a non-NULL
1127openinfo parameter is used at all, the value that happens to be in bval
1128will be used. That means you always have to specify bval when making
1129use of any of the options in the openinfo parameter. This documentation
1130error will be fixed in the next release of Berkeley DB.
1131
1132That clarifies the situation with regards Berkeley DB itself. What
1133about B<DB_File>? Well, the behavior defined in the quote above is
6ca2e664 1134quite useful, so B<DB_File> conforms to it.
36477c24
PP
1135
1136That means that you can specify other options (e.g. cachesize) and
1137still have bval default to C<"\n"> for variable length records, and
1138space for fixed length records.
1139
f6b705ef 1140=head2 A Simple Example
3b35bae3 1141
6ca2e664
PM
1142Here is a simple example that uses RECNO (if you are using a version
1143of Perl earlier than 5.004_57 this example won't work -- see
1144L<Extra RECNO Methods> for a workaround).
f6b705ef 1145
610ab055 1146 use strict ;
f6b705ef 1147 use DB_File ;
f6b705ef 1148
2c2d71f5
JH
1149 my $filename = "text" ;
1150 unlink $filename ;
1151
610ab055 1152 my @h ;
2c2d71f5 1153 tie @h, "DB_File", $filename, O_RDWR|O_CREAT, 0640, $DB_RECNO
f6b705ef
PP
1154 or die "Cannot open file 'text': $!\n" ;
1155
1156 # Add a few key/value pairs to the file
1157 $h[0] = "orange" ;
1158 $h[1] = "blue" ;
1159 $h[2] = "yellow" ;
1160
6ca2e664
PM
1161 push @h, "green", "black" ;
1162
1163 my $elements = scalar @h ;
1164 print "The array contains $elements entries\n" ;
1165
1166 my $last = pop @h ;
1167 print "popped $last\n" ;
1168
1169 unshift @h, "white" ;
1170 my $first = shift @h ;
1171 print "shifted $first\n" ;
1172
f6b705ef
PP
1173 # Check for existence of a key
1174 print "Element 1 Exists with value $h[1]\n" if $h[1] ;
1175
1176 # use a negative index
1177 print "The last element is $h[-1]\n" ;
1178 print "The 2nd last element is $h[-2]\n" ;
1179
1180 untie @h ;
3b35bae3 1181
f6b705ef
PP
1182Here is the output from the script:
1183
6ca2e664
PM
1184 The array contains 5 entries
1185 popped black
2c2d71f5 1186 shifted white
f6b705ef 1187 Element 1 Exists with value blue
6ca2e664
PM
1188 The last element is green
1189 The 2nd last element is yellow
f6b705ef 1190
6ca2e664 1191=head2 Extra RECNO Methods
f6b705ef 1192
045291aa 1193If you are using a version of Perl earlier than 5.004_57, the tied
6ca2e664
PM
1194array interface is quite limited. In the example script above
1195C<push>, C<pop>, C<shift>, C<unshift>
1196or determining the array length will not work with a tied array.
045291aa
PM
1197
1198To make the interface more useful for older versions of Perl, a number
1199of methods are supplied with B<DB_File> to simulate the missing array
1200operations. All these methods are accessed via the object returned from
1201the tie call.
f6b705ef
PP
1202
1203Here are the methods:
1204
1205=over 5
3b35bae3 1206
f6b705ef
PP
1207=item B<$X-E<gt>push(list) ;>
1208
1209Pushes the elements of C<list> to the end of the array.
1210
1211=item B<$value = $X-E<gt>pop ;>
1212
1213Removes and returns the last element of the array.
1214
1215=item B<$X-E<gt>shift>
1216
1217Removes and returns the first element of the array.
1218
1219=item B<$X-E<gt>unshift(list) ;>
1220
1221Pushes the elements of C<list> to the start of the array.
1222
1223=item B<$X-E<gt>length>
1224
1225Returns the number of elements in the array.
1226
1227=back
1228
1229=head2 Another Example
1230
1231Here is a more complete example that makes use of some of the methods
1232described above. It also makes use of the API interface directly (see
1233L<THE API INTERFACE>).
1234
1235 use strict ;
1236 use vars qw(@h $H $file $i) ;
1237 use DB_File ;
1238 use Fcntl ;
1239
1240 $file = "text" ;
1241
1242 unlink $file ;
1243
1244 $H = tie @h, "DB_File", $file, O_RDWR|O_CREAT, 0640, $DB_RECNO
1245 or die "Cannot open file $file: $!\n" ;
1246
1247 # first create a text file to play with
1248 $h[0] = "zero" ;
1249 $h[1] = "one" ;
1250 $h[2] = "two" ;
1251 $h[3] = "three" ;
1252 $h[4] = "four" ;
1253
1254
1255 # Print the records in order.
1256 #
1257 # The length method is needed here because evaluating a tied
1258 # array in a scalar context does not return the number of
1259 # elements in the array.
1260
1261 print "\nORIGINAL\n" ;
1262 foreach $i (0 .. $H->length - 1) {
1263 print "$i: $h[$i]\n" ;
1264 }
1265
1266 # use the push & pop methods
1267 $a = $H->pop ;
1268 $H->push("last") ;
1269 print "\nThe last record was [$a]\n" ;
1270
1271 # and the shift & unshift methods
1272 $a = $H->shift ;
1273 $H->unshift("first") ;
1274 print "The first record was [$a]\n" ;
1275
1276 # Use the API to add a new record after record 2.
1277 $i = 2 ;
1278 $H->put($i, "Newbie", R_IAFTER) ;
1279
1280 # and a new record before record 1.
1281 $i = 1 ;
1282 $H->put($i, "New One", R_IBEFORE) ;
1283
1284 # delete record 3
1285 $H->del(3) ;
1286
1287 # now print the records in reverse order
1288 print "\nREVERSE\n" ;
1289 for ($i = $H->length - 1 ; $i >= 0 ; -- $i)
1290 { print "$i: $h[$i]\n" }
1291
1292 # same again, but use the API functions instead
1293 print "\nREVERSE again\n" ;
610ab055 1294 my ($s, $k, $v) = (0, 0, 0) ;
f6b705ef
PP
1295 for ($s = $H->seq($k, $v, R_LAST) ;
1296 $s == 0 ;
1297 $s = $H->seq($k, $v, R_PREV))
1298 { print "$k: $v\n" }
1299
1300 undef $H ;
1301 untie @h ;
1302
1303and this is what it outputs:
1304
1305 ORIGINAL
1306 0: zero
1307 1: one
1308 2: two
1309 3: three
1310 4: four
1311
1312 The last record was [four]
1313 The first record was [zero]
1314
1315 REVERSE
1316 5: last
1317 4: three
1318 3: Newbie
1319 2: one
1320 1: New One
1321 0: first
1322
1323 REVERSE again
1324 5: last
1325 4: three
1326 3: Newbie
1327 2: one
1328 1: New One
1329 0: first
1330
1331Notes:
1332
1333=over 5
1334
1335=item 1.
1336
1337Rather than iterating through the array, C<@h> like this:
1338
1339 foreach $i (@h)
1340
1341it is necessary to use either this:
1342
1343 foreach $i (0 .. $H->length - 1)
1344
1345or this:
1346
1347 for ($a = $H->get($k, $v, R_FIRST) ;
1348 $a == 0 ;
1349 $a = $H->get($k, $v, R_NEXT) )
1350
1351=item 2.
1352
1353Notice that both times the C<put> method was used the record index was
1354specified using a variable, C<$i>, rather than the literal value
1355itself. This is because C<put> will return the record number of the
1356inserted line via that parameter.
1357
1358=back
1359
1360=head1 THE API INTERFACE
3b35bae3
AD
1361
1362As well as accessing Berkeley DB using a tied hash or array, it is also
88108326 1363possible to make direct use of most of the API functions defined in the
8e07c86e 1364Berkeley DB documentation.
3b35bae3 1365
88108326 1366To do this you need to store a copy of the object returned from the tie.
3b35bae3 1367
88108326 1368 $db = tie %hash, "DB_File", "filename" ;
3b35bae3 1369
8e07c86e 1370Once you have done that, you can access the Berkeley DB API functions
88108326 1371as B<DB_File> methods directly like this:
3b35bae3
AD
1372
1373 $db->put($key, $value, R_NOOVERWRITE) ;
1374
88108326
PP
1375B<Important:> If you have saved a copy of the object returned from
1376C<tie>, the underlying database file will I<not> be closed until both
1377the tied variable is untied and all copies of the saved object are
610ab055 1378destroyed.
88108326
PP
1379
1380 use DB_File ;
1381 $db = tie %hash, "DB_File", "filename"
1382 or die "Cannot tie filename: $!" ;
1383 ...
1384 undef $db ;
1385 untie %hash ;
1386
9a2c4ce3 1387See L<The untie() Gotcha> for more details.
778183f3 1388
88108326
PP
1389All the functions defined in L<dbopen> are available except for
1390close() and dbopen() itself. The B<DB_File> method interface to the
1391supported functions have been implemented to mirror the way Berkeley DB
1392works whenever possible. In particular note that:
1393
1394=over 5
1395
1396=item *
1397
1398The methods return a status value. All return 0 on success.
1399All return -1 to signify an error and set C<$!> to the exact
1400error code. The return code 1 generally (but not always) means that the
1401key specified did not exist in the database.
1402
1403Other return codes are defined. See below and in the Berkeley DB
1404documentation for details. The Berkeley DB documentation should be used
1405as the definitive source.
1406
1407=item *
3b35bae3 1408
88108326
PP
1409Whenever a Berkeley DB function returns data via one of its parameters,
1410the equivalent B<DB_File> method does exactly the same.
3b35bae3 1411
88108326
PP
1412=item *
1413
1414If you are careful, it is possible to mix API calls with the tied
1415hash/array interface in the same piece of code. Although only a few of
1416the methods used to implement the tied interface currently make use of
1417the cursor, you should always assume that the cursor has been changed
1418any time the tied hash/array interface is used. As an example, this
1419code will probably not do what you expect:
1420
1421 $X = tie %x, 'DB_File', $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE
1422 or die "Cannot tie $filename: $!" ;
1423
1424 # Get the first key/value pair and set the cursor
1425 $X->seq($key, $value, R_FIRST) ;
1426
1427 # this line will modify the cursor
1428 $count = scalar keys %x ;
1429
1430 # Get the second key/value pair.
1431 # oops, it didn't, it got the last key/value pair!
1432 $X->seq($key, $value, R_NEXT) ;
1433
1434The code above can be rearranged to get around the problem, like this:
1435
1436 $X = tie %x, 'DB_File', $filename, O_RDWR|O_CREAT, 0777, $DB_BTREE
1437 or die "Cannot tie $filename: $!" ;
1438
1439 # this line will modify the cursor
1440 $count = scalar keys %x ;
1441
1442 # Get the first key/value pair and set the cursor
1443 $X->seq($key, $value, R_FIRST) ;
1444
1445 # Get the second key/value pair.
1446 # worked this time.
1447 $X->seq($key, $value, R_NEXT) ;
1448
1449=back
1450
1451All the constants defined in L<dbopen> for use in the flags parameters
1452in the methods defined below are also available. Refer to the Berkeley
1453DB documentation for the precise meaning of the flags values.
1454
1455Below is a list of the methods available.
3b35bae3
AD
1456
1457=over 5
1458
f6b705ef 1459=item B<$status = $X-E<gt>get($key, $value [, $flags]) ;>
88108326
PP
1460
1461Given a key (C<$key>) this method reads the value associated with it
1462from the database. The value read from the database is returned in the
1463C<$value> parameter.
3b35bae3 1464
88108326 1465If the key does not exist the method returns 1.
3b35bae3 1466
88108326 1467No flags are currently defined for this method.
3b35bae3 1468
f6b705ef 1469=item B<$status = $X-E<gt>put($key, $value [, $flags]) ;>
3b35bae3 1470
88108326
PP
1471Stores the key/value pair in the database.
1472
1473If you use either the R_IAFTER or R_IBEFORE flags, the C<$key> parameter
8e07c86e 1474will have the record number of the inserted key/value pair set.
3b35bae3 1475
88108326
PP
1476Valid flags are R_CURSOR, R_IAFTER, R_IBEFORE, R_NOOVERWRITE and
1477R_SETCURSOR.
1478
f6b705ef 1479=item B<$status = $X-E<gt>del($key [, $flags]) ;>
3b35bae3 1480
88108326 1481Removes all key/value pairs with key C<$key> from the database.
3b35bae3 1482
88108326
PP
1483A return code of 1 means that the requested key was not in the
1484database.
3b35bae3 1485
88108326 1486R_CURSOR is the only valid flag at present.
3b35bae3 1487
f6b705ef 1488=item B<$status = $X-E<gt>fd ;>
3b35bae3 1489
88108326 1490Returns the file descriptor for the underlying database.
3b35bae3 1491
b90e71be
GS
1492See L<Locking: The Trouble with fd> for an explanation for why you should
1493not use C<fd> to lock your database.
3b35bae3 1494
f6b705ef 1495=item B<$status = $X-E<gt>seq($key, $value, $flags) ;>
3b35bae3 1496
88108326
PP
1497This interface allows sequential retrieval from the database. See
1498L<dbopen> for full details.
1499
1500Both the C<$key> and C<$value> parameters will be set to the key/value
1501pair read from the database.
1502
1503The flags parameter is mandatory. The valid flag values are R_CURSOR,
1504R_FIRST, R_LAST, R_NEXT and R_PREV.
1505
f6b705ef 1506=item B<$status = $X-E<gt>sync([$flags]) ;>
88108326
PP
1507
1508Flushes any cached buffers to disk.
1509
1510R_RECNOSYNC is the only valid flag at present.
3b35bae3
AD
1511
1512=back
1513
cad2e5aa
JH
1514=head1 DBM FILTERS
1515
1516A DBM Filter is a piece of code that is be used when you I<always>
1517want to make the same transformation to all keys and/or values in a
1518DBM database.
1519
1520There are four methods associated with DBM Filters. All work identically,
1521and each is used to install (or uninstall) a single DBM Filter. Each
1522expects a single parameter, namely a reference to a sub. The only
1523difference between them is the place that the filter is installed.
1524
1525To summarise:
1526
1527=over 5
1528
1529=item B<filter_store_key>
1530
1531If a filter has been installed with this method, it will be invoked
1532every time you write a key to a DBM database.
1533
1534=item B<filter_store_value>
1535
1536If a filter has been installed with this method, it will be invoked
1537every time you write a value to a DBM database.
1538
1539
1540=item B<filter_fetch_key>
1541
1542If a filter has been installed with this method, it will be invoked
1543every time you read a key from a DBM database.
1544
1545=item B<filter_fetch_value>
1546
1547If a filter has been installed with this method, it will be invoked
1548every time you read a value from a DBM database.
1549
1550=back
1551
1552You can use any combination of the methods, from none, to all four.
1553
1554All filter methods return the existing filter, if present, or C<undef>
1555in not.
1556
1557To delete a filter pass C<undef> to it.
1558
1559=head2 The Filter
1560
1561When each filter is called by Perl, a local copy of C<$_> will contain
1562the key or value to be filtered. Filtering is achieved by modifying
1563the contents of C<$_>. The return code from the filter is ignored.
1564
1565=head2 An Example -- the NULL termination problem.
1566
1567Consider the following scenario. You have a DBM database
1568that you need to share with a third-party C application. The C application
1569assumes that I<all> keys and values are NULL terminated. Unfortunately
1570when Perl writes to DBM databases it doesn't use NULL termination, so
1571your Perl application will have to manage NULL termination itself. When
1572you write to the database you will have to use something like this:
1573
1574 $hash{"$key\0"} = "$value\0" ;
1575
1576Similarly the NULL needs to be taken into account when you are considering
1577the length of existing keys/values.
1578
1579It would be much better if you could ignore the NULL terminations issue
1580in the main application code and have a mechanism that automatically
1581added the terminating NULL to all keys and values whenever you write to
1582the database and have them removed when you read from the database. As I'm
1583sure you have already guessed, this is a problem that DBM Filters can
1584fix very easily.
1585
1586 use strict ;
1587 use DB_File ;
1588
1589 my %hash ;
1590 my $filename = "/tmp/filt" ;
1591 unlink $filename ;
1592
1593 my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH
1594 or die "Cannot open $filename: $!\n" ;
1595
1596 # Install DBM Filters
1597 $db->filter_fetch_key ( sub { s/\0$// } ) ;
1598 $db->filter_store_key ( sub { $_ .= "\0" } ) ;
1599 $db->filter_fetch_value( sub { s/\0$// } ) ;
1600 $db->filter_store_value( sub { $_ .= "\0" } ) ;
1601
1602 $hash{"abc"} = "def" ;
1603 my $a = $hash{"ABC"} ;
1604 # ...
1605 undef $db ;
1606 untie %hash ;
1607
1608Hopefully the contents of each of the filters should be
1609self-explanatory. Both "fetch" filters remove the terminating NULL,
1610and both "store" filters add a terminating NULL.
1611
1612
1613=head2 Another Example -- Key is a C int.
1614
1615Here is another real-life example. By default, whenever Perl writes to
1616a DBM database it always writes the key and value as strings. So when
1617you use this:
1618
1619 $hash{12345} = "soemthing" ;
1620
1621the key 12345 will get stored in the DBM database as the 5 byte string
1622"12345". If you actually want the key to be stored in the DBM database
1623as a C int, you will have to use C<pack> when writing, and C<unpack>
1624when reading.
1625
1626Here is a DBM Filter that does it:
1627
1628 use strict ;
1629 use DB_File ;
1630 my %hash ;
1631 my $filename = "/tmp/filt" ;
1632 unlink $filename ;
1633
1634
1635 my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666, $DB_HASH
1636 or die "Cannot open $filename: $!\n" ;
1637
1638 $db->filter_fetch_key ( sub { $_ = unpack("i", $_) } ) ;
1639 $db->filter_store_key ( sub { $_ = pack ("i", $_) } ) ;
1640 $hash{123} = "def" ;
1641 # ...
1642 undef $db ;
1643 untie %hash ;
1644
1645This time only two filters have been used -- we only need to manipulate
1646the contents of the key, so it wasn't necessary to install any value
1647filters.
1648
f6b705ef 1649=head1 HINTS AND TIPS
3b35bae3 1650
3b35bae3 1651
b90e71be 1652=head2 Locking: The Trouble with fd
3b35bae3 1653
b90e71be
GS
1654Until version 1.72 of this module, the recommended technique for locking
1655B<DB_File> databases was to flock the filehandle returned from the "fd"
1656function. Unfortunately this technique has been shown to be fundamentally
1657flawed (Kudos to David Harris for tracking this down). Use it at your own
1658peril!
3b35bae3 1659
b90e71be 1660The locking technique went like this.
cb1a09d0 1661
b90e71be
GS
1662 $db = tie(%db, 'DB_File', '/tmp/foo.db', O_CREAT|O_RDWR, 0644)
1663 || die "dbcreat /tmp/foo.db $!";
1664 $fd = $db->fd;
1665 open(DB_FH, "+<&=$fd") || die "dup $!";
1666 flock (DB_FH, LOCK_EX) || die "flock: $!";
1667 ...
1668 $db{"Tom"} = "Jerry" ;
1669 ...
1670 flock(DB_FH, LOCK_UN);
1671 undef $db;
1672 untie %db;
1673 close(DB_FH);
cb1a09d0 1674
b90e71be 1675In simple terms, this is what happens:
cb1a09d0 1676
b90e71be 1677=over 5
cb1a09d0 1678
b90e71be 1679=item 1.
cb1a09d0 1680
b90e71be 1681Use "tie" to open the database.
cb1a09d0 1682
b90e71be 1683=item 2.
cb1a09d0 1684
b90e71be 1685Lock the database with fd & flock.
cb1a09d0 1686
b90e71be 1687=item 3.
cb1a09d0 1688
b90e71be 1689Read & Write to the database.
cb1a09d0 1690
b90e71be 1691=item 4.
cb1a09d0 1692
b90e71be 1693Unlock and close the database.
cb1a09d0 1694
b90e71be
GS
1695=back
1696
1697Here is the crux of the problem. A side-effect of opening the B<DB_File>
1698database in step 2 is that an initial block from the database will get
1699read from disk and cached in memory.
1700
1701To see why this is a problem, consider what can happen when two processes,
1702say "A" and "B", both want to update the same B<DB_File> database
1703using the locking steps outlined above. Assume process "A" has already
1704opened the database and has a write lock, but it hasn't actually updated
1705the database yet (it has finished step 2, but not started step 3 yet). Now
1706process "B" tries to open the same database - step 1 will succeed,
1707but it will block on step 2 until process "A" releases the lock. The
1708important thing to notice here is that at this point in time both
1709processes will have cached identical initial blocks from the database.
1710
1711Now process "A" updates the database and happens to change some of the
1712data held in the initial buffer. Process "A" terminates, flushing
1713all cached data to disk and releasing the database lock. At this point
1714the database on disk will correctly reflect the changes made by process
1715"A".
1716
1717With the lock released, process "B" can now continue. It also updates the
1718database and unfortunately it too modifies the data that was in its
1719initial buffer. Once that data gets flushed to disk it will overwrite
1720some/all of the changes process "A" made to the database.
1721
1722The result of this scenario is at best a database that doesn't contain
1723what you expect. At worst the database will corrupt.
1724
1725The above won't happen every time competing process update the same
1726B<DB_File> database, but it does illustrate why the technique should
1727not be used.
1728
1729=head2 Safe ways to lock a database
1730
1731Starting with version 2.x, Berkeley DB has internal support for locking.
1732The companion module to this one, B<BerkeleyDB>, provides an interface
1733to this locking functionality. If you are serious about locking
1734Berkeley DB databases, I strongly recommend using B<BerkeleyDB>.
1735
1736If using B<BerkeleyDB> isn't an option, there are a number of modules
1737available on CPAN that can be used to implement locking. Each one
1738implements locking differently and has different goals in mind. It is
1739therefore worth knowing the difference, so that you can pick the right
1740one for your application. Here are the three locking wrappers:
1741
1742=over 5
1743
1744=item B<Tie::DB_Lock>
1745
1746A B<DB_File> wrapper which creates copies of the database file for
1747read access, so that you have a kind of a multiversioning concurrent read
1748system. However, updates are still serial. Use for databases where reads
1749may be lengthy and consistency problems may occur.
1750
1751=item B<Tie::DB_LockFile>
1752
1753A B<DB_File> wrapper that has the ability to lock and unlock the database
1754while it is being used. Avoids the tie-before-flock problem by simply
1755re-tie-ing the database when you get or drop a lock. Because of the
1756flexibility in dropping and re-acquiring the lock in the middle of a
1757session, this can be massaged into a system that will work with long
1758updates and/or reads if the application follows the hints in the POD
1759documentation.
1760
1761=item B<DB_File::Lock>
1762
1763An extremely lightweight B<DB_File> wrapper that simply flocks a lockfile
1764before tie-ing the database and drops the lock after the untie. Allows
1765one to use the same lockfile for multiple databases to avoid deadlock
1766problems, if desired. Use for databases where updates are reads are
1767quick and simple flock locking semantics are enough.
1768
1769=back
cb1a09d0 1770
68dc0745 1771=head2 Sharing Databases With C Applications
f6b705ef
PP
1772
1773There is no technical reason why a Berkeley DB database cannot be
1774shared by both a Perl and a C application.
1775
1776The vast majority of problems that are reported in this area boil down
1777to the fact that C strings are NULL terminated, whilst Perl strings are
cad2e5aa 1778not. See L<DBM FILTERS> for a generic way to work around this problem.
f6b705ef
PP
1779
1780Here is a real example. Netscape 2.0 keeps a record of the locations you
1781visit along with the time you last visited them in a DB_HASH database.
1782This is usually stored in the file F<~/.netscape/history.db>. The key
1783field in the database is the location string and the value field is the
1784time the location was last visited stored as a 4 byte binary value.
1785
1786If you haven't already guessed, the location string is stored with a
1787terminating NULL. This means you need to be careful when accessing the
1788database.
1789
1790Here is a snippet of code that is loosely based on Tom Christiansen's
1791I<ggh> script (available from your nearest CPAN archive in
1792F<authors/id/TOMC/scripts/nshist.gz>).
1793
610ab055 1794 use strict ;
f6b705ef
PP
1795 use DB_File ;
1796 use Fcntl ;
f6b705ef 1797
610ab055 1798 use vars qw( $dotdir $HISTORY %hist_db $href $binary_time $date ) ;
f6b705ef
PP
1799 $dotdir = $ENV{HOME} || $ENV{LOGNAME};
1800
1801 $HISTORY = "$dotdir/.netscape/history.db";
1802
1803 tie %hist_db, 'DB_File', $HISTORY
1804 or die "Cannot open $HISTORY: $!\n" ;;
1805
1806 # Dump the complete database
1807 while ( ($href, $binary_time) = each %hist_db ) {
1808
1809 # remove the terminating NULL
1810 $href =~ s/\x00$// ;
1811
1812 # convert the binary time into a user friendly string
1813 $date = localtime unpack("V", $binary_time);
1814 print "$date $href\n" ;
1815 }
1816
1817 # check for the existence of a specific key
1818 # remember to add the NULL
1819 if ( $binary_time = $hist_db{"http://mox.perl.com/\x00"} ) {
1820 $date = localtime unpack("V", $binary_time) ;
1821 print "Last visited mox.perl.com on $date\n" ;
1822 }
1823 else {
1824 print "Never visited mox.perl.com\n"
1825 }
1826
1827 untie %hist_db ;
1828
68dc0745 1829=head2 The untie() Gotcha
778183f3 1830
7a2e2cd6 1831If you make use of the Berkeley DB API, it is I<very> strongly
68dc0745 1832recommended that you read L<perltie/The untie Gotcha>.
778183f3
PM
1833
1834Even if you don't currently make use of the API interface, it is still
1835worth reading it.
1836
1837Here is an example which illustrates the problem from a B<DB_File>
1838perspective:
1839
1840 use DB_File ;
1841 use Fcntl ;
1842
1843 my %x ;
1844 my $X ;
1845
1846 $X = tie %x, 'DB_File', 'tst.fil' , O_RDWR|O_TRUNC
1847 or die "Cannot tie first time: $!" ;
1848
1849 $x{123} = 456 ;
1850
1851 untie %x ;
1852
1853 tie %x, 'DB_File', 'tst.fil' , O_RDWR|O_CREAT
1854 or die "Cannot tie second time: $!" ;
1855
1856 untie %x ;
1857
1858When run, the script will produce this error message:
1859
1860 Cannot tie second time: Invalid argument at bad.file line 14.
1861
1862Although the error message above refers to the second tie() statement
1863in the script, the source of the problem is really with the untie()
1864statement that precedes it.
1865
1866Having read L<perltie> you will probably have already guessed that the
1867error is caused by the extra copy of the tied object stored in C<$X>.
1868If you haven't, then the problem boils down to the fact that the
1869B<DB_File> destructor, DESTROY, will not be called until I<all>
1870references to the tied object are destroyed. Both the tied variable,
1871C<%x>, and C<$X> above hold a reference to the object. The call to
1872untie() will destroy the first, but C<$X> still holds a valid
1873reference, so the destructor will not get called and the database file
1874F<tst.fil> will remain open. The fact that Berkeley DB then reports the
b90e71be 1875attempt to open a database that is already open via the catch-all
778183f3
PM
1876"Invalid argument" doesn't help.
1877
1878If you run the script with the C<-w> flag the error message becomes:
1879
1880 untie attempted while 1 inner references still exist at bad.file line 12.
1881 Cannot tie second time: Invalid argument at bad.file line 14.
1882
1883which pinpoints the real problem. Finally the script can now be
1884modified to fix the original problem by destroying the API object
1885before the untie:
1886
1887 ...
1888 $x{123} = 456 ;
1889
1890 undef $X ;
1891 untie %x ;
1892
1893 $X = tie %x, 'DB_File', 'tst.fil' , O_RDWR|O_CREAT
1894 ...
1895
f6b705ef
PP
1896
1897=head1 COMMON QUESTIONS
1898
1899=head2 Why is there Perl source in my database?
1900
1901If you look at the contents of a database file created by DB_File,
1902there can sometimes be part of a Perl script included in it.
1903
1904This happens because Berkeley DB uses dynamic memory to allocate
1905buffers which will subsequently be written to the database file. Being
1906dynamic, the memory could have been used for anything before DB
1907malloced it. As Berkeley DB doesn't clear the memory once it has been
1908allocated, the unused portions will contain random junk. In the case
1909where a Perl script gets written to the database, the random junk will
1910correspond to an area of dynamic memory that happened to be used during
1911the compilation of the script.
1912
1913Unless you don't like the possibility of there being part of your Perl
1914scripts embedded in a database file, this is nothing to worry about.
1915
1916=head2 How do I store complex data structures with DB_File?
1917
1918Although B<DB_File> cannot do this directly, there is a module which
1919can layer transparently over B<DB_File> to accomplish this feat.
1920
1921Check out the MLDBM module, available on CPAN in the directory
1922F<modules/by-module/MLDBM>.
1923
1924=head2 What does "Invalid Argument" mean?
1925
1926You will get this error message when one of the parameters in the
1927C<tie> call is wrong. Unfortunately there are quite a few parameters to
1928get wrong, so it can be difficult to figure out which one it is.
1929
1930Here are a couple of possibilities:
1931
1932=over 5
1933
1934=item 1.
1935
610ab055 1936Attempting to reopen a database without closing it.
f6b705ef
PP
1937
1938=item 2.
1939
1940Using the O_WRONLY flag.
1941
1942=back
1943
1944=head2 What does "Bareword 'DB_File' not allowed" mean?
1945
1946You will encounter this particular error message when you have the
1947C<strict 'subs'> pragma (or the full strict pragma) in your script.
1948Consider this script:
1949
1950 use strict ;
1951 use DB_File ;
1952 use vars qw(%x) ;
1953 tie %x, DB_File, "filename" ;
1954
1955Running it produces the error in question:
1956
1957 Bareword "DB_File" not allowed while "strict subs" in use
1958
1959To get around the error, place the word C<DB_File> in either single or
1960double quotes, like this:
1961
1962 tie %x, "DB_File", "filename" ;
1963
1964Although it might seem like a real pain, it is really worth the effort
1965of having a C<use strict> in all your scripts.
1966
cad2e5aa
JH
1967=head1 REFERENCES
1968
1969Articles that are either about B<DB_File> or make use of it.
1970
1971=over 5
1972
1973=item 1.
1974
1975I<Full-Text Searching in Perl>, Tim Kientzle (tkientzle@ddj.com),
1976Dr. Dobb's Journal, Issue 295, January 1999, pp 34-41
1977
1978=back
1979
cb1a09d0
AD
1980=head1 HISTORY
1981
1f70e1ea 1982Moved to the Changes file.
610ab055 1983
1f70e1ea 1984=head1 BUGS
05475680 1985
1f70e1ea
PM
1986Some older versions of Berkeley DB had problems with fixed length
1987records using the RECNO file format. This problem has been fixed since
1988version 1.85 of Berkeley DB.
e858de61 1989
1f70e1ea
PM
1990I am sure there are bugs in the code. If you do find any, or can
1991suggest any enhancements, I would welcome your comments.
a6ed719b 1992
1f70e1ea 1993=head1 AVAILABILITY
a6ed719b 1994
1f70e1ea
PM
1995B<DB_File> comes with the standard Perl source distribution. Look in
1996the directory F<ext/DB_File>. Given the amount of time between releases
1997of Perl the version that ships with Perl is quite likely to be out of
1998date, so the most recent version can always be found on CPAN (see
1999L<perlmod/CPAN> for details), in the directory
2000F<modules/by-module/DB_File>.
a6ed719b 2001
039d031f
PM
2002This version of B<DB_File> will work with either version 1.x, 2.x or
20033.x of Berkeley DB, but is limited to the functionality provided by
2004version 1.
a6ed719b 2005
cad2e5aa 2006The official web site for Berkeley DB is F<http://www.sleepycat.com>.
039d031f 2007All versions of Berkeley DB are available there.
93af7a87 2008
1f70e1ea
PM
2009Alternatively, Berkeley DB version 1 is available at your nearest CPAN
2010archive in F<src/misc/db.1.85.tar.gz>.
e858de61 2011
1f70e1ea
PM
2012If you are running IRIX, then get Berkeley DB version 1 from
2013F<http://reality.sgi.com/ariel>. It has the patches necessary to
2014compile properly on IRIX 5.3.
610ab055 2015
1f70e1ea 2016=head1 COPYRIGHT
3b35bae3 2017
cad2e5aa 2018Copyright (c) 1995-1999 Paul Marquess. All rights reserved. This program
a9fd575d
PM
2019is free software; you can redistribute it and/or modify it under the
2020same terms as Perl itself.
3b35bae3 2021
1f70e1ea
PM
2022Although B<DB_File> is covered by the Perl license, the library it
2023makes use of, namely Berkeley DB, is not. Berkeley DB has its own
2024copyright and its own license. Please take the time to read it.
3b35bae3 2025
a9fd575d 2026Here are are few words taken from the Berkeley DB FAQ (at
b90e71be 2027F<http://www.sleepycat.com>) regarding the license:
68dc0745 2028
a9fd575d 2029 Do I have to license DB to use it in Perl scripts?
3b35bae3 2030
a9fd575d
PM
2031 No. The Berkeley DB license requires that software that uses
2032 Berkeley DB be freely redistributable. In the case of Perl, that
2033 software is Perl, and not your scripts. Any Perl scripts that you
2034 write are your property, including scripts that make use of
2035 Berkeley DB. Neither the Perl license nor the Berkeley DB license
2036 place any restriction on what you may do with them.
88108326 2037
1f70e1ea
PM
2038If you are in any doubt about the license situation, contact either the
2039Berkeley DB authors or the author of DB_File. See L<"AUTHOR"> for details.
a0b8c8c1
PM
2040
2041
3b35bae3
AD
2042=head1 SEE ALSO
2043
9fe6733a
PM
2044L<perl(1)>, L<dbopen(3)>, L<hash(3)>, L<recno(3)>, L<btree(3)>,
2045L<dbmfilter>
3b35bae3 2046
3b35bae3
AD
2047=head1 AUTHOR
2048
8e07c86e 2049The DB_File interface was written by Paul Marquess
6ca2e664 2050E<lt>Paul.Marquess@btinternet.comE<gt>.
d3ef3b8a
PM
2051Questions about the DB system itself may be addressed to
2052E<lt>db@sleepycat.com<gt>.
3b35bae3
AD
2053
2054=cut