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