1BerkeleyDB(3) User Contributed Perl Documentation BerkeleyDB(3)
2
6 BerkeleyDB - Perl extension for Berkeley DB version 2, 3 or 4
7
9 use BerkeleyDB;
10 $env = new BerkeleyDB::Env [OPTIONS] ;
12 $db = tie %hash, 'BerkeleyDB::Hash', [OPTIONS] ;
14 $db = new BerkeleyDB::Hash [OPTIONS] ;
15 $db = tie %hash, 'BerkeleyDB::Btree', [OPTIONS] ;
17 $db = new BerkeleyDB::Btree [OPTIONS] ;
18 $db = tie @array, 'BerkeleyDB::Recno', [OPTIONS] ;
20 $db = new BerkeleyDB::Recno [OPTIONS] ;
21 $db = tie @array, 'BerkeleyDB::Queue', [OPTIONS] ;
23 $db = new BerkeleyDB::Queue [OPTIONS] ;
24 $db = new BerkeleyDB::Unknown [OPTIONS] ;
26 $status = BerkeleyDB::db_remove [OPTIONS]
28 $status = BerkeleyDB::db_rename [OPTIONS]
29 $status = BerkeleyDB::db_verify [OPTIONS]
30 $hash{$key} = $value ;
32 $value = $hash{$key} ;
33 each %hash ;
34 keys %hash ;
35 values %hash ;
36 $status = $db->db_get()
38 $status = $db->db_put() ;
39 $status = $db->db_del() ;
40 $status = $db->db_sync() ;
41 $status = $db->db_close() ;
42 $status = $db->db_pget()
43 $hash_ref = $db->db_stat() ;
44 $status = $db->db_key_range();
45 $type = $db->type() ;
46 $status = $db->status() ;
47 $boolean = $db->byteswapped() ;
48 $status = $db->truncate($count) ;
49 $status = $db->compact($start, $stop, $c_data, $flags, $end);
50 $bool = $env->cds_enabled();
52 $bool = $db->cds_enabled();
53 $lock = $db->cds_lock();
54 $lock->cds_unlock();
55 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;
57 ($flag, $old_offset, $old_length) = $db->partial_clear() ;
58 $cursor = $db->db_cursor([$flags]) ;
60 $newcursor = $cursor->c_dup([$flags]);
61 $status = $cursor->c_get() ;
62 $status = $cursor->c_put() ;
63 $status = $cursor->c_del() ;
64 $status = $cursor->c_count() ;
65 $status = $cursor->c_pget() ;
66 $status = $cursor->status() ;
67 $status = $cursor->c_close() ;
68 $cursor = $db->db_join() ;
70 $status = $cursor->c_get() ;
71 $status = $cursor->c_close() ;
72 $status = $env->txn_checkpoint()
74 $hash_ref = $env->txn_stat()
75 $status = $env->setmutexlocks()
76 $status = $env->set_flags()
77 $status = $env->set_timeout()
78 $status = $env->lsn_reset()
79 $txn = $env->txn_begin() ;
81 $db->Txn($txn);
82 $txn->Txn($db1, $db2,...);
83 $status = $txn->txn_prepare()
84 $status = $txn->txn_commit()
85 $status = $txn->txn_abort()
86 $status = $txn->txn_id()
87 $status = $txn->txn_discard()
88 $status = $txn->set_timeout()
89 $status = $env->set_lg_dir();
91 $status = $env->set_lg_bsize();
92 $status = $env->set_lg_max();
93 $status = $env->set_data_dir() ;
95 $status = $env->set_tmp_dir() ;
96 $status = $env->set_verbose() ;
97 $db_env_ptr = $env->DB_ENV() ;
98 $BerkeleyDB::Error
100 $BerkeleyDB::db_version
101 # DBM Filters
103 $old_filter = $db->filter_store_key ( sub { ... } ) ;
104 $old_filter = $db->filter_store_value( sub { ... } ) ;
105 $old_filter = $db->filter_fetch_key ( sub { ... } ) ;
106 $old_filter = $db->filter_fetch_value( sub { ... } ) ;
107 # deprecated, but supported
109 $txn_mgr = $env->TxnMgr();
110 $status = $txn_mgr->txn_checkpoint()
111 $hash_ref = $txn_mgr->txn_stat()
112 $txn = $txn_mgr->txn_begin() ;
113
115 NOTE: This document is still under construction. Expect it to be incom‐
116 plete in places.
117 This Perl module provides an interface to most of the functionality
119 available in Berkeley DB versions 2, 3 and 4. In general it is safe to
120 assume that the interface provided here to be identical to the Berkeley
121 DB interface. The main changes have been to make the Berkeley DB API
122 work in a Perl way. Note that if you are using Berkeley DB 2.x, the new
123 features available in Berkeley DB 3.x or DB 4.x are not available via
124 this module.
125 The reader is expected to be familiar with the Berkeley DB documenta‐
127 tion. Where the interface provided here is identical to the Berkeley DB
128 library and the... TODO
129 The db_appinit, db_cursor, db_open and db_txn man pages are particu‐
131 larly relevant.
132 The interface to Berkeley DB is implemented with a number of Perl
134 classes.
135
137 The BerkeleyDB::Env class provides an interface to the Berkeley DB
138 function db_appinit in Berkeley DB 2.x or db_env_create and DBENV->open
139 in Berkeley DB 3.x/4.x. Its purpose is to initialise a number of sub-
140 systems that can then be used in a consistent way in all the databases
141 you make use of in the environment.
142 If you don't intend using transactions, locking or logging, then you
144 shouldn't need to make use of BerkeleyDB::Env.
145 Note that an environment consists of a number of files that Berkeley DB
147 manages behind the scenes for you. When you first use an environment,
148 it needs to be explicitly created. This is done by including "DB_CRE‐
149 ATE" with the "Flags" parameter, described below.
150 Synopsis
152 $env = new BerkeleyDB::Env
154 [ -Home => $path, ]
155 [ -Server => $name, ]
156 [ -CacheSize => $number, ]
157 [ -Config => { name => value, name => value }, ]
158 [ -ErrFile => filename, ]
159 [ -ErrPrefix => "string", ]
160 [ -Flags => number, ]
161 [ -SetFlags => bitmask, ]
162 [ -LockDetect => number, ]
163 [ -SharedMemKey => number, ]
164 [ -Verbose => boolean, ]
165 [ -Encrypt => { Password => "string",
166 Flags => number }, ]
167 All the parameters to the BerkeleyDB::Env constructor are optional.
169 -Home
171 If present, this parameter should point to an existing directory.
172 Any files that aren't specified with an absolute path in the sub-
173 systems that are initialised by the BerkeleyDB::Env class will be
174 assumed to live in the Home directory.
175 For example, in the code fragment below the database "fred.db"
177 will be opened in the directory "/home/databases" because it was
178 specified as a relative path, but "joe.db" will be opened in
179 "/other" because it was part of an absolute path.
180 $env = new BerkeleyDB::Env
182 -Home => "/home/databases"
183 ...
184 $db1 = new BerkeleyDB::Hash
186 -Filename => "fred.db",
187 -Env => $env
188 ...
189 $db2 = new BerkeleyDB::Hash
191 -Filename => "/other/joe.db",
192 -Env => $env
193 ...
194 -Server
196 If present, this parameter should be the hostname of a server that
197 is running the Berkeley DB RPC server. All databases will be
198 accessed via the RPC server.
199 -Encrypt
201 If present, this parameter will enable encryption of all data
202 before it is written to the database. This parameters must be
203 given a hash reference. The format is shown below.
204 -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES }
206 Valid values for the Flags are 0 or "DB_ENCRYPT_AES".
208 This option requires Berkeley DB 4.1 or better.
210 -Cachesize
212 If present, this parameter sets the size of the environments
213 shared memory buffer pool.
214 -SharedMemKey
216 If present, this parameter sets the base segment ID for the shared
217 memory region used by Berkeley DB.
218 This option requires Berkeley DB 3.1 or better.
220 Use "$env->get_shm_key($id)" to find out the base segment ID used
222 once the environment is open.
223 -Config
225 This is a variation on the "-Home" parameter, but it allows finer
226 control of where specific types of files will be stored.
227 The parameter expects a reference to a hash. Valid keys are:
229 DB_DATA_DIR, DB_LOG_DIR and DB_TMP_DIR
230 The code below shows an example of how it can be used.
232 $env = new BerkeleyDB::Env
234 -Config => { DB_DATA_DIR => "/home/databases",
235 DB_LOG_DIR => "/home/logs",
236 DB_TMP_DIR => "/home/tmp"
237 }
238 ...
239 -ErrFile
241 Expects a filename or filenhandle. Any errors generated internally
242 by Berkeley DB will be logged to this file. A useful debug setting
243 is to open environments with either
244 -ErrFile => *STDOUT
246 or
248 -ErrFile => *STDERR
250 -ErrPrefix
252 Allows a prefix to be added to the error messages before they are
253 sent to -ErrFile.
254 -Flags
256 The Flags parameter specifies both which sub-systems to ini‐
257 tialise, as well as a number of environment-wide options. See the
258 Berkeley DB documentation for more details of these options.
259 Any of the following can be specified by OR'ing them:
261 DB_CREATE
263 If any of the files specified do not already exist, create them.
265 DB_INIT_CDB
267 Initialise the Concurrent Access Methods
269 DB_INIT_LOCK
271 Initialise the Locking sub-system.
273 DB_INIT_LOG
275 Initialise the Logging sub-system.
277 DB_INIT_MPOOL
279 Initialise the ...
281 DB_INIT_TXN
283 Initialise the ...
285 DB_MPOOL_PRIVATE
287 Initialise the ...
289 DB_INIT_MPOOL is also specified.
291 Initialise the ...
293 DB_NOMMAP
295 Initialise the ...
297 DB_RECOVER
299 DB_RECOVER_FATAL
301 DB_THREAD
303 DB_TXN_NOSYNC
305 DB_USE_ENVIRON
307 DB_USE_ENVIRON_ROOT
309 -SetFlags
311 Calls ENV->set_flags with the supplied bitmask. Use this when you
312 need to make use of DB_ENV->set_flags before DB_ENV->open is
313 called.
314 Only valid when Berkeley DB 3.x or better is used.
316 -LockDetect
318 Specifies what to do when a lock conflict occurs. The value should
319 be one of
320 DB_LOCK_DEFAULT
322 DB_LOCK_OLDEST
324 DB_LOCK_RANDOM
326 DB_LOCK_YOUNGEST
328 -Verbose
330 Add extra debugging information to the messages sent to -ErrFile.
331 Methods
333 The environment class has the following methods:
335 $env->errPrefix("string") ;
337 This method is identical to the -ErrPrefix flag. It allows the
338 error prefix string to be changed dynamically.
339 $env->set_flags(bitmask, 1⎪0);
341 $txn = $env->TxnMgr()
342 Constructor for creating a TxnMgr object. See "TRANSACTIONS" for
343 more details of using transactions.
344 This method is deprecated. Access the transaction methods using
346 the txn_ methods below from the environment object directly.
347 $env->txn_begin()
349 TODO
350 $env->txn_stat()
352 TODO
353 $env->txn_checkpoint()
355 TODO
356 $env->status()
358 Returns the status of the last BerkeleyDB::Env method.
359 $env->DB_ENV()
361 Returns a pointer to the underlying DB_ENV data structure that
362 Berkeley DB uses.
363 $env->get_shm_key($id)
365 Writes the base segment ID for the shared memory region used by
366 the Berkeley DB environment into $id. Returns 0 on success.
367 This option requires Berkeley DB 4.2 or better.
369 Use the "-SharedMemKey" option when opening the environemt to set
371 the base segment ID.
372 $env->set_timeout($timeout, $flags)
374 $env->status()
375 Returns the status of the last BerkeleyDB::Env method.
376 Examples
378 TODO.
380
382 $status = BerkeleyDB::db_remove [OPTIONS]
383 $status = BerkeleyDB::db_rename [OPTIONS]
384 $status = BerkeleyDB::db_verify [OPTIONS]
385
387 BerkeleyDB supports the following database formats:
388 BerkeleyDB::Hash
390 This database type allows arbitrary key/value pairs to be stored
391 in data files. This is equivalent to the functionality provided by
392 other hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM.
393 Remember though, the files created using BerkeleyDB::Hash are not
394 compatible with any of the other packages mentioned.
395 A default hashing algorithm, which will be adequate for most
397 applications, is built into BerkeleyDB. If you do need to use your
398 own hashing algorithm it is possible to write your own in Perl and
399 have BerkeleyDB use it instead.
400 BerkeleyDB::Btree
402 The Btree format allows arbitrary key/value pairs to be stored in
403 a B+tree.
404 As with the BerkeleyDB::Hash format, it is possible to provide a
406 user defined Perl routine to perform the comparison of keys. By
407 default, though, the keys are stored in lexical order.
408 BerkeleyDB::Recno
410 TODO.
411 BerkeleyDB::Queue
413 TODO.
414 BerkeleyDB::Unknown
416 This isn't a database format at all. It is used when you want to
417 open an existing Berkeley DB database without having to know what
418 type is it.
419 Each of the database formats described above is accessed via a corre‐
421 sponding BerkeleyDB class. These will be described in turn in the next
422 sections.
423
425 Equivalent to calling db_open with type DB_HASH in Berkeley DB 2.x and
426 calling db_create followed by DB->open with type DB_HASH in Berkeley DB
427 3.x or greater.
428 Two forms of constructor are supported:
430 $db = new BerkeleyDB::Hash
432 [ -Filename => "filename", ]
433 [ -Subname => "sub-database name", ]
434 [ -Flags => flags,]
435 [ -Property => flags,]
436 [ -Mode => number,]
437 [ -Cachesize => number,]
438 [ -Lorder => number,]
439 [ -Pagesize => number,]
440 [ -Env => $env,]
441 [ -Txn => $txn,]
442 [ -Encrypt => { Password => "string",
443 Flags => number }, ],
444 # BerkeleyDB::Hash specific
445 [ -Ffactor => number,]
446 [ -Nelem => number,]
447 [ -Hash => code reference,]
448 [ -DupCompare => code reference,]
449 and this
451 [$db =] tie %hash, 'BerkeleyDB::Hash',
453 [ -Filename => "filename", ]
454 [ -Subname => "sub-database name", ]
455 [ -Flags => flags,]
456 [ -Property => flags,]
457 [ -Mode => number,]
458 [ -Cachesize => number,]
459 [ -Lorder => number,]
460 [ -Pagesize => number,]
461 [ -Env => $env,]
462 [ -Txn => $txn,]
463 [ -Encrypt => { Password => "string",
464 Flags => number }, ],
465 # BerkeleyDB::Hash specific
466 [ -Ffactor => number,]
467 [ -Nelem => number,]
468 [ -Hash => code reference,]
469 [ -DupCompare => code reference,]
470 When the "tie" interface is used, reading from and writing to the data‐
472 base is achieved via the tied hash. In this case the database operates
473 like a Perl associative array that happens to be stored on disk.
474 In addition to the high-level tied hash interface, it is possible to
476 make use of the underlying methods provided by Berkeley DB
477 Options
479 In addition to the standard set of options (see "COMMON OPTIONS")
481 BerkeleyDB::Hash supports these options:
482 -Property
484 Used to specify extra flags when opening a database. The following
485 flags may be specified by bitwise OR'ing together one or more of
486 the following values:
487 DB_DUP
489 When creating a new database, this flag enables the storing of
491 duplicate keys in the database. If DB_DUPSORT is not specified as
492 well, the duplicates are stored in the order they are created in
493 the database.
494 DB_DUPSORT
496 Enables the sorting of duplicate keys in the database. Ignored if
498 DB_DUP isn't also specified.
499 -Ffactor
501 -Nelem
502 See the Berkeley DB documentation for details of these options.
503 -Hash
505 Allows you to provide a user defined hash function. If not speci‐
506 fied, a default hash function is used. Here is a template for a
507 user-defined hash function
508 sub hash
510 {
511 my ($data) = shift ;
512 ...
513 # return the hash value for $data
514 return $hash ;
515 }
516 tie %h, "BerkeleyDB::Hash",
518 -Filename => $filename,
519 -Hash => \&hash,
520 ...
521 See for an example.
523 -DupCompare
525 Used in conjunction with the DB_DUPOSRT flag.
526 sub compare
528 {
529 my ($key, $key2) = @_ ;
530 ...
531 # return 0 if $key1 eq $key2
532 # -1 if $key1 lt $key2
533 # 1 if $key1 gt $key2
534 return (-1 , 0 or 1) ;
535 }
536 tie %h, "BerkeleyDB::Hash",
538 -Filename => $filename,
539 -Property => DB_DUP⎪DB_DUPSORT,
540 -DupCompare => \&compare,
541 ...
542 Methods
544 BerkeleyDB::Hash only supports the standard database methods. See
546 "COMMON DATABASE METHODS".
547 A Simple Tied Hash Example
549 use strict ;
551 use BerkeleyDB ;
552 use vars qw( %h $k $v ) ;
553 my $filename = "fruit" ;
555 unlink $filename ;
556 tie %h, "BerkeleyDB::Hash",
557 -Filename => $filename,
558 -Flags => DB_CREATE
559 or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;
560 # Add a few key/value pairs to the file
562 $h{"apple"} = "red" ;
563 $h{"orange"} = "orange" ;
564 $h{"banana"} = "yellow" ;
565 $h{"tomato"} = "red" ;
566 # Check for existence of a key
568 print "Banana Exists\n\n" if $h{"banana"} ;
569 # Delete a key/value pair.
571 delete $h{"apple"} ;
572 # print the contents of the file
574 while (($k, $v) = each %h)
575 { print "$k -> $v\n" }
576 untie %h ;
578 here is the output:
580 Banana Exists
582 orange -> orange
584 tomato -> red
585 banana -> yellow
586 Note that the like ordinary associative arrays, the order of the keys
588 retrieved from a Hash database are in an apparently random order.
589 Another Simple Hash Example
591 Do the same as the previous example but not using tie.
593 use strict ;
595 use BerkeleyDB ;
596 my $filename = "fruit" ;
598 unlink $filename ;
599 my $db = new BerkeleyDB::Hash
600 -Filename => $filename,
601 -Flags => DB_CREATE
602 or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;
603 # Add a few key/value pairs to the file
605 $db->db_put("apple", "red") ;
606 $db->db_put("orange", "orange") ;
607 $db->db_put("banana", "yellow") ;
608 $db->db_put("tomato", "red") ;
609 # Check for existence of a key
611 print "Banana Exists\n\n" if $db->db_get("banana", $v) == 0;
612 # Delete a key/value pair.
614 $db->db_del("apple") ;
615 # print the contents of the file
617 my ($k, $v) = ("", "") ;
618 my $cursor = $db->db_cursor() ;
619 while ($cursor->c_get($k, $v, DB_NEXT) == 0)
620 { print "$k -> $v\n" }
621 undef $cursor ;
623 undef $db ;
624 Duplicate keys
626 The code below is a variation on the examples above. This time the hash
628 has been inverted. The key this time is colour and the value is the
629 fruit name. The DB_DUP flag has been specified to allow duplicates.
630 use strict ;
632 use BerkeleyDB ;
633 my $filename = "fruit" ;
635 unlink $filename ;
636 my $db = new BerkeleyDB::Hash
637 -Filename => $filename,
638 -Flags => DB_CREATE,
639 -Property => DB_DUP
640 or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;
641 # Add a few key/value pairs to the file
643 $db->db_put("red", "apple") ;
644 $db->db_put("orange", "orange") ;
645 $db->db_put("green", "banana") ;
646 $db->db_put("yellow", "banana") ;
647 $db->db_put("red", "tomato") ;
648 $db->db_put("green", "apple") ;
649 # print the contents of the file
651 my ($k, $v) = ("", "") ;
652 my $cursor = $db->db_cursor() ;
653 while ($cursor->c_get($k, $v, DB_NEXT) == 0)
654 { print "$k -> $v\n" }
655 undef $cursor ;
657 undef $db ;
658 here is the output:
660 orange -> orange
662 yellow -> banana
663 red -> apple
664 red -> tomato
665 green -> banana
666 green -> apple
667 Sorting Duplicate Keys
669 In the previous example, when there were duplicate keys, the values are
671 sorted in the order they are stored in. The code below is identical to
672 the previous example except the DB_DUPSORT flag is specified.
673 use strict ;
675 use BerkeleyDB ;
676 my $filename = "fruit" ;
678 unlink $filename ;
679 my $db = new BerkeleyDB::Hash
680 -Filename => $filename,
681 -Flags => DB_CREATE,
682 -Property => DB_DUP ⎪ DB_DUPSORT
683 or die "Cannot open file $filename: $! $BerkeleyDB::Error\n" ;
684 # Add a few key/value pairs to the file
686 $db->db_put("red", "apple") ;
687 $db->db_put("orange", "orange") ;
688 $db->db_put("green", "banana") ;
689 $db->db_put("yellow", "banana") ;
690 $db->db_put("red", "tomato") ;
691 $db->db_put("green", "apple") ;
692 # print the contents of the file
694 my ($k, $v) = ("", "") ;
695 my $cursor = $db->db_cursor() ;
696 while ($cursor->c_get($k, $v, DB_NEXT) == 0)
697 { print "$k -> $v\n" }
698 undef $cursor ;
700 undef $db ;
701 Notice that in the output below the duplicate values are sorted.
703 orange -> orange
705 yellow -> banana
706 red -> apple
707 red -> tomato
708 green -> apple
709 green -> banana
710 Custom Sorting Duplicate Keys
712 Another variation
714 TODO
716 Changing the hash
718 TODO
720 Using db_stat
722 TODO
724
726 Equivalent to calling db_open with type DB_BTREE in Berkeley DB 2.x and
727 calling db_create followed by DB->open with type DB_BTREE in Berkeley
728 DB 3.x or greater.
729 Two forms of constructor are supported:
731 $db = new BerkeleyDB::Btree
733 [ -Filename => "filename", ]
734 [ -Subname => "sub-database name", ]
735 [ -Flags => flags,]
736 [ -Property => flags,]
737 [ -Mode => number,]
738 [ -Cachesize => number,]
739 [ -Lorder => number,]
740 [ -Pagesize => number,]
741 [ -Env => $env,]
742 [ -Txn => $txn,]
743 [ -Encrypt => { Password => "string",
744 Flags => number }, ],
745 # BerkeleyDB::Btree specific
746 [ -Minkey => number,]
747 [ -Compare => code reference,]
748 [ -DupCompare => code reference,]
749 [ -Prefix => code reference,]
750 and this
752 [$db =] tie %hash, 'BerkeleyDB::Btree',
754 [ -Filename => "filename", ]
755 [ -Subname => "sub-database name", ]
756 [ -Flags => flags,]
757 [ -Property => flags,]
758 [ -Mode => number,]
759 [ -Cachesize => number,]
760 [ -Lorder => number,]
761 [ -Pagesize => number,]
762 [ -Env => $env,]
763 [ -Txn => $txn,]
764 [ -Encrypt => { Password => "string",
765 Flags => number }, ],
766 # BerkeleyDB::Btree specific
767 [ -Minkey => number,]
768 [ -Compare => code reference,]
769 [ -DupCompare => code reference,]
770 [ -Prefix => code reference,]
771 Options
773 In addition to the standard set of options (see "COMMON OPTIONS")
775 BerkeleyDB::Btree supports these options:
776 -Property
778 Used to specify extra flags when opening a database. The following
779 flags may be specified by bitwise OR'ing together one or more of
780 the following values:
781 DB_DUP
783 When creating a new database, this flag enables the storing of
785 duplicate keys in the database. If DB_DUPSORT is not specified as
786 well, the duplicates are stored in the order they are created in
787 the database.
788 DB_DUPSORT
790 Enables the sorting of duplicate keys in the database. Ignored if
792 DB_DUP isn't also specified.
793 Minkey
795 TODO
796 Compare
798 Allow you to override the default sort order used in the database.
799 See "Changing the sort order" for an example.
800 sub compare
802 {
803 my ($key, $key2) = @_ ;
804 ...
805 # return 0 if $key1 eq $key2
806 # -1 if $key1 lt $key2
807 # 1 if $key1 gt $key2
808 return (-1 , 0 or 1) ;
809 }
810 tie %h, "BerkeleyDB::Hash",
812 -Filename => $filename,
813 -Compare => \&compare,
814 ...
815 Prefix
817 sub prefix
818 {
819 my ($key, $key2) = @_ ;
820 ...
821 # return number of bytes of $key2 which are
822 # necessary to determine that it is greater than $key1
823 return $bytes ;
824 }
825 tie %h, "BerkeleyDB::Hash",
827 -Filename => $filename,
828 -Prefix => \&prefix,
829 ...
830 =item DupCompare
831 sub compare
833 {
834 my ($key, $key2) = @_ ;
835 ...
836 # return 0 if $key1 eq $key2
837 # -1 if $key1 lt $key2
838 # 1 if $key1 gt $key2
839 return (-1 , 0 or 1) ;
840 }
841 tie %h, "BerkeleyDB::Hash",
843 -Filename => $filename,
844 -DupCompare => \&compare,
845 ...
846 Methods
848 BerkeleyDB::Btree supports the following database methods. See also
850 "COMMON DATABASE METHODS".
851 All the methods below return 0 to indicate success.
853 $status = $db->db_key_range($key, $less, $equal, $greater [, $flags])
855 Given a key, $key, this method returns the proportion of keys less
856 than $key in $less, the proportion equal to $key in $equal and the
857 proportion greater than $key in $greater.
858 The proportion is returned as a double in the range 0.0 to 1.0.
860 A Simple Btree Example
862 The code below is a simple example of using a btree database.
864 use strict ;
866 use BerkeleyDB ;
867 my $filename = "tree" ;
869 unlink $filename ;
870 my %h ;
871 tie %h, 'BerkeleyDB::Btree',
872 -Filename => $filename,
873 -Flags => DB_CREATE
874 or die "Cannot open $filename: $! $BerkeleyDB::Error\n" ;
875 # Add a key/value pair to the file
877 $h{'Wall'} = 'Larry' ;
878 $h{'Smith'} = 'John' ;
879 $h{'mouse'} = 'mickey' ;
880 $h{'duck'} = 'donald' ;
881 # Delete
883 delete $h{"duck"} ;
884 # Cycle through the keys printing them in order.
886 # Note it is not necessary to sort the keys as
887 # the btree will have kept them in order automatically.
888 foreach (keys %h)
889 { print "$_\n" }
890 untie %h ;
892 Here is the output from the code above. The keys have been sorted using
894 Berkeley DB's default sorting algorithm.
895 Smith
897 Wall
898 mouse
899 Changing the sort order
901 It is possible to supply your own sorting algorithm if the one that
903 Berkeley DB used isn't suitable. The code below is identical to the
904 previous example except for the case insensitive compare function.
905 use strict ;
907 use BerkeleyDB ;
908 my $filename = "tree" ;
910 unlink $filename ;
911 my %h ;
912 tie %h, 'BerkeleyDB::Btree',
913 -Filename => $filename,
914 -Flags => DB_CREATE,
915 -Compare => sub { lc $_[0] cmp lc $_[1] }
916 or die "Cannot open $filename: $!\n" ;
917 # Add a key/value pair to the file
919 $h{'Wall'} = 'Larry' ;
920 $h{'Smith'} = 'John' ;
921 $h{'mouse'} = 'mickey' ;
922 $h{'duck'} = 'donald' ;
923 # Delete
925 delete $h{"duck"} ;
926 # Cycle through the keys printing them in order.
928 # Note it is not necessary to sort the keys as
929 # the btree will have kept them in order automatically.
930 foreach (keys %h)
931 { print "$_\n" }
932 untie %h ;
934 Here is the output from the code above.
936 mouse
938 Smith
939 Wall
940 There are a few point to bear in mind if you want to change the order‐
942 ing in a BTREE database:
943 1. The new compare function must be specified when you create the
945 database.
946 2. You cannot change the ordering once the database has been created.
948 Thus you must use the same compare function every time you access
949 the database.
950 Using db_stat
952 TODO
954
956 Equivalent to calling db_open with type DB_RECNO in Berkeley DB 2.x and
957 calling db_create followed by DB->open with type DB_RECNO in Berkeley
958 DB 3.x or greater.
959 Two forms of constructor are supported:
961 $db = new BerkeleyDB::Recno
963 [ -Filename => "filename", ]
964 [ -Subname => "sub-database name", ]
965 [ -Flags => flags,]
966 [ -Property => flags,]
967 [ -Mode => number,]
968 [ -Cachesize => number,]
969 [ -Lorder => number,]
970 [ -Pagesize => number,]
971 [ -Env => $env,]
972 [ -Txn => $txn,]
973 [ -Encrypt => { Password => "string",
974 Flags => number }, ],
975 # BerkeleyDB::Recno specific
976 [ -Delim => byte,]
977 [ -Len => number,]
978 [ -Pad => byte,]
979 [ -Source => filename,]
980 and this
982 [$db =] tie @arry, 'BerkeleyDB::Recno',
984 [ -Filename => "filename", ]
985 [ -Subname => "sub-database name", ]
986 [ -Flags => flags,]
987 [ -Property => flags,]
988 [ -Mode => number,]
989 [ -Cachesize => number,]
990 [ -Lorder => number,]
991 [ -Pagesize => number,]
992 [ -Env => $env,]
993 [ -Txn => $txn,]
994 [ -Encrypt => { Password => "string",
995 Flags => number }, ],
996 # BerkeleyDB::Recno specific
997 [ -Delim => byte,]
998 [ -Len => number,]
999 [ -Pad => byte,]
1000 [ -Source => filename,]
1001 A Recno Example
1003 Here is a simple example that uses RECNO (if you are using a version of
1005 Perl earlier than 5.004_57 this example won't work -- see "Extra RECNO
1006 Methods" for a workaround).
1007 use strict ;
1009 use BerkeleyDB ;
1010 my $filename = "text" ;
1012 unlink $filename ;
1013 my @h ;
1015 tie @h, 'BerkeleyDB::Recno',
1016 -Filename => $filename,
1017 -Flags => DB_CREATE,
1018 -Property => DB_RENUMBER
1019 or die "Cannot open $filename: $!\n" ;
1020 # Add a few key/value pairs to the file
1022 $h[0] = "orange" ;
1023 $h[1] = "blue" ;
1024 $h[2] = "yellow" ;
1025 push @h, "green", "black" ;
1027 my $elements = scalar @h ;
1029 print "The array contains $elements entries\n" ;
1030 my $last = pop @h ;
1032 print "popped $last\n" ;
1033 unshift @h, "white" ;
1035 my $first = shift @h ;
1036 print "shifted $first\n" ;
1037 # Check for existence of a key
1039 print "Element 1 Exists with value $h[1]\n" if $h[1] ;
1040 untie @h ;
1042 Here is the output from the script:
1044 The array contains 5 entries
1046 popped black
1047 shifted white
1048 Element 1 Exists with value blue
1049 The last element is green
1050 The 2nd last element is yellow
1051
1053 Equivalent to calling db_create followed by DB->open with type DB_QUEUE
1054 in Berkeley DB 3.x or greater. This database format isn't available if
1055 you use Berkeley DB 2.x.
1056 Two forms of constructor are supported:
1058 $db = new BerkeleyDB::Queue
1060 [ -Filename => "filename", ]
1061 [ -Subname => "sub-database name", ]
1062 [ -Flags => flags,]
1063 [ -Property => flags,]
1064 [ -Mode => number,]
1065 [ -Cachesize => number,]
1066 [ -Lorder => number,]
1067 [ -Pagesize => number,]
1068 [ -Env => $env,]
1069 [ -Txn => $txn,]
1070 [ -Encrypt => { Password => "string",
1071 Flags => number }, ],
1072 # BerkeleyDB::Queue specific
1073 [ -Len => number,]
1074 [ -Pad => byte,]
1075 [ -ExtentSize => number, ]
1076 and this
1078 [$db =] tie @arry, 'BerkeleyDB::Queue',
1080 [ -Filename => "filename", ]
1081 [ -Subname => "sub-database name", ]
1082 [ -Flags => flags,]
1083 [ -Property => flags,]
1084 [ -Mode => number,]
1085 [ -Cachesize => number,]
1086 [ -Lorder => number,]
1087 [ -Pagesize => number,]
1088 [ -Env => $env,]
1089 [ -Txn => $txn,]
1090 [ -Encrypt => { Password => "string",
1091 Flags => number }, ],
1092 # BerkeleyDB::Queue specific
1093 [ -Len => number,]
1094 [ -Pad => byte,]
1095
1097 This class is used to open an existing database.
1098 Equivalent to calling db_open with type DB_UNKNOWN in Berkeley DB 2.x
1100 and calling db_create followed by DB->open with type DB_UNKNOWN in
1101 Berkeley DB 3.x or greater.
1102 The constructor looks like this:
1104 $db = new BerkeleyDB::Unknown
1106 [ -Filename => "filename", ]
1107 [ -Subname => "sub-database name", ]
1108 [ -Flags => flags,]
1109 [ -Property => flags,]
1110 [ -Mode => number,]
1111 [ -Cachesize => number,]
1112 [ -Lorder => number,]
1113 [ -Pagesize => number,]
1114 [ -Env => $env,]
1115 [ -Txn => $txn,]
1116 [ -Encrypt => { Password => "string",
1117 Flags => number }, ],
1118 An example
1120
1122 All database access class constructors support the common set of
1123 options defined below. All are optional.
1124 -Filename
1126 The database filename. If no filename is specified, a temporary
1127 file will be created and removed once the program terminates.
1128 -Subname
1130 Specifies the name of the sub-database to open. This option is
1131 only valid if you are using Berkeley DB 3.x or greater.
1132 -Flags
1134 Specify how the database will be opened/created. The valid flags
1135 are:
1136 DB_CREATE
1138 Create any underlying files, as necessary. If the files do not
1140 already exist and the DB_CREATE flag is not specified, the call
1141 will fail.
1142 DB_NOMMAP
1144 Not supported by BerkeleyDB.
1146 DB_RDONLY
1148 Opens the database in read-only mode.
1150 DB_THREAD
1152 Not supported by BerkeleyDB.
1154 DB_TRUNCATE
1156 If the database file already exists, remove all the data before
1158 opening it.
1159 -Mode
1161 Determines the file protection when the database is created.
1162 Defaults to 0666.
1163 -Cachesize
1165 -Lorder
1166 -Pagesize
1167 -Env When working under a Berkeley DB environment, this parameter
1168 Defaults to no environment.
1170 -Encrypt
1172 If present, this parameter will enable encryption of all data
1173 before it is written to the database. This parameters must be
1174 given a hash reference. The format is shown below.
1175 -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES }
1177 Valid values for the Flags are 0 or "DB_ENCRYPT_AES".
1179 This option requires Berkeley DB 4.1 or better.
1181 -Txn TODO.
1183
1185 All the database interfaces support the common set of methods defined
1186 below.
1187 All the methods below return 0 to indicate success.
1189 $status = $db->db_get($key, $value [, $flags])
1191 Given a key ($key) this method reads the value associated with it from
1193 the database. If it exists, the value read from the database is
1194 returned in the $value parameter.
1195 The $flags parameter is optional. If present, it must be set to one of
1197 the following values:
1198 DB_GET_BOTH
1200 When the DB_GET_BOTH flag is specified, db_get checks for the
1201 existence of both the $key and $value in the database.
1202 DB_SET_RECNO
1204 TODO.
1205 In addition, the following value may be set by bitwise OR'ing it into
1207 the $flags parameter:
1208 DB_RMW
1210 TODO
1211 $status = $db->db_put($key, $value [, $flags])
1213 Stores a key/value pair in the database.
1215 The $flags parameter is optional. If present it must be set to one of
1217 the following values:
1218 DB_APPEND
1220 This flag is only applicable when accessing a BerkeleyDB::Recno
1221 database.
1222 TODO.
1224 DB_NOOVERWRITE
1226 If this flag is specified and $key already exists in the database,
1227 the call to db_put will return DB_KEYEXIST.
1228 $status = $db->db_del($key [, $flags])
1230 Deletes a key/value pair in the database associated with $key. If
1232 duplicate keys are enabled in the database, db_del will delete all
1233 key/value pairs with key $key.
1234 The $flags parameter is optional and is currently unused.
1236 $status = $db->db_sync()
1238 If any parts of the database are in memory, write them to the database.
1240 $cursor = $db->db_cursor([$flags])
1242 Creates a cursor object. This is used to access the contents of the
1244 database sequentially. See CURSORS for details of the methods available
1245 when working with cursors.
1246 The $flags parameter is optional. If present it must be set to one of
1248 the following values:
1249 DB_RMW
1251 TODO.
1252 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length)
1254 ;
1255 TODO
1257 ($flag, $old_offset, $old_length) = $db->partial_clear() ;
1259 TODO
1261 $db->byteswapped()
1263 TODO
1265 $db->type()
1267 Returns the type of the database. The possible return code are DB_HASH
1269 for a BerkeleyDB::Hash database, DB_BTREE for a BerkeleyDB::Btree data‐
1270 base and DB_RECNO for a BerkeleyDB::Recno database. This method is typ‐
1271 ically used when a database has been opened with BerkeleyDB::Unknown.
1272 $bool = $env->cds_enabled();
1274 Returns true if the Berkeley DB environment $env has been opened on CDS
1276 mode.
1277 $bool = $db->cds_enabled();
1279 Returns true if the database $db has been opened on CDS mode.
1281 $lock = $db->cds_lock();
1283 Creates a CDS write lock object $lock.
1285 It is a fatal error to attempt to create a cds_lock if the Berkeley DB
1287 environment has not been opened in CDS mode.
1288 $lock->cds_unlock();
1290 Removes a CDS lock. The destruction of the CDS lock object automati‐
1292 cally calls this method.
1293 Note that if multiple CDS lock objects are created, the underlying
1295 write lock will not be released until all CDS lock objects are either
1296 explictly unlocked with this method, or the CDS lock objects have been
1297 destroyed.
1298 $ref = $db->db_stat()
1300 Returns a reference to an associative array containing information
1302 about the database. The keys of the associative array correspond
1303 directly to the names of the fields defined in the Berkeley DB documen‐
1304 tation. For example, in the DB documentation, the field bt_version
1305 stores the version of the Btree database. Assuming you called db_stat
1306 on a Btree database the equivalent field would be accessed as follows:
1307 $version = $ref->{'bt_version'} ;
1309 If you are using Berkeley DB 3.x or better, this method will work will
1311 all database formats. When DB 2.x is used, it only works with Berke‐
1312 leyDB::Btree.
1313 $status = $db->status()
1315 Returns the status of the last $db method called.
1317 $status = $db->truncate($count)
1319 Truncates the datatabase and returns the number or records deleted in
1321 $count.
1322 $status = $db->compact($start, $stop, $c_data, $flags, $end);
1324 Compacts the database $db.
1326 All the parameters are optional - if only want to make use of some of
1328 them, use "undef" for those you don't want. Trailing unusused parame‐
1329 ters can be omitted. For example, if you only want to use the $c_data
1330 parameter to set the "compact_fillpercent", write you code like this
1331 my %hash;
1333 $hash{compact_fillpercent} = 50;
1334 $db->commit(undef, undef, \%hash);
1335 The parameters operate identically to the C equivalent of this method.
1337 The $c_data needs a bit of explanation - it must be a hash reference.
1338 The values of the following keys can be set before calling "compact"
1339 and will affect the operation of the compaction.
1340 The following keys, along with associated values, will be created in
1342 the hash reference if the "compact" operation was successful.
1343 * compact_deadlock =item * compact_levels =item * compact_pages_free
1345 =item * compact_pages_examine =item * compact_pages_truncated
1346 You need to be running Berkeley DB 4.4 or better if you wan to make use
1348 of "compact".
1349
1351 A cursor is used whenever you want to access the contents of a database
1352 in sequential order. A cursor object is created with the "db_cursor"
1353 A cursor object has the following methods available:
1355 $newcursor = $cursor->c_dup($flags)
1357 Creates a duplicate of $cursor. This method needs Berkeley DB 3.0.x or
1359 better.
1360 The $flags parameter is optional and can take the following value:
1362 DB_POSITION
1364 When present this flag will position the new cursor at the same
1365 place as the existing cursor.
1366 $status = $cursor->c_get($key, $value, $flags)
1368 Reads a key/value pair from the database, returning the data in $key
1370 and $value. The key/value pair actually read is controlled by the
1371 $flags parameter, which can take one of the following values:
1372 DB_FIRST
1374 Set the cursor to point to the first key/value pair in the data‐
1375 base. Return the key/value pair in $key and $value.
1376 DB_LAST
1378 Set the cursor to point to the last key/value pair in the data‐
1379 base. Return the key/value pair in $key and $value.
1380 DB_NEXT
1382 If the cursor is already pointing to a key/value pair, it will be
1383 incremented to point to the next key/value pair and return its
1384 contents.
1385 If the cursor isn't initialised, DB_NEXT works just like DB_FIRST.
1387 If the cursor is already positioned at the last key/value pair,
1389 c_get will return DB_NOTFOUND.
1390 DB_NEXT_DUP
1392 This flag is only valid when duplicate keys have been enabled in a
1393 database. If the cursor is already pointing to a key/value pair
1394 and the key of the next key/value pair is identical, the cursor
1395 will be incremented to point to it and their contents returned.
1396 DB_PREV
1398 If the cursor is already pointing to a key/value pair, it will be
1399 decremented to point to the previous key/value pair and return its
1400 contents.
1401 If the cursor isn't initialised, DB_PREV works just like DB_LAST.
1403 If the cursor is already positioned at the first key/value pair,
1405 c_get will return DB_NOTFOUND.
1406 DB_CURRENT
1408 If the cursor has been set to point to a key/value pair, return
1409 their contents. If the key/value pair referenced by the cursor
1410 has been deleted, c_get will return DB_KEYEMPTY.
1411 DB_SET
1413 Set the cursor to point to the key/value pair referenced by $key
1414 and return the value in $value.
1415 DB_SET_RANGE
1417 This flag is a variation on the DB_SET flag. As well as returning
1418 the value, it also returns the key, via $key. When used with a
1419 BerkeleyDB::Btree database the key matched by c_get will be the
1420 shortest key (in length) which is greater than or equal to the key
1421 supplied, via $key. This allows partial key searches. See ??? for
1422 an example of how to use this flag.
1423 DB_GET_BOTH
1425 Another variation on DB_SET. This one returns both the key and the
1426 value.
1427 DB_SET_RECNO
1429 TODO.
1430 DB_GET_RECNO
1432 TODO.
1433 In addition, the following value may be set by bitwise OR'ing it into
1435 the $flags parameter:
1436 DB_RMW
1438 TODO.
1439 $status = $cursor->c_put($key, $value, $flags)
1441 Stores the key/value pair in the database. The position that the data
1443 is stored in the database is controlled by the $flags parameter, which
1444 must take one of the following values:
1445 DB_AFTER
1447 When used with a Btree or Hash database, a duplicate of the key
1448 referenced by the current cursor position will be created and the
1449 contents of $value will be associated with it - $key is ignored.
1450 The new key/value pair will be stored immediately after the cur‐
1451 rent cursor position. Obviously the database has to have been
1452 opened with DB_DUP.
1453 When used with a Recno ... TODO
1455 DB_BEFORE
1457 When used with a Btree or Hash database, a duplicate of the key
1458 referenced by the current cursor position will be created and the
1459 contents of $value will be associated with it - $key is ignored.
1460 The new key/value pair will be stored immediately before the cur‐
1461 rent cursor position. Obviously the database has to have been
1462 opened with DB_DUP.
1463 When used with a Recno ... TODO
1465 DB_CURRENT
1467 If the cursor has been initialised, replace the value of the
1468 key/value pair stored in the database with the contents of $value.
1469 DB_KEYFIRST
1471 Only valid with a Btree or Hash database. This flag is only really
1472 used when duplicates are enabled in the database and sorted dupli‐
1473 cates haven't been specified. In this case the key/value pair
1474 will be inserted as the first entry in the duplicates for the par‐
1475 ticular key.
1476 DB_KEYLAST
1478 Only valid with a Btree or Hash database. This flag is only really
1479 used when duplicates are enabled in the database and sorted dupli‐
1480 cates haven't been specified. In this case the key/value pair
1481 will be inserted as the last entry in the duplicates for the par‐
1482 ticular key.
1483 $status = $cursor->c_del([$flags])
1485 This method deletes the key/value pair associated with the current cur‐
1487 sor position. The cursor position will not be changed by this opera‐
1488 tion, so any subsequent cursor operation must first initialise the cur‐
1489 sor to point to a valid key/value pair.
1490 If the key/value pair associated with the cursor have already been
1492 deleted, c_del will return DB_KEYEMPTY.
1493 The $flags parameter is not used at present.
1495 $status = $cursor->c_count($cnt [, $flags])
1497 Stores the number of duplicates at the current cursor position in $cnt.
1499 The $flags parameter is not used at present. This method needs Berkeley
1501 DB 3.1 or better.
1502 $status = $cursor->status()
1504 Returns the status of the last cursor method as a dual type.
1506 $status = $cursor->c_pget() ;
1508 TODO
1510 $status = $cursor->c_close()
1512 Closes the cursor $cursor.
1514 Cursor Examples
1516 TODO
1518 Iterating from first to last, then in reverse.
1520 examples of each of the flags.
1522
1524 Join support for BerkeleyDB is in progress. Watch this space.
1525 TODO
1527
1529 TODO.
1530
1532 The Berkeley Db Concurrent Data Store is a lightweight locking mecha‐
1533 nism that is useful in scenarios where transactions are overkill. See
1534 the accompanying document .. for details of using this module in CDS
1535 mode.
1536
1538 A DBM Filter is a piece of code that is be used when you always want to
1539 make the same transformation to all keys and/or values in a DBM data‐
1540 base. All of the database classes (BerkeleyDB::Hash, BerkeleyDB::Btree
1541 and BerkeleyDB::Recno) support DBM Filters.
1542 There are four methods associated with DBM Filters. All work identi‐
1544 cally, and each is used to install (or uninstall) a single DBM Filter.
1545 Each expects a single parameter, namely a reference to a sub. The only
1546 difference between them is the place that the filter is installed.
1547 To summarise:
1549 filter_store_key
1551 If a filter has been installed with this method, it will be
1552 invoked every time you write a key to a DBM database.
1553 filter_store_value
1555 If a filter has been installed with this method, it will be
1556 invoked every time you write a value to a DBM database.
1557 filter_fetch_key
1559 If a filter has been installed with this method, it will be
1560 invoked every time you read a key from a DBM database.
1561 filter_fetch_value
1563 If a filter has been installed with this method, it will be
1564 invoked every time you read a value from a DBM database.
1565 You can use any combination of the methods, from none, to all four.
1567 All filter methods return the existing filter, if present, or "undef"
1569 in not.
1570 To delete a filter pass "undef" to it.
1572 The Filter
1574 When each filter is called by Perl, a local copy of $_ will contain the
1576 key or value to be filtered. Filtering is achieved by modifying the
1577 contents of $_. The return code from the filter is ignored.
1578 An Example -- the NULL termination problem.
1580 Consider the following scenario. You have a DBM database that you need
1582 to share with a third-party C application. The C application assumes
1583 that all keys and values are NULL terminated. Unfortunately when Perl
1584 writes to DBM databases it doesn't use NULL termination, so your Perl
1585 application will have to manage NULL termination itself. When you write
1586 to the database you will have to use something like this:
1587 $hash{"$key\0"} = "$value\0" ;
1589 Similarly the NULL needs to be taken into account when you are consid‐
1591 ering the length of existing keys/values.
1592 It would be much better if you could ignore the NULL terminations issue
1594 in the main application code and have a mechanism that automatically
1595 added the terminating NULL to all keys and values whenever you write to
1596 the database and have them removed when you read from the database. As
1597 I'm sure you have already guessed, this is a problem that DBM Filters
1598 can fix very easily.
1599 use strict ;
1601 use BerkeleyDB ;
1602 my %hash ;
1604 my $filename = "filt.db" ;
1605 unlink $filename ;
1606 my $db = tie %hash, 'BerkeleyDB::Hash',
1608 -Filename => $filename,
1609 -Flags => DB_CREATE
1610 or die "Cannot open $filename: $!\n" ;
1611 # Install DBM Filters
1613 $db->filter_fetch_key ( sub { s/\0$// } ) ;
1614 $db->filter_store_key ( sub { $_ .= "\0" } ) ;
1615 $db->filter_fetch_value( sub { s/\0$// } ) ;
1616 $db->filter_store_value( sub { $_ .= "\0" } ) ;
1617 $hash{"abc"} = "def" ;
1619 my $a = $hash{"ABC"} ;
1620 # ...
1621 undef $db ;
1622 untie %hash ;
1623 Hopefully the contents of each of the filters should be self-explana‐
1625 tory. Both "fetch" filters remove the terminating NULL, and both
1626 "store" filters add a terminating NULL.
1627 Another Example -- Key is a C int.
1629 Here is another real-life example. By default, whenever Perl writes to
1631 a DBM database it always writes the key and value as strings. So when
1632 you use this:
1633 $hash{12345} = "something" ;
1635 the key 12345 will get stored in the DBM database as the 5 byte string
1637 "12345". If you actually want the key to be stored in the DBM database
1638 as a C int, you will have to use "pack" when writing, and "unpack" when
1639 reading.
1640 Here is a DBM Filter that does it:
1642 use strict ;
1644 use BerkeleyDB ;
1645 my %hash ;
1646 my $filename = "filt.db" ;
1647 unlink $filename ;
1648 my $db = tie %hash, 'BerkeleyDB::Btree',
1650 -Filename => $filename,
1651 -Flags => DB_CREATE
1652 or die "Cannot open $filename: $!\n" ;
1653 $db->filter_fetch_key ( sub { $_ = unpack("i", $_) } ) ;
1655 $db->filter_store_key ( sub { $_ = pack ("i", $_) } ) ;
1656 $hash{123} = "def" ;
1657 # ...
1658 undef $db ;
1659 untie %hash ;
1660 This time only two filters have been used -- we only need to manipulate
1662 the contents of the key, so it wasn't necessary to install any value
1663 filters.
1664
1666 Both BerkeleyDB::Hash and BerkeleyDB::Btree can be used with the MLDBM
1667 module. The code fragment below shows how to open associate MLDBM with
1668 BerkeleyDB::Btree. To use BerkeleyDB::Hash just replace Berke‐
1669 leyDB::Btree with BerkeleyDB::Hash.
1670 use strict ;
1672 use BerkeleyDB ;
1673 use MLDBM qw(BerkeleyDB::Btree) ;
1674 use Data::Dumper;
1675 my $filename = 'testmldbm' ;
1677 my %o ;
1678 unlink $filename ;
1680 tie %o, 'MLDBM', -Filename => $filename,
1681 -Flags => DB_CREATE
1682 or die "Cannot open database '$filename: $!\n";
1683 See the MLDBM documentation for information on how to use the module
1685 and for details of its limitations.
1686
1688 TODO.
1689
1691 Sharing Databases With C Applications
1692 There is no technical reason why a Berkeley DB database cannot be
1694 shared by both a Perl and a C application.
1695 The vast majority of problems that are reported in this area boil down
1697 to the fact that C strings are NULL terminated, whilst Perl strings are
1698 not. See "An Example -- the NULL termination problem." in the DBM FIL‐
1699 TERS section for a generic way to work around this problem.
1700 The untie Gotcha
1702 TODO
1704
1706 This section attempts to answer some of the more common questions that
1707 I get asked.
1708 Relationship with DB_File
1710 Before Berkeley DB 2.x was written there was only one Perl module that
1712 interfaced to Berkeley DB. That module is called DB_File. Although
1713 DB_File can be build with Berkeley DB 1.x, 2.x, 3.x or 4.x, it only
1714 provides an interface to the functionality available in Berkeley DB
1715 1.x. That means that it doesn't support transactions, locking or any of
1716 the other new features available in DB 2.x or better.
1717 How do I store Perl data structures with BerkeleyDB?
1719 See "Using BerkeleyDB with MLDBM".
1721
1723 See the Changes file.
1724
1726 The most recent version of BerkeleyDB can always be found on CPAN (see
1727 "CPAN" in perlmod for details), in the directory modules/by-mod‐
1728 ule/BerkeleyDB.
1729 The official web site for Berkeley DB is http://www.sleepycat.com.
1731
1733 Copyright (c) 1997-2004 Paul Marquess. All rights reserved. This pro‐
1734 gram is free software; you can redistribute it and/or modify it under
1735 the same terms as Perl itself.
1736 Although BerkeleyDB is covered by the Perl license, the library it
1738 makes use of, namely Berkeley DB, is not. Berkeley DB has its own copy‐
1739 right and its own license. Please take the time to read it.
1740 Here are few words taken from the Berkeley DB FAQ (at http://www.sleep‐
1742 ycat.com) regarding the license:
1743 Do I have to license DB to use it in Perl scripts?
1745 No. The Berkeley DB license requires that software that uses
1747 Berkeley DB be freely redistributable. In the case of Perl, that
1748 software is Perl, and not your scripts. Any Perl scripts that you
1749 write are your property, including scripts that make use of Berkeley
1750 DB. Neither the Perl license nor the Berkeley DB license
1751 place any restriction on what you may do with them.
1752 If you are in any doubt about the license situation, contact either the
1754 Berkeley DB authors or the author of BerkeleyDB. See "AUTHOR" for
1755 details.
1756
1758 Paul Marquess <pmqs@cpan.org>.
1759 Questions about Berkeley DB may be addressed to <db@sleepycat.com>.
1761
1763 perl(1), DB_File, Berkeley DB.
1764perl v5.8.8 2006-10-02 BerkeleyDB(3)