Debian Codegraph @

lang/perl/BerkeleyDB/BerkeleyDB.pod.P

raw
1 =head1 NAME
2
3 BerkeleyDB - Perl extension for Berkeley DB version 2, 3, 4 or 5
4
5 =head1 SYNOPSIS
6
7 use BerkeleyDB;
8
9 $env = new BerkeleyDB::Env [OPTIONS] ;
10
11 $db = tie %hash, 'BerkeleyDB::Hash', [OPTIONS] ;
12 $db = new BerkeleyDB::Hash [OPTIONS] ;
13
14 $db = tie %hash, 'BerkeleyDB::Btree', [OPTIONS] ;
15 $db = new BerkeleyDB::Btree [OPTIONS] ;
16
17 $db = tie @array, 'BerkeleyDB::Recno', [OPTIONS] ;
18 $db = new BerkeleyDB::Recno [OPTIONS] ;
19
20 $db = tie @array, 'BerkeleyDB::Queue', [OPTIONS] ;
21 $db = new BerkeleyDB::Queue [OPTIONS] ;
22
23 $db = new BerkeleyDB::Heap [OPTIONS] ;
24
25 $db = new BerkeleyDB::Unknown [OPTIONS] ;
26
27 $status = BerkeleyDB::db_remove [OPTIONS]
28 $status = BerkeleyDB::db_rename [OPTIONS]
29 $status = BerkeleyDB::db_verify [OPTIONS]
30
31 $hash{$key} = $value ;
32 $value = $hash{$key} ;
33 each %hash ;
34 keys %hash ;
35 values %hash ;
36
37 $env = $db->Env()
38 $status = $db->db_get()
39 $status = $db->db_exists() ;
40 $status = $db->db_put() ;
41 $status = $db->db_del() ;
42 $status = $db->db_sync() ;
43 $status = $db->db_close() ;
44 $status = $db->db_pget()
45 $hash_ref = $db->db_stat() ;
46 $status = $db->db_key_range();
47 $type = $db->type() ;
48 $status = $db->status() ;
49 $boolean = $db->byteswapped() ;
50 $status = $db->truncate($count) ;
51 $status = $db->compact($start, $stop, $c_data, $flags, $end);
52
53 $bool = $env->cds_enabled();
54 $bool = $db->cds_enabled();
55 $lock = $db->cds_lock();
56 $lock->cds_unlock();
57
58 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;
59 ($flag, $old_offset, $old_length) = $db->partial_clear() ;
60
61 $cursor = $db->db_cursor([$flags]) ;
62 $newcursor = $cursor->c_dup([$flags]);
63 $status = $cursor->c_get() ;
64 $status = $cursor->c_put() ;
65 $status = $cursor->c_del() ;
66 $status = $cursor->c_count() ;
67 $status = $cursor->c_pget() ;
68 $status = $cursor->status() ;
69 $status = $cursor->c_close() ;
70
71 $cursor = $db->db_join() ;
72 $status = $cursor->c_get() ;
73 $status = $cursor->c_close() ;
74
75 $status = $env->txn_checkpoint()
76 $hash_ref = $env->txn_stat()
77 $status = $env->set_mutexlocks()
78 $status = $env->set_flags()
79 $status = $env->set_timeout()
80 $status = $env->lock_detect()
81 $status = $env->lsn_reset()
82
83 $txn = $env->txn_begin() ;
84 $db->Txn($txn);
85 $txn->Txn($db1, $db2,...);
86 $status = $txn->txn_prepare()
87 $status = $txn->txn_commit()
88 $status = $txn->txn_abort()
89 $status = $txn->txn_id()
90 $status = $txn->txn_discard()
91 $status = $txn->set_timeout()
92
93 $status = $env->set_lg_dir();
94 $status = $env->set_lg_bsize();
95 $status = $env->set_lg_max();
96
97 $status = $env->set_data_dir() ;
98 $status = $env->set_tmp_dir() ;
99 $status = $env->set_verbose() ;
100 $db_env_ptr = $env->DB_ENV() ;
101
102 $BerkeleyDB::Error
103 $BerkeleyDB::db_version
104
105 # DBM Filters
106 $old_filter = $db->filter_store_key ( sub { ... } ) ;
107 $old_filter = $db->filter_store_value( sub { ... } ) ;
108 $old_filter = $db->filter_fetch_key ( sub { ... } ) ;
109 $old_filter = $db->filter_fetch_value( sub { ... } ) ;
110
111 # deprecated, but supported
112 $txn_mgr = $env->TxnMgr();
113 $status = $txn_mgr->txn_checkpoint()
114 $hash_ref = $txn_mgr->txn_stat()
115 $txn = $txn_mgr->txn_begin() ;
116
117 =head1 DESCRIPTION
118
119 B<NOTE: This document is still under construction. Expect it to be
120 incomplete in places.>
121
122 This Perl module provides an interface to most of the functionality
123 available in Berkeley DB versions 2, 3 and 4. In general it is safe to assume
124 that the interface provided here to be identical to the Berkeley DB
125 interface. The main changes have been to make the Berkeley DB API work
126 in a Perl way. Note that if you are using Berkeley DB 2.x, the new
127 features available in Berkeley DB 3.x or DB 4.x are not available via
128 this module.
129
130 The reader is expected to be familiar with the Berkeley DB
131 documentation. Where the interface provided here is identical to the
132 Berkeley DB library and the... TODO
133
134 The B<db_appinit>, B<db_cursor>, B<db_open> and B<db_txn> man pages are
135 particularly relevant.
136
137 The interface to Berkeley DB is implemented with a number of Perl
138 classes.
139
140 =head1 The BerkeleyDB::Env Class
141
142 The B<BerkeleyDB::Env> class provides an interface to the Berkeley DB
143 function B<db_appinit> in Berkeley DB 2.x or B<db_env_create> and
144 B<DBENV-E<gt>open> in Berkeley DB 3.x/4.x. Its purpose is to initialise a
145 number of sub-systems that can then be used in a consistent way in all
146 the databases you make use of in the environment.
147
148 If you don't intend using transactions, locking or logging, then you
149 shouldn't need to make use of B<BerkeleyDB::Env>.
150
151 Note that an environment consists of a number of files that Berkeley DB
152 manages behind the scenes for you. When you first use an environment, it
153 needs to be explicitly created. This is done by including C<DB_CREATE>
154 with the C<Flags> parameter, described below.
155
156 =head2 Synopsis
157
158 $env = new BerkeleyDB::Env
159 [ -Home => $path, ]
160 [ -Server => $name, ]
161 [ -CacheSize => $number, ]
162 [ -Config => { name => value, name => value }, ]
163 [ -ErrFile => filename, ]
164 [ -MsgFile => filename, ]
165 [ -ErrPrefix => "string", ]
166 [ -Flags => number, ]
167 [ -SetFlags => bitmask, ]
168 [ -LockDetect => number, ]
169 [ -TxMax => number, ]
170 [ -LogConfig => number, ]
171 [ -MaxLockers => number, ]
172 [ -MaxLocks => number, ]
173 [ -MaxObjects => number, ]
174 [ -SharedMemKey => number, ]
175 [ -Verbose => boolean, ]
176 [ -Encrypt => { Password => "string",
177 Flags => number }, ]
178
179 All the parameters to the BerkeleyDB::Env constructor are optional.
180
181 =over 5
182
183 =item -Home
184
185 If present, this parameter should point to an existing directory. Any
186 files that I<aren't> specified with an absolute path in the sub-systems
187 that are initialised by the BerkeleyDB::Env class will be assumed to
188 live in the B<Home> directory.
189
190 For example, in the code fragment below the database "fred.db" will be
191 opened in the directory "/home/databases" because it was specified as a
192 relative path, but "joe.db" will be opened in "/other" because it was
193 part of an absolute path.
194
195 $env = new BerkeleyDB::Env
196 -Home => "/home/databases"
197 ...
198
199 $db1 = new BerkeleyDB::Hash
200 -Filename => "fred.db",
201 -Env => $env
202 ...
203
204 $db2 = new BerkeleyDB::Hash
205 -Filename => "/other/joe.db",
206 -Env => $env
207 ...
208
209 =item -Server
210
211 If present, this parameter should be the hostname of a server that is running
212 the Berkeley DB RPC server. All databases will be accessed via the RPC server.
213
214 =item -Encrypt
215
216 If present, this parameter will enable encryption of all data before
217 it is written to the database. This parameters must be given a hash
218 reference. The format is shown below.
219
220 -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES }
221
222 Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>.
223
224 This option requires Berkeley DB 4.1 or better.
225
226 =item -Cachesize
227
228 If present, this parameter sets the size of the environments shared memory
229 buffer pool.
230
231 =item -TxMax
232
233 If present, this parameter sets the number of simultaneous
234 transactions that are allowed. Default 100. This default is
235 definitely too low for programs using the MVCC capabilities.
236
237 =item -LogConfig
238
239 If present, this parameter is used to configure log options.
240
241 =item -MaxLockers
242
243 If present, this parameter is used to configure the maximum number of
244 processes doing locking on the database. Default 1000.
245
246 =item -MaxLocks
247
248 If present, this parameter is used to configure the maximum number of
249 locks on the database. Default 1000. This is often lower than required.
250
251 =item -MaxObjects
252
253 If present, this parameter is used to configure the maximum number of
254 locked objects. Default 1000. This is often lower than required.
255
256 =item -SharedMemKey
257
258 If present, this parameter sets the base segment ID for the shared memory
259 region used by Berkeley DB.
260
261 This option requires Berkeley DB 3.1 or better.
262
263 Use C<$env-E<gt>get_shm_key($id)> to find out the base segment ID used
264 once the environment is open.
265
266 =item -ThreadCount
267
268 If present, this parameter declares the approximate number of threads that
269 will be used in the database environment. This parameter is only necessary
270 when the $env->failchk method will be used. It does not actually set the
271 maximum number of threads but rather is used to determine memory sizing.
272
273 This option requires Berkeley DB 4.4 or better. It is only supported on
274 Unix/Linux.
275
276 =item -Config
277
278 This is a variation on the C<-Home> parameter, but it allows finer
279 control of where specific types of files will be stored.
280
281 The parameter expects a reference to a hash. Valid keys are:
282 B<DB_DATA_DIR>, B<DB_LOG_DIR> and B<DB_TMP_DIR>
283
284 The code below shows an example of how it can be used.
285
286 $env = new BerkeleyDB::Env
287 -Config => { DB_DATA_DIR => "/home/databases",
288 DB_LOG_DIR => "/home/logs",
289 DB_TMP_DIR => "/home/tmp"
290 }
291 ...
292
293 =item -ErrFile
294
295 Expects a filename or filenhandle. Any errors generated internally by
296 Berkeley DB will be logged to this file. A useful debug setting is to
297 open environments with either
298
299 -ErrFile => *STDOUT
300
301 or
302
303 -ErrFile => *STDERR
304
305 =item -ErrPrefix
306
307 Allows a prefix to be added to the error messages before they are sent
308 to B<-ErrFile>.
309
310 =item -Flags
311
312 The B<Flags> parameter specifies both which sub-systems to initialise,
313 as well as a number of environment-wide options.
314 See the Berkeley DB documentation for more details of these options.
315
316 Any of the following can be specified by OR'ing them:
317
318 B<DB_CREATE>
319
320 If any of the files specified do not already exist, create them.
321
322 B<DB_INIT_CDB>
323
324 Initialise the Concurrent Access Methods
325
326 B<DB_INIT_LOCK>
327
328 Initialise the Locking sub-system.
329
330 B<DB_INIT_LOG>
331
332 Initialise the Logging sub-system.
333
334 B<DB_INIT_MPOOL>
335
336 Initialize the shared memory buffer pool subsystem. This subsystem should be used whenever an application is using any Berkeley DB access method.
337
338 B<DB_INIT_TXN>
339
340 Initialize the transaction subsystem. This subsystem should be used when recovery and atomicity of multiple operations are important. The DB_INIT_TXN flag implies the DB_INIT_LOG flag.
341
342
343 B<DB_MPOOL_PRIVATE>
344
345 Create a private memory pool; see memp_open. Ignored unless DB_INIT_MPOOL is also specified.
346
347
348 B<DB_INIT_MPOOL> is also specified.
349
350
351 B<DB_NOMMAP>
352
353 Do not map this database into process memory.
354
355
356 B<DB_RECOVER>
357
358 Run normal recovery on this environment before opening it for normal use. If this flag is set, the DB_CREATE flag must also be set since the regions will be removed and recreated.
359
360 The db_appinit function returns successfully if DB_RECOVER is specified and no log files exist, so it is necessary to ensure all necessary log files are present before running recovery.
361
362
363 B<DB_PRIVATE>
364
365 B<DB_RECOVER_FATAL>
366
367 Run catastrophic recovery on this environment before opening it for normal use. If this flag is set, the DB_CREATE flag must also be set since the regions will be removed and recreated.
368
369 The db_appinit function returns successfully if DB_RECOVER_FATAL is specified and no log files exist, so it is necessary to ensure all necessary log files are present before running recovery.
370
371 B<DB_THREAD>
372
373 Ensure that handles returned by the Berkeley DB subsystems are useable by multiple threads within a single process, i.e., that the system is free-threaded.
374
375 B<DB_TXN_NOSYNC>
376
377 On transaction commit, do not synchronously flush the log; see txn_open. Ignored unless DB_INIT_TXN is also specified.
378
379 B<DB_USE_ENVIRON>
380
381 The Berkeley DB process' environment may be permitted to specify information to be used when naming files; see Berkeley DB File Naming. As permitting users to specify which files are used can create security problems, environment information will be used in file naming for all users only if the DB_USE_ENVIRON flag is set.
382
383 B<DB_USE_ENVIRON_ROOT>
384
385 The Berkeley DB process' environment may be permitted to specify information to be used when naming files; see Berkeley DB File Naming. As permitting users to specify which files are used can create security problems, if the DB_USE_ENVIRON_ROOT flag is set, environment information will be used for file naming only for users with a user-ID matching that of the superuser (specifically, users for whom the getuid(2) system call returns the user-ID 0).
386
387 =item -SetFlags
388
389 Calls ENV->set_flags with the supplied bitmask. Use this when you need to make
390 use of DB_ENV->set_flags before DB_ENV->open is called.
391
392 Only valid when Berkeley DB 3.x or better is used.
393
394 =item -LockDetect
395
396 Specifies what to do when a lock conflict occurs. The value should be one of
397
398 B<DB_LOCK_DEFAULT>
399
400 Use the default policy as specified by db_deadlock.
401
402 B<DB_LOCK_OLDEST>
403
404 Abort the oldest transaction.
405
406 B<DB_LOCK_RANDOM>
407
408 Abort a random transaction involved in the deadlock.
409
410 B<DB_LOCK_YOUNGEST>
411
412 Abort the youngest transaction.
413
414
415 =item -Verbose
416
417 Add extra debugging information to the messages sent to B<-ErrFile>.
418
419 =back
420
421 =head2 Methods
422
423 The environment class has the following methods:
424
425 =over 5
426
427 =item $env->errPrefix("string") ;
428
429 This method is identical to the B<-ErrPrefix> flag. It allows the
430 error prefix string to be changed dynamically.
431
432 =item $env->set_flags(bitmask, 1|0);
433
434 =item $txn = $env->TxnMgr()
435
436 Constructor for creating a B<TxnMgr> object.
437 See L<"TRANSACTIONS"> for more details of using transactions.
438
439 This method is deprecated. Access the transaction methods using the B<txn_>
440 methods below from the environment object directly.
441
442 =item $env->txn_begin()
443
444 TODO
445
446 =item $env->txn_stat()
447
448 TODO
449
450 =item $env->txn_checkpoint()
451
452 TODO
453
454 =item $env->status()
455
456 Returns the status of the last BerkeleyDB::Env method.
457
458
459 =item $env->DB_ENV()
460
461 Returns a pointer to the underlying DB_ENV data structure that Berkeley
462 DB uses.
463
464 =item $env->get_shm_key($id)
465
466 Writes the base segment ID for the shared memory region used by the
467 Berkeley DB environment into C<$id>. Returns 0 on success.
468
469 This option requires Berkeley DB 4.2 or better.
470
471 Use the C<-SharedMemKey> option when opening the environemt to set the
472 base segment ID.
473
474 =item $env->set_isalive()
475
476 Set the callback that determines if the thread of control, identified by
477 the pid and tid arguments, is still running. This method should only be
478 used in combination with $env->failchk.
479
480 This option requires Berkeley DB 4.4 or better.
481
482 =item $env->failchk($flags)
483
484 The $env->failchk method checks for threads of control (either a true
485 thread or a process) that have exited while manipulating Berkeley DB
486 library data structures, while holding a logical database lock, or with an
487 unresolved transaction (that is, a transaction that was never aborted or
488 committed).
489
490 If $env->failchk determines a thread of control exited while holding
491 database read locks, it will release those locks. If $env->failchk
492 determines a thread of control exited with an unresolved transaction, the
493 transaction will be aborted.
494
495 Applications calling the $env->failchk method must have already called the
496 $env->set_isalive method, on the same DB environement, and must have
497 configured their database environment using the -ThreadCount flag. The
498 ThreadCount flag cannot be used on an environment that wasn't previously
499 initialized with it.
500
501 This option requires Berkeley DB 4.4 or better.
502
503 =item $env->stat_print
504
505 Prints statistical information.
506
507 If the C<MsgFile> option is specified the output will be sent to the
508 file. Otherwise output is sent to standard output.
509
510 This option requires Berkeley DB 4.3 or better.
511
512 =item $env->lock_stat_print
513
514 Prints locking subsystem statistics.
515
516 If the C<MsgFile> option is specified the output will be sent to the
517 file. Otherwise output is sent to standard output.
518
519 This option requires Berkeley DB 4.3 or better.
520
521 =item $env->mutex_stat_print
522
523 Prints mutex subsystem statistics.
524
525 If the C<MsgFile> option is specified the output will be sent to the
526 file. Otherwise output is sent to standard output.
527
528 This option requires Berkeley DB 4.4 or better.
529
530
531 =item $env->set_timeout($timeout, $flags)
532
533 =item $env->status()
534
535 Returns the status of the last BerkeleyDB::Env method.
536
537 =back
538
539 =head2 Examples
540
541 TODO.
542
543 =head1 Global Classes
544
545 $status = BerkeleyDB::db_remove [OPTIONS]
546 $status = BerkeleyDB::db_rename [OPTIONS]
547 $status = BerkeleyDB::db_verify [OPTIONS]
548
549 =head1 THE DATABASE CLASSES
550
551 B<BerkeleyDB> supports the following database formats:
552
553 =over 5
554
555 =item B<BerkeleyDB::Hash>
556
557 This database type allows arbitrary key/value pairs to be stored in data
558 files. This is equivalent to the functionality provided by other
559 hashing packages like DBM, NDBM, ODBM, GDBM, and SDBM. Remember though,
560 the files created using B<BerkeleyDB::Hash> are not compatible with any
561 of the other packages mentioned.
562
563 A default hashing algorithm, which will be adequate for most applications,
564 is built into BerkeleyDB. If you do need to use your own hashing algorithm
565 it is possible to write your own in Perl and have B<BerkeleyDB> use
566 it instead.
567
568 =item B<BerkeleyDB::Btree>
569
570 The Btree format allows arbitrary key/value pairs to be stored in a
571 B+tree.
572
573 As with the B<BerkeleyDB::Hash> format, it is possible to provide a
574 user defined Perl routine to perform the comparison of keys. By default,
575 though, the keys are stored in lexical order.
576
577 =item B<BerkeleyDB::Recno>
578
579 TODO.
580
581
582 =item B<BerkeleyDB::Queue>
583
584 TODO.
585
586 =item B<BerkeleyDB::Heap>
587
588 TODO.
589
590 =item B<BerkeleyDB::Unknown>
591
592 This isn't a database format at all. It is used when you want to open an
593 existing Berkeley DB database without having to know what type is it.
594
595 =back
596
597
598 Each of the database formats described above is accessed via a
599 corresponding B<BerkeleyDB> class. These will be described in turn in
600 the next sections.
601
602 =head1 BerkeleyDB::Hash
603
604 Equivalent to calling B<db_open> with type B<DB_HASH> in Berkeley DB 2.x and
605 calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_HASH> in
606 Berkeley DB 3.x or greater.
607
608 Two forms of constructor are supported:
609
610 $db = new BerkeleyDB::Hash
611 [ -Filename => "filename", ]
612 [ -Subname => "sub-database name", ]
613 [ -Flags => flags,]
614 [ -Property => flags,]
615 [ -Mode => number,]
616 [ -Cachesize => number,]
617 [ -Lorder => number,]
618 [ -Pagesize => number,]
619 [ -Env => $env,]
620 [ -Txn => $txn,]
621 [ -Encrypt => { Password => "string",
622 Flags => number }, ],
623 # BerkeleyDB::Hash specific
624 [ -Ffactor => number,]
625 [ -Nelem => number,]
626 [ -Hash => code reference,]
627 [ -DupCompare => code reference,]
628
629 and this
630
631 [$db =] tie %hash, 'BerkeleyDB::Hash',
632 [ -Filename => "filename", ]
633 [ -Subname => "sub-database name", ]
634 [ -Flags => flags,]
635 [ -Property => flags,]
636 [ -Mode => number,]
637 [ -Cachesize => number,]
638 [ -Lorder => number,]
639 [ -Pagesize => number,]
640 [ -Env => $env,]
641 [ -Txn => $txn,]
642 [ -Encrypt => { Password => "string",
643 Flags => number }, ],
644 # BerkeleyDB::Hash specific
645 [ -Ffactor => number,]
646 [ -Nelem => number,]
647 [ -Hash => code reference,]
648 [ -DupCompare => code reference,]
649
650
651 When the "tie" interface is used, reading from and writing to the database
652 is achieved via the tied hash. In this case the database operates like
653 a Perl associative array that happens to be stored on disk.
654
655 In addition to the high-level tied hash interface, it is possible to
656 make use of the underlying methods provided by Berkeley DB
657
658 =head2 Options
659
660 In addition to the standard set of options (see L<COMMON OPTIONS>)
661 B<BerkeleyDB::Hash> supports these options:
662
663 =over 5
664
665 =item -Property
666
667 Used to specify extra flags when opening a database. The following
668 flags may be specified by bitwise OR'ing together one or more of the
669 following values:
670
671 B<DB_DUP>
672
673 When creating a new database, this flag enables the storing of duplicate
674 keys in the database. If B<DB_DUPSORT> is not specified as well, the
675 duplicates are stored in the order they are created in the database.
676
677 B<DB_DUPSORT>
678
679 Enables the sorting of duplicate keys in the database. Ignored if
680 B<DB_DUP> isn't also specified.
681
682 =item -Ffactor
683
684 =item -Nelem
685
686 See the Berkeley DB documentation for details of these options.
687
688 =item -Hash
689
690 Allows you to provide a user defined hash function. If not specified,
691 a default hash function is used. Here is a template for a user-defined
692 hash function
693
694 sub hash
695 {
696 my ($data) = shift ;
697 ...
698 # return the hash value for $data
699 return $hash ;
700 }
701
702 tie %h, "BerkeleyDB::Hash",
703 -Filename => $filename,
704 -Hash => \&hash,
705 ...
706
707 See L<""> for an example.
708
709 =item -DupCompare
710
711 Used in conjunction with the B<DB_DUPOSRT> flag.
712
713 sub compare
714 {
715 my ($key, $key2) = @_ ;
716 ...
717 # return 0 if $key1 eq $key2
718 # -1 if $key1 lt $key2
719 # 1 if $key1 gt $key2
720 return (-1 , 0 or 1) ;
721 }
722
723 tie %h, "BerkeleyDB::Hash",
724 -Filename => $filename,
725 -Property => DB_DUP|DB_DUPSORT,
726 -DupCompare => \&compare,
727 ...
728
729 =back
730
731
732 =head2 Methods
733
734 B<BerkeleyDB::Hash> only supports the standard database methods.
735 See L<COMMON DATABASE METHODS>.
736
737 =head2 A Simple Tied Hash Example
738
739 ## simpleHash
740
741 here is the output:
742
743 Banana Exists
744
745 orange -> orange
746 tomato -> red
747 banana -> yellow
748
749 Note that the like ordinary associative arrays, the order of the keys
750 retrieved from a Hash database are in an apparently random order.
751
752 =head2 Another Simple Hash Example
753
754 Do the same as the previous example but not using tie.
755
756 ## simpleHash2
757
758 =head2 Duplicate keys
759
760 The code below is a variation on the examples above. This time the hash has
761 been inverted. The key this time is colour and the value is the fruit name.
762 The B<DB_DUP> flag has been specified to allow duplicates.
763
764 ##dupHash
765
766 here is the output:
767
768 orange -> orange
769 yellow -> banana
770 red -> apple
771 red -> tomato
772 green -> banana
773 green -> apple
774
775 =head2 Sorting Duplicate Keys
776
777 In the previous example, when there were duplicate keys, the values are
778 sorted in the order they are stored in. The code below is
779 identical to the previous example except the B<DB_DUPSORT> flag is
780 specified.
781
782 ##dupSortHash
783
784 Notice that in the output below the duplicate values are sorted.
785
786 orange -> orange
787 yellow -> banana
788 red -> apple
789 red -> tomato
790 green -> apple
791 green -> banana
792
793 =head2 Custom Sorting Duplicate Keys
794
795 Another variation
796
797 TODO
798
799 =head2 Changing the hash
800
801 TODO
802
803 =head2 Using db_stat
804
805 TODO
806
807 =head1 BerkeleyDB::Btree
808
809 Equivalent to calling B<db_open> with type B<DB_BTREE> in Berkeley DB 2.x and
810 calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_BTREE> in
811 Berkeley DB 3.x or greater.
812
813 Two forms of constructor are supported:
814
815
816 $db = new BerkeleyDB::Btree
817 [ -Filename => "filename", ]
818 [ -Subname => "sub-database name", ]
819 [ -Flags => flags,]
820 [ -Property => flags,]
821 [ -Mode => number,]
822 [ -Cachesize => number,]
823 [ -Lorder => number,]
824 [ -Pagesize => number,]
825 [ -Env => $env,]
826 [ -Txn => $txn,]
827 [ -Encrypt => { Password => "string",
828 Flags => number }, ],
829 # BerkeleyDB::Btree specific
830 [ -Minkey => number,]
831 [ -Compare => code reference,]
832 [ -DupCompare => code reference,]
833 [ -Prefix => code reference,]
834
835 and this
836
837 [$db =] tie %hash, 'BerkeleyDB::Btree',
838 [ -Filename => "filename", ]
839 [ -Subname => "sub-database name", ]
840 [ -Flags => flags,]
841 [ -Property => flags,]
842 [ -Mode => number,]
843 [ -Cachesize => number,]
844 [ -Lorder => number,]
845 [ -Pagesize => number,]
846 [ -Env => $env,]
847 [ -Txn => $txn,]
848 [ -Encrypt => { Password => "string",
849 Flags => number }, ],
850 # BerkeleyDB::Btree specific
851 [ -Minkey => number,]
852 [ -Compare => code reference,]
853 [ -DupCompare => code reference,]
854 [ -Prefix => code reference,]
855
856 =head2 Options
857
858 In addition to the standard set of options (see L<COMMON OPTIONS>)
859 B<BerkeleyDB::Btree> supports these options:
860
861 =over 5
862
863 =item -Property
864
865 Used to specify extra flags when opening a database. The following
866 flags may be specified by bitwise OR'ing together one or more of the
867 following values:
868
869 B<DB_DUP>
870
871 When creating a new database, this flag enables the storing of duplicate
872 keys in the database. If B<DB_DUPSORT> is not specified as well, the
873 duplicates are stored in the order they are created in the database.
874
875 B<DB_DUPSORT>
876
877 Enables the sorting of duplicate keys in the database. Ignored if
878 B<DB_DUP> isn't also specified.
879
880 =item Minkey
881
882 TODO
883
884 =item Compare
885
886 Allow you to override the default sort order used in the database. See
887 L<"Changing the sort order"> for an example.
888
889 sub compare
890 {
891 my ($key, $key2) = @_ ;
892 ...
893 # return 0 if $key1 eq $key2
894 # -1 if $key1 lt $key2
895 # 1 if $key1 gt $key2
896 return (-1 , 0 or 1) ;
897 }
898
899 tie %h, "BerkeleyDB::Hash",
900 -Filename => $filename,
901 -Compare => \&compare,
902 ...
903
904 =item Prefix
905
906 sub prefix
907 {
908 my ($key, $key2) = @_ ;
909 ...
910 # return number of bytes of $key2 which are
911 # necessary to determine that it is greater than $key1
912 return $bytes ;
913 }
914
915 tie %h, "BerkeleyDB::Hash",
916 -Filename => $filename,
917 -Prefix => \&prefix,
918 ...
919 =item DupCompare
920
921 sub compare
922 {
923 my ($key, $key2) = @_ ;
924 ...
925 # return 0 if $key1 eq $key2
926 # -1 if $key1 lt $key2
927 # 1 if $key1 gt $key2
928 return (-1 , 0 or 1) ;
929 }
930
931 tie %h, "BerkeleyDB::Hash",
932 -Filename => $filename,
933 -DupCompare => \&compare,
934 ...
935
936 =item set_bt_compress
937
938 Enabled compression of the btree data. The callback interface is not
939 supported at present. Need Berkeley DB 4.8 or better.
940
941 =back
942
943 =head2 Methods
944
945 B<BerkeleyDB::Btree> supports the following database methods.
946 See also L<COMMON DATABASE METHODS>.
947
948 All the methods below return 0 to indicate success.
949
950 =over 5
951
952 =item $status = $db->db_key_range($key, $less, $equal, $greater [, $flags])
953
954 Given a key, C<$key>, this method returns the proportion of keys less than
955 C<$key> in C<$less>, the proportion equal to C<$key> in C<$equal> and the
956 proportion greater than C<$key> in C<$greater>.
957
958 The proportion is returned as a double in the range 0.0 to 1.0.
959
960 =back
961
962 =head2 A Simple Btree Example
963
964 The code below is a simple example of using a btree database.
965
966 ## btreeSimple
967
968 Here is the output from the code above. The keys have been sorted using
969 Berkeley DB's default sorting algorithm.
970
971 Smith
972 Wall
973 mouse
974
975
976 =head2 Changing the sort order
977
978 It is possible to supply your own sorting algorithm if the one that Berkeley
979 DB used isn't suitable. The code below is identical to the previous example
980 except for the case insensitive compare function.
981
982 ## btreeSortOrder
983
984 Here is the output from the code above.
985
986 mouse
987 Smith
988 Wall
989
990 There are a few point to bear in mind if you want to change the
991 ordering in a BTREE database:
992
993 =over 5
994
995 =item 1.
996
997 The new compare function must be specified when you create the database.
998
999 =item 2.
1000
1001 You cannot change the ordering once the database has been created. Thus
1002 you must use the same compare function every time you access the
1003 database.
1004
1005 =back
1006
1007 =head2 Using db_stat
1008
1009 TODO
1010
1011 =head1 BerkeleyDB::Recno
1012
1013 Equivalent to calling B<db_open> with type B<DB_RECNO> in Berkeley DB 2.x and
1014 calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_RECNO> in
1015 Berkeley DB 3.x or greater.
1016
1017 Two forms of constructor are supported:
1018
1019 $db = new BerkeleyDB::Recno
1020 [ -Filename => "filename", ]
1021 [ -Subname => "sub-database name", ]
1022 [ -Flags => flags,]
1023 [ -Property => flags,]
1024 [ -Mode => number,]
1025 [ -Cachesize => number,]
1026 [ -Lorder => number,]
1027 [ -Pagesize => number,]
1028 [ -Env => $env,]
1029 [ -Txn => $txn,]
1030 [ -Encrypt => { Password => "string",
1031 Flags => number }, ],
1032 # BerkeleyDB::Recno specific
1033 [ -Delim => byte,]
1034 [ -Len => number,]
1035 [ -Pad => byte,]
1036 [ -Source => filename,]
1037
1038 and this
1039
1040 [$db =] tie @arry, 'BerkeleyDB::Recno',
1041 [ -Filename => "filename", ]
1042 [ -Subname => "sub-database name", ]
1043 [ -Flags => flags,]
1044 [ -Property => flags,]
1045 [ -Mode => number,]
1046 [ -Cachesize => number,]
1047 [ -Lorder => number,]
1048 [ -Pagesize => number,]
1049 [ -Env => $env,]
1050 [ -Txn => $txn,]
1051 [ -Encrypt => { Password => "string",
1052 Flags => number }, ],
1053 # BerkeleyDB::Recno specific
1054 [ -Delim => byte,]
1055 [ -Len => number,]
1056 [ -Pad => byte,]
1057 [ -Source => filename,]
1058
1059 =head2 A Recno Example
1060
1061 Here is a simple example that uses RECNO (if you are using a version
1062 of Perl earlier than 5.004_57 this example won't work -- see
1063 L<Extra RECNO Methods> for a workaround).
1064
1065 ## simpleRecno
1066
1067 Here is the output from the script:
1068
1069 The array contains 5 entries
1070 popped black
1071 shifted white
1072 Element 1 Exists with value blue
1073 The last element is green
1074 The 2nd last element is yellow
1075
1076 =head1 BerkeleyDB::Queue
1077
1078 Equivalent to calling B<db_create> followed by B<DB-E<gt>open> with
1079 type B<DB_QUEUE> in Berkeley DB 3.x or greater. This database format
1080 isn't available if you use Berkeley DB 2.x.
1081
1082 Two forms of constructor are supported:
1083
1084 $db = new BerkeleyDB::Queue
1085 [ -Filename => "filename", ]
1086 [ -Subname => "sub-database name", ]
1087 [ -Flags => flags,]
1088 [ -Property => flags,]
1089 [ -Mode => number,]
1090 [ -Cachesize => number,]
1091 [ -Lorder => number,]
1092 [ -Pagesize => number,]
1093 [ -Env => $env,]
1094 [ -Txn => $txn,]
1095 [ -Encrypt => { Password => "string",
1096 Flags => number }, ],
1097 # BerkeleyDB::Queue specific
1098 [ -Len => number,]
1099 [ -Pad => byte,]
1100 [ -ExtentSize => number, ]
1101
1102 and this
1103
1104 [$db =] tie @arry, 'BerkeleyDB::Queue',
1105 [ -Filename => "filename", ]
1106 [ -Subname => "sub-database name", ]
1107 [ -Flags => flags,]
1108 [ -Property => flags,]
1109 [ -Mode => number,]
1110 [ -Cachesize => number,]
1111 [ -Lorder => number,]
1112 [ -Pagesize => number,]
1113 [ -Env => $env,]
1114 [ -Txn => $txn,]
1115 [ -Encrypt => { Password => "string",
1116 Flags => number }, ],
1117 # BerkeleyDB::Queue specific
1118 [ -Len => number,]
1119 [ -Pad => byte,]
1120
1121
1122 =head1 BerkeleyDB::Heap
1123
1124 Equivalent to calling B<db_create> followed by B<DB-E<gt>open> with
1125 type B<DB_HEAP> in Berkeley DB 5.2.x or greater. This database format
1126 isn't available if you use an older version of Berkeley DB.
1127
1128 One form of constructor is supported:
1129
1130 $db = new BerkeleyDB::Heap
1131 [ -Filename => "filename", ]
1132 [ -Subname => "sub-database name", ]
1133 [ -Flags => flags,]
1134 [ -Property => flags,]
1135 [ -Mode => number,]
1136 [ -Cachesize => number,]
1137 [ -Lorder => number,]
1138 [ -Pagesize => number,]
1139 [ -Env => $env,]
1140 [ -Txn => $txn,]
1141 [ -Encrypt => { Password => "string",
1142 Flags => number }, ],
1143 # BerkeleyDB::Heap specific
1144 [ -HeapSize => number, ]
1145 [ -HeapSizeGb => number, ]
1146
1147 =head1 BerkeleyDB::Unknown
1148
1149 This class is used to open an existing database.
1150
1151 Equivalent to calling B<db_open> with type B<DB_UNKNOWN> in Berkeley DB 2.x and
1152 calling B<db_create> followed by B<DB-E<gt>open> with type B<DB_UNKNOWN> in
1153 Berkeley DB 3.x or greater.
1154
1155 The constructor looks like this:
1156
1157 $db = new BerkeleyDB::Unknown
1158 [ -Filename => "filename", ]
1159 [ -Subname => "sub-database name", ]
1160 [ -Flags => flags,]
1161 [ -Property => flags,]
1162 [ -Mode => number,]
1163 [ -Cachesize => number,]
1164 [ -Lorder => number,]
1165 [ -Pagesize => number,]
1166 [ -Env => $env,]
1167 [ -Txn => $txn,]
1168 [ -Encrypt => { Password => "string",
1169 Flags => number }, ],
1170
1171
1172 =head2 An example
1173
1174 =head1 COMMON OPTIONS
1175
1176 All database access class constructors support the common set of
1177 options defined below. All are optional.
1178
1179 =over 5
1180
1181 =item -Filename
1182
1183 The database filename. If no filename is specified, a temporary file will
1184 be created and removed once the program terminates.
1185
1186 =item -Subname
1187
1188 Specifies the name of the sub-database to open.
1189 This option is only valid if you are using Berkeley DB 3.x or greater.
1190
1191 =item -Flags
1192
1193 Specify how the database will be opened/created. The valid flags are:
1194
1195 B<DB_CREATE>
1196
1197 Create any underlying files, as necessary. If the files do not already
1198 exist and the B<DB_CREATE> flag is not specified, the call will fail.
1199
1200 B<DB_NOMMAP>
1201
1202 Not supported by BerkeleyDB.
1203
1204 B<DB_RDONLY>
1205
1206 Opens the database in read-only mode.
1207
1208 B<DB_THREAD>
1209
1210 Not supported by BerkeleyDB.
1211
1212 B<DB_TRUNCATE>
1213
1214 If the database file already exists, remove all the data before
1215 opening it.
1216
1217 =item -Mode
1218
1219 Determines the file protection when the database is created. Defaults
1220 to 0666.
1221
1222 =item -Cachesize
1223
1224 =item -Lorder
1225
1226 =item -Pagesize
1227
1228 =item -Env
1229
1230 When working under a Berkeley DB environment, this parameter
1231
1232 Defaults to no environment.
1233
1234 =item -Encrypt
1235
1236 If present, this parameter will enable encryption of all data before
1237 it is written to the database. This parameters must be given a hash
1238 reference. The format is shown below.
1239
1240 -Encrypt => { -Password => "abc", Flags => DB_ENCRYPT_AES }
1241
1242 Valid values for the Flags are 0 or C<DB_ENCRYPT_AES>.
1243
1244 This option requires Berkeley DB 4.1 or better.
1245
1246 =item -Txn
1247
1248 TODO.
1249
1250 =back
1251
1252 =head1 COMMON DATABASE METHODS
1253
1254 All the database interfaces support the common set of methods defined
1255 below.
1256
1257 All the methods below return 0 to indicate success.
1258
1259 =head2 $env = $db->Env();
1260
1261 Returns the environment object the database is associated with or C<undef>
1262 when no environment was used when opening the database.
1263
1264 =head2 $status = $db->db_get($key, $value [, $flags])
1265
1266 Given a key (C<$key>) this method reads the value associated with it
1267 from the database. If it exists, the value read from the database is
1268 returned in the C<$value> parameter.
1269
1270 The B<$flags> parameter is optional. If present, it must be set to B<one>
1271 of the following values:
1272
1273 =over 5
1274
1275 =item B<DB_GET_BOTH>
1276
1277 When the B<DB_GET_BOTH> flag is specified, B<db_get> checks for the
1278 existence of B<both> the C<$key> B<and> C<$value> in the database.
1279
1280 =item B<DB_SET_RECNO>
1281
1282 TODO.
1283
1284 =back
1285
1286 In addition, the following value may be set by bitwise OR'ing it into
1287 the B<$flags> parameter:
1288
1289 =over 5
1290
1291 =item B<DB_RMW>
1292
1293 TODO
1294
1295 =back
1296
1297 The variant C<db_pget> allows you to query a secondary database:
1298
1299 $status = $sdb->db_pget($skey, $pkey, $value);
1300
1301 using the key C<$skey> in the secondary db to lookup C<$pkey> and C<$value>
1302 from the primary db.
1303
1304 =head2 $status = $db->db_exists($key [, $flags])
1305
1306 This method checks for the existence of the given key (C<$key>), but
1307 does not read the value. If the key is not found, B<db_exists> will
1308 return B<DB_NOTFOUND>. Requires BDB 4.6 or better.
1309
1310 =head2 $status = $db->db_put($key, $value [, $flags])
1311
1312 Stores a key/value pair in the database.
1313
1314 The B<$flags> parameter is optional. If present it must be set to B<one>
1315 of the following values:
1316
1317 =over 5
1318
1319 =item B<DB_APPEND>
1320
1321 This flag is only applicable when accessing a B<BerkeleyDB::Recno>
1322 database.
1323
1324 TODO.
1325
1326
1327 =item B<DB_NOOVERWRITE>
1328
1329 If this flag is specified and C<$key> already exists in the database,
1330 the call to B<db_put> will return B<DB_KEYEXIST>.
1331
1332 =back
1333
1334 =head2 $status = $db->db_del($key [, $flags])
1335
1336 Deletes a key/value pair in the database associated with C<$key>.
1337 If duplicate keys are enabled in the database, B<db_del> will delete
1338 B<all> key/value pairs with key C<$key>.
1339
1340 The B<$flags> parameter is optional and is currently unused.
1341
1342 =head2 $status = $env->stat_print([$flags])
1343
1344 Prints statistical information.
1345
1346 If the C<MsgFile> option is specified the output will be sent to the
1347 file. Otherwise output is sent to standard output.
1348
1349 This option requires Berkeley DB 4.3 or better.
1350
1351 =head2 $status = $db->db_sync()
1352
1353 If any parts of the database are in memory, write them to the database.
1354
1355 =head2 $cursor = $db->db_cursor([$flags])
1356
1357 Creates a cursor object. This is used to access the contents of the
1358 database sequentially. See L<CURSORS> for details of the methods
1359 available when working with cursors.
1360
1361 The B<$flags> parameter is optional. If present it must be set to B<one>
1362 of the following values:
1363
1364 =over 5
1365
1366 =item B<DB_RMW>
1367
1368 TODO.
1369
1370 =back
1371
1372 =head2 ($flag, $old_offset, $old_length) = $db->partial_set($offset, $length) ;
1373
1374 TODO
1375
1376 =head2 ($flag, $old_offset, $old_length) = $db->partial_clear() ;
1377
1378 TODO
1379
1380 =head2 $db->byteswapped()
1381
1382 TODO
1383
1384 =head2 $db->type()
1385
1386 Returns the type of the database. The possible return code are B<DB_HASH>
1387 for a B<BerkeleyDB::Hash> database, B<DB_BTREE> for a B<BerkeleyDB::Btree>
1388 database and B<DB_RECNO> for a B<BerkeleyDB::Recno> database. This method
1389 is typically used when a database has been opened with
1390 B<BerkeleyDB::Unknown>.
1391
1392 =head2 $bool = $env->cds_enabled();
1393
1394 Returns true if the Berkeley DB environment C<$env> has been opened on
1395 CDS mode.
1396
1397 =head2 $bool = $db->cds_enabled();
1398
1399 Returns true if the database C<$db> has been opened on CDS mode.
1400
1401 =head2 $lock = $db->cds_lock();
1402
1403 Creates a CDS write lock object C<$lock>.
1404
1405 It is a fatal error to attempt to create a cds_lock if the Berkeley DB
1406 environment has not been opened in CDS mode.
1407
1408 =head2 $lock->cds_unlock();
1409
1410 Removes a CDS lock. The destruction of the CDS lock object automatically
1411 calls this method.
1412
1413 Note that if multiple CDS lock objects are created, the underlying write
1414 lock will not be released until all CDS lock objects are either explictly
1415 unlocked with this method, or the CDS lock objects have been destroyed.
1416
1417 =head2 $ref = $db->db_stat()
1418
1419 Returns a reference to an associative array containing information about
1420 the database. The keys of the associative array correspond directly to the
1421 names of the fields defined in the Berkeley DB documentation. For example,
1422 in the DB documentation, the field B<bt_version> stores the version of the
1423 Btree database. Assuming you called B<db_stat> on a Btree database the
1424 equivalent field would be accessed as follows:
1425
1426 $version = $ref->{'bt_version'} ;
1427
1428 If you are using Berkeley DB 3.x or better, this method will work will
1429 all database formats. When DB 2.x is used, it only works with
1430 B<BerkeleyDB::Btree>.
1431
1432 =head2 $status = $db->status()
1433
1434 Returns the status of the last C<$db> method called.
1435
1436 =head2 $status = $db->truncate($count)
1437
1438 Truncates the datatabase and returns the number or records deleted
1439 in C<$count>.
1440
1441 =head2 $status = $db->compact($start, $stop, $c_data, $flags, $end);
1442
1443 Compacts the database C<$db>.
1444
1445 All the parameters are optional - if only want to make use of some of them,
1446 use C<undef> for those you don't want. Trailing unusused parameters can be
1447 omitted. For example, if you only want to use the C<$c_data> parameter to
1448 set the C<compact_fillpercent>, write you code like this
1449
1450 my %hash;
1451 $hash{compact_fillpercent} = 50;
1452 $db->compact(undef, undef, \%hash);
1453
1454 The parameters operate identically to the C equivalent of this method.
1455 The C<$c_data> needs a bit of explanation - it must be a hash reference.
1456 The values of the following keys can be set before calling C<compact> and
1457 will affect the operation of the compaction.
1458
1459 =over 5
1460
1461 =item * compact_fillpercent
1462
1463 =item * compact_timeout
1464
1465 =back
1466
1467 The following keys, along with associated values, will be created in the
1468 hash reference if the C<compact> operation was successful.
1469
1470 =over 5
1471
1472 =item * compact_deadlock
1473
1474 =item * compact_levels
1475
1476 =item * compact_pages_free
1477
1478 =item * compact_pages_examine
1479
1480 =item * compact_pages_truncated
1481
1482 =back
1483
1484 You need to be running Berkeley DB 4.4 or better if you want to make use of
1485 C<compact>.
1486
1487 =head2 $status = $db->associate($secondary, \&key_callback)
1488
1489 Associate C<$db> with the secondary DB C<$secondary>
1490
1491 New key/value pairs inserted to the database will be passed to the callback
1492 which must set its third argument to the secondary key to allow lookup. If
1493 an array reference is set multiple keys secondary keys will be associated
1494 with the primary database entry.
1495
1496 Data may be retrieved fro the secondary database using C<db_pget> to also
1497 obtain the primary key.
1498
1499 Secondary databased are maintained automatically.
1500
1501 =head2 $status = $db->associate_foreign($secondary, callback, $flags)
1502
1503 Associate a foreign key database C<$db> with the secondary DB
1504 C<$secondary>.
1505
1506 The second parameter must be a reference to a sub or C<undef>.
1507
1508 The C<$flags> parameter must be either C<DB_FOREIGN_CASCADE>,
1509 C<DB_FOREIGN_ABORT> or C<DB_FOREIGN_NULLIFY>.
1510
1511 When the flags parameter is C<DB_FOREIGN_NULLIFY> the second parameter is a
1512 reference to a sub of the form
1513
1514 sub foreign_cb
1515 {
1516 my $key = \$_[0];
1517 my $value = \$_[1];
1518 my $foreignkey = \$_[2];
1519 my $changed = \$_[3] ;
1520
1521 # for ... set $$value and set $$changed to 1
1522
1523 return 0;
1524 }
1525
1526 $foreign_db->associate_foreign($secondary, \&foreign_cb, DB_FOREIGN_NULLIFY);
1527
1528 =head1 CURSORS
1529
1530 A cursor is used whenever you want to access the contents of a database
1531 in sequential order.
1532 A cursor object is created with the C<db_cursor>
1533
1534 A cursor object has the following methods available:
1535
1536 =head2 $newcursor = $cursor->c_dup($flags)
1537
1538 Creates a duplicate of C<$cursor>. This method needs Berkeley DB 3.0.x or better.
1539
1540 The C<$flags> parameter is optional and can take the following value:
1541
1542 =over 5
1543
1544 =item DB_POSITION
1545
1546 When present this flag will position the new cursor at the same place as the
1547 existing cursor.
1548
1549 =back
1550
1551 =head2 $status = $cursor->c_get($key, $value, $flags)
1552
1553 Reads a key/value pair from the database, returning the data in C<$key>
1554 and C<$value>. The key/value pair actually read is controlled by the
1555 C<$flags> parameter, which can take B<one> of the following values:
1556
1557 =over 5
1558
1559 =item B<DB_FIRST>
1560
1561 Set the cursor to point to the first key/value pair in the
1562 database. Return the key/value pair in C<$key> and C<$value>.
1563
1564 =item B<DB_LAST>
1565
1566 Set the cursor to point to the last key/value pair in the database. Return
1567 the key/value pair in C<$key> and C<$value>.
1568
1569 =item B<DB_NEXT>
1570
1571 If the cursor is already pointing to a key/value pair, it will be
1572 incremented to point to the next key/value pair and return its contents.
1573
1574 If the cursor isn't initialised, B<DB_NEXT> works just like B<DB_FIRST>.
1575
1576 If the cursor is already positioned at the last key/value pair, B<c_get>
1577 will return B<DB_NOTFOUND>.
1578
1579 =item B<DB_NEXT_DUP>
1580
1581 This flag is only valid when duplicate keys have been enabled in
1582 a database.
1583 If the cursor is already pointing to a key/value pair and the key of
1584 the next key/value pair is identical, the cursor will be incremented to
1585 point to it and their contents returned.
1586
1587 =item B<DB_PREV>
1588
1589 If the cursor is already pointing to a key/value pair, it will be
1590 decremented to point to the previous key/value pair and return its
1591 contents.
1592
1593 If the cursor isn't initialised, B<DB_PREV> works just like B<DB_LAST>.
1594
1595 If the cursor is already positioned at the first key/value pair, B<c_get>
1596 will return B<DB_NOTFOUND>.
1597
1598 =item B<DB_CURRENT>
1599
1600 If the cursor has been set to point to a key/value pair, return their
1601 contents.
1602 If the key/value pair referenced by the cursor has been deleted, B<c_get>
1603 will return B<DB_KEYEMPTY>.
1604
1605 =item B<DB_SET>
1606
1607 Set the cursor to point to the key/value pair referenced by B<$key>
1608 and return the value in B<$value>.
1609
1610 =item B<DB_SET_RANGE>
1611
1612 This flag is a variation on the B<DB_SET> flag. As well as returning
1613 the value, it also returns the key, via B<$key>.
1614 When used with a B<BerkeleyDB::Btree> database the key matched by B<c_get>
1615 will be the shortest key (in length) which is greater than or equal to
1616 the key supplied, via B<$key>. This allows partial key searches.
1617 See ??? for an example of how to use this flag.
1618
1619 =item B<DB_GET_BOTH>
1620
1621 Another variation on B<DB_SET>. This one returns both the key and
1622 the value.
1623
1624 =item B<DB_SET_RECNO>
1625
1626 TODO.
1627
1628 =item B<DB_GET_RECNO>
1629
1630 TODO.
1631
1632 =back
1633
1634 In addition, the following value may be set by bitwise OR'ing it into
1635 the B<$flags> parameter:
1636
1637 =over 5
1638
1639 =item B<DB_RMW>
1640
1641 TODO.
1642
1643 =back
1644
1645 =head2 $status = $cursor->c_put($key, $value, $flags)
1646
1647 Stores the key/value pair in the database. The position that the data is
1648 stored in the database is controlled by the C<$flags> parameter, which
1649 must take B<one> of the following values:
1650
1651 =over 5
1652
1653 =item B<DB_AFTER>
1654
1655 When used with a Btree or Hash database, a duplicate of the key referenced
1656 by the current cursor position will be created and the contents of
1657 B<$value> will be associated with it - B<$key> is ignored.
1658 The new key/value pair will be stored immediately after the current
1659 cursor position.
1660 Obviously the database has to have been opened with B<DB_DUP>.
1661
1662 When used with a Recno ... TODO
1663
1664
1665 =item B<DB_BEFORE>
1666
1667 When used with a Btree or Hash database, a duplicate of the key referenced
1668 by the current cursor position will be created and the contents of
1669 B<$value> will be associated with it - B<$key> is ignored.
1670 The new key/value pair will be stored immediately before the current
1671 cursor position.
1672 Obviously the database has to have been opened with B<DB_DUP>.
1673
1674 When used with a Recno ... TODO
1675
1676 =item B<DB_CURRENT>
1677
1678 If the cursor has been initialised, replace the value of the key/value
1679 pair stored in the database with the contents of B<$value>.
1680
1681 =item B<DB_KEYFIRST>
1682
1683 Only valid with a Btree or Hash database. This flag is only really
1684 used when duplicates are enabled in the database and sorted duplicates
1685 haven't been specified.
1686 In this case the key/value pair will be inserted as the first entry in
1687 the duplicates for the particular key.
1688
1689 =item B<DB_KEYLAST>
1690
1691 Only valid with a Btree or Hash database. This flag is only really
1692 used when duplicates are enabled in the database and sorted duplicates
1693 haven't been specified.
1694 In this case the key/value pair will be inserted as the last entry in
1695 the duplicates for the particular key.
1696
1697 =back
1698
1699 =head2 $status = $cursor->c_del([$flags])
1700
1701 This method deletes the key/value pair associated with the current cursor
1702 position. The cursor position will not be changed by this operation, so
1703 any subsequent cursor operation must first initialise the cursor to
1704 point to a valid key/value pair.
1705
1706 If the key/value pair associated with the cursor have already been
1707 deleted, B<c_del> will return B<DB_KEYEMPTY>.
1708
1709 The B<$flags> parameter is not used at present.
1710
1711 =head2 $status = $cursor->c_count($cnt [, $flags])
1712
1713 Stores the number of duplicates at the current cursor position in B<$cnt>.
1714
1715 The B<$flags> parameter is not used at present. This method needs
1716 Berkeley DB 3.1 or better.
1717
1718 =head2 $status = $cursor->status()
1719
1720 Returns the status of the last cursor method as a dual type.
1721
1722 =head2 $status = $cursor->c_pget() ;
1723
1724 See C<db_pget>
1725
1726 =head2 $status = $cursor->c_close()
1727
1728 Closes the cursor B<$cursor>.
1729
1730 =head2 Cursor Examples
1731
1732 TODO
1733
1734 Iterating from first to last, then in reverse.
1735
1736 examples of each of the flags.
1737
1738 =head1 JOIN
1739
1740 Join support for BerkeleyDB is in progress. Watch this space.
1741
1742 TODO
1743
1744 =head1 TRANSACTIONS
1745
1746 Transactions are created using the C<txn_begin> method on L<BerkeleyDB::Env>:
1747
1748 my $txn = $env->txn_begin;
1749
1750 If this is a nested transaction, supply the parent transaction as an
1751 argument:
1752
1753 my $child_txn = $env->txn_begin($parent_txn);
1754
1755 Then in order to work with the transaction, you must set it as the current
1756 transaction on the database handles you want to work with:
1757
1758 $db->Txn($txn);
1759
1760 Or for multiple handles:
1761
1762 $txn->Txn(@handles);
1763
1764 The current transaction is given by BerkeleyDB each time to the various BDB
1765 operations. In the C api it is required explicitly as an argument to every
1766 operation.
1767
1768 To commit a transaction call the C<commit> method on it:
1769
1770 $txn->txn_commit;
1771
1772 and to roll back call abort:
1773
1774 $txn->txn_abort
1775
1776 After committing or aborting a child transaction you need to set the active
1777 transaction again using C<Txn>.
1778
1779
1780 =head1 Berkeley DB Concurrent Data Store (CDS)
1781
1782 The Berkeley DB I<Concurrent Data Store> (CDS) is a lightweight locking
1783 mechanism that is useful in scenarios where transactions are overkill.
1784
1785 =head2 What is CDS?
1786
1787 The Berkeley DB CDS interface is a simple lightweight locking mechanism
1788 that allows safe concurrent access to Berkeley DB databases. Your
1789 application can have multiple reader and write processes, but Berkeley DB
1790 will arrange it so that only one process can have a write lock against the
1791 database at a time, i.e. multiple processes can read from a database
1792 concurrently, but all write processes will be serialised.
1793
1794 =head2 Should I use it?
1795
1796 Whilst this simple locking model is perfectly adequate for some
1797 applications, it will be too restrictive for others. Before deciding on
1798 using CDS mode, you need to be sure that it is suitable for the expected
1799 behaviour of your application.
1800
1801 The key features of this model are
1802
1803 =over 5
1804
1805 =item *
1806
1807 All writes operations are serialised.
1808
1809 =item *
1810
1811 A write operation will block until all reads have finished.
1812
1813 =back
1814
1815 There are a few of the attributes of your application that you need to be
1816 aware of before choosing to use CDS.
1817
1818 Firstly, if you application needs either recoverability or transaction
1819 support, then CDS will not be suitable.
1820
1821 Next what is the ratio of read operation to write operations will your
1822 application have?
1823
1824 If it is carrying out mostly read operations, and very few writes, then CDS
1825 may be appropriate.
1826
1827 What is the expected throughput of reads/writes in your application?
1828
1829 If you application does 90% writes and 10% reads, but on average you only
1830 have a transaction every 5 seconds, then the fact that all writes are
1831 serialised will not matter, because there will hardly ever be multiple
1832 writes processes blocking.
1833
1834 In summary CDS mode may be appropriate for your application if it performs
1835 mostly reads and very few writes or there is a low throughput. Also, if
1836 you do not need to be able to roll back a series of database operations if
1837 an error occurs, then CDS is ok.
1838
1839 If any of these is not the case you will need to use Berkeley DB
1840 transactions. That is outside the scope of this document.
1841
1842 =head2 Locking Used
1843
1844 Berkeley DB implements CDS mode using two kinds of lock behind the scenes -
1845 namely read locks and write locks. A read lock allows multiple processes to
1846 access the database for reading at the same time. A write lock will only
1847 get access to the database when there are no read or write locks active.
1848 The write lock will block until the process holding the lock releases it.
1849
1850 Multiple processes with read locks can all access the database at the same
1851 time as long as no process has a write lock. A process with a write lock
1852 can only access the database if there are no other active read or write
1853 locks.
1854
1855 The majority of the time the Berkeley DB CDS mode will handle all locking
1856 without your application having to do anything. There are a couple of
1857 exceptions you need to be aware of though - these will be discussed in
1858 L<Safely Updating Records> and L<Implicit Cursors> below.
1859
1860 A Berkeley DB Cursor (created with C<< $db->db_cursor >>) will by hold a
1861 lock on the database until it is either explicitly closed or destroyed.
1862 This means the lock has the potential to be long lived.
1863
1864 By default Berkeley DB cursors create a read lock, but it is possible to
1865 create a cursor that holds a write lock, thus
1866
1867 $cursor = $db->db_cursor(DB_WRITECURSOR);
1868
1869
1870 Whilst either a read or write cursor is active, it will block any other
1871 processes that wants to write to the database.
1872
1873 To avoid blocking problems, only keep cursors open as long as they are
1874 needed. The same is true when you use the C<cursor> method or the
1875 C<cds_lock> method.
1876
1877 For full information on CDS see the "Berkeley DB Concurrent Data Store
1878 applications" section in the Berkeley DB Reference Guide.
1879
1880
1881 =head2 Opening a database for CDS
1882
1883 Here is the typical signature that is used when opening a database in CDS
1884 mode.
1885
1886 use BerkeleyDB ;
1887
1888 my $env = new BerkeleyDB::Env
1889 -Home => "./home" ,
1890 -Flags => DB_CREATE| DB_INIT_CDB | DB_INIT_MPOOL
1891 or die "cannot open environment: $BerkeleyDB::Error\n";
1892
1893 my $db = new BerkeleyDB::Hash
1894 -Filename => 'test1.db',
1895 -Flags => DB_CREATE,
1896 -Env => $env
1897 or die "cannot open database: $BerkeleyDB::Error\n";
1898
1899 or this, if you use the tied interface
1900
1901 tie %hash, "BerkeleyDB::Hash",
1902 -Filename => 'test2.db',
1903 -Flags => DB_CREATE,
1904 -Env => $env
1905 or die "cannot open database: $BerkeleyDB::Error\n";
1906
1907 The first thing to note is that you B<MUST> always use a Berkeley DB
1908 environment if you want to use locking with Berkeley DB.
1909
1910 Remember, that apart from the actual database files you explicitly create
1911 yourself, Berkeley DB will create a few behind the scenes to handle locking
1912 - they usually have names like "__db.001". It is therefore a good idea to
1913 use the C<-Home> option, unless you are happy for all these files to be
1914 written in the current directory.
1915
1916 Next, remember to include the C<DB_CREATE> flag when opening the
1917 environment for the first time. A common mistake is to forget to add this
1918 option and then wonder why the application doesn't work.
1919
1920 Finally, it is vital that all processes that are going to access the
1921 database files use the same Berkeley DB environment.
1922
1923
1924 =head2 Safely Updating a Record
1925
1926 One of the main gotchas when using CDS is if you want to update a record in
1927 a database, i.e. you want to retrieve a record from a database, modify it
1928 in some way and put it back in the database.
1929
1930 For example, say you are writing a web application and you want to keep a
1931 record of the number of times your site is accessed in a Berkeley DB
1932 database. So your code will have a line of code like this (assume, of
1933 course, that C<%hash> has been tied to a Berkeley DB database):
1934
1935 $hash{Counter} ++ ;
1936
1937 That may look innocent enough, but there is a race condition lurking in
1938 there. If I rewrite the line of code using the low-level Berkeley DB API,
1939 which is what will actually be executed, the race condition may be more
1940 apparent:
1941
1942 $db->db_get("Counter", $value);
1943 ++ $value ;
1944 $db->db_put("Counter", $value);
1945
1946 Consider what happens behind the scenes when you execute the commands
1947 above. Firstly, the existing value for the key "Counter" is fetched from
1948 the database using C<db_get>. A read lock will be used for this part of the
1949 update. The value is then incremented, and the new value is written back
1950 to the database using C<db_put>. This time a write lock will be used.
1951
1952 Here's the problem - there is nothing to stop two (or more) processes
1953 executing the read part at the same time. Remember multiple processes can
1954 hold a read lock on the database at the same time. So both will fetch the
1955 same value, let's say 7, from the database. Both increment the value to 8
1956 and attempt to write it to the database. Berkeley DB will ensure that only
1957 one of the processes gets a write lock, while the other will be blocked. So
1958 the process that happened to get the write lock will store the value 8 to
1959 the database and release the write lock. Now the other process will be
1960 unblocked, and it too will write the value 8 to the database. The result,
1961 in this example, is we have missed a hit in the counter.
1962
1963 To deal with this kind of scenario, you need to make the update atomic. A
1964 convenience method, called C<cds_lock>, is supplied with the BerkeleyDB
1965 module for this purpose. Using C<cds_lock>, the counter update code can now
1966 be rewritten thus:
1967
1968 my $lk = $dbh->cds_lock() ;
1969 $hash{Counter} ++ ;
1970 $lk->cds_unlock;
1971
1972 or this, where scoping is used to limit the lifetime of the lock object
1973
1974 {
1975 my $lk = $dbh->cds_lock() ;
1976 $hash{Counter} ++ ;
1977 }
1978
1979 Similarly, C<cds_lock> can be used with the native Berkeley DB API
1980
1981 my $lk = $dbh->cds_lock() ;
1982 $db->db_get("Counter", $value);
1983 ++ $value ;
1984 $db->db_put("Counter", $value);
1985 $lk->unlock;
1986
1987
1988 The C<cds_lock> method will ensure that the current process has exclusive
1989 access to the database until the lock is either explicitly released, via
1990 the C<< $lk->cds_unlock() >> or by the lock object being destroyed.
1991
1992 If you are interested, all that C<cds_lock> does is open a "write" cursor.
1993 This has the useful side-effect of holding a write-lock on the database
1994 until the cursor is deleted. This is how you create a write-cursor
1995
1996 $cursor = $db->db_cursor(DB_WRITECURSOR);
1997
1998 If you have instantiated multiple C<cds_lock> objects for one database
1999 within a single process, that process will hold a write-lock on the
2000 database until I<ALL> C<cds_lock> objects have been destroyed.
2001
2002 As with all write-cursors, you should try to limit the scope of the
2003 C<cds_lock> to as short a time as possible. Remember the complete database
2004 will be locked to other process whilst the write lock is in place.
2005
2006 =head2 Cannot write with a read cursor while a write cursor is active
2007
2008 This issue is easier to demonstrate with an example, so consider the code
2009 below. The intention of the code is to increment the values of all the
2010 elements in a database by one.
2011
2012 # Assume $db is a database opened in a CDS environment.
2013
2014 # Create a write-lock
2015 my $lock = $db->db_cursor(DB_WRITECURSOR);
2016 # or
2017 # my $lock = $db->cds_lock();
2018
2019
2020 my $cursor = $db->db_cursor();
2021
2022 # Now loop through the database, and increment
2023 # each value using c_put.
2024 while ($cursor->c_get($key, $value, DB_NEXT) == 0)
2025 {
2026 $cursor->c_put($key, $value+1, DB_CURRENT) == 0
2027 or die "$BerkeleyDB::Error\n";
2028 }
2029
2030
2031 When this code is run, it will fail on the C<c_put> line with this error
2032
2033 Write attempted on read-only cursor
2034
2035 The read cursor has automatically disallowed a write operation to prevent a
2036 deadlock.
2037
2038
2039 So the rule is -- you B<CANNOT> carry out a write operation using a
2040 read-only cursor (i.e. you cannot use C<c_put> or C<c_del>) whilst another
2041 write-cursor is already active.
2042
2043 The workaround for this issue is to just use C<db_put> instead of C<c_put>,
2044 like this
2045
2046 # Assume $db is a database opened in a CDS environment.
2047
2048 # Create a write-lock
2049 my $lock = $db->db_cursor(DB_WRITECURSOR);
2050 # or
2051 # my $lock = $db->cds_lock();
2052
2053
2054 my $cursor = $db->db_cursor();
2055
2056 # Now loop through the database, and increment
2057 # each value using c_put.
2058 while ($cursor->c_get($key, $value, DB_NEXT) == 0)
2059 {
2060 $db->db_put($key, $value+1) == 0
2061 or die "$BerkeleyDB::Error\n";
2062 }
2063
2064
2065
2066 =head2 Implicit Cursors
2067
2068 All Berkeley DB cursors will hold either a read lock or a write lock on the
2069 database for the existence of the cursor. In order to prevent blocking of
2070 other processes you need to make sure that they are not long lived.
2071
2072 There are a number of instances where the Perl interface to Berkeley DB
2073 will create a cursor behind the scenes without you being aware of it. Most
2074 of these are very short-lived and will not affect the running of your
2075 script, but there are a few notable exceptions.
2076
2077 Consider this snippet of code
2078
2079 while (my ($k, $v) = each %hash)
2080 {
2081 # do something
2082 }
2083
2084
2085 To implement the "each" functionality, a read cursor will be created behind
2086 the scenes to allow you to iterate through the tied hash, C<%hash>. While
2087 that cursor is still active, a read lock will obviously be held against the
2088 database. If your application has any other writing processes, these will
2089 be blocked until the read cursor is closed. That won't happen until the
2090 loop terminates.
2091
2092 To avoid blocking problems, only keep cursors open as long as they are
2093 needed. The same is true when you use the C<cursor> method or the
2094 C<cds_lock> method.
2095
2096
2097 The locking behaviour of the C<values> or C<keys> functions, shown below,
2098 is subtly different.
2099
2100 foreach my $k (keys %hash)
2101 {
2102 # do something
2103 }
2104
2105 foreach my $v (values %hash)
2106 {
2107 # do something
2108 }
2109
2110
2111 Just as in the C<each> function, a read cursor will be created to iterate
2112 over the database in both of these cases. Where C<keys> and C<values>
2113 differ is the place where the cursor carries out the iteration through the
2114 database. Whilst C<each> carried out a single iteration every time it was
2115 invoked, the C<keys> and C<values> functions will iterate through the
2116 entire database in one go -- the complete database will be read into memory
2117 before the first iteration of the loop.
2118
2119 Apart from the fact that a read lock will be held for the amount of time
2120 required to iterate through the database, the use of C<keys> and C<values>
2121 is B<not> recommended because it will result in the complete database being
2122 read into memory.
2123
2124
2125 =head2 Avoiding Deadlock with multiple databases
2126
2127 If your CDS application uses multiple database files, and you need to write
2128 to more than one of them, you need to be careful you don't create a
2129 deadlock.
2130
2131 For example, say you have two databases, D1 and D2, and two processes, P1
2132 and P2. Assume you want to write a record to each database. If P1 writes
2133 the records to the databases in the order D1, D2 while process P2 writes
2134 the records in the order D2, D1, there is the potential for a deadlock to
2135 occur.
2136
2137 This scenario can be avoided by either always acquiring the write locks in
2138 exactly the same order in your application code, or by using the
2139 C<DB_CDB_ALLDB> flag when opening the environment. This flag will make a
2140 write-lock apply to all the databases in the environment.
2141
2142 Add example here
2143
2144 =head1 DBM Filters
2145
2146 A DBM Filter is a piece of code that is be used when you I<always>
2147 want to make the same transformation to all keys and/or values in a DBM
2148 database. All of the database classes (BerkeleyDB::Hash,
2149 BerkeleyDB::Btree and BerkeleyDB::Recno) support DBM Filters.
2150
2151 There are four methods associated with DBM Filters. All work
2152 identically, and each is used to install (or uninstall) a single DBM
2153 Filter. Each expects a single parameter, namely a reference to a sub.
2154 The only difference between them is the place that the filter is
2155 installed.
2156
2157 To summarise:
2158
2159 =over 5
2160
2161 =item B<filter_store_key>
2162
2163 If a filter has been installed with this method, it will be invoked
2164 every time you write a key to a DBM database.
2165
2166 =item B<filter_store_value>
2167
2168 If a filter has been installed with this method, it will be invoked
2169 every time you write a value to a DBM database.
2170
2171
2172 =item B<filter_fetch_key>
2173
2174 If a filter has been installed with this method, it will be invoked
2175 every time you read a key from a DBM database.
2176
2177 =item B<filter_fetch_value>
2178
2179 If a filter has been installed with this method, it will be invoked
2180 every time you read a value from a DBM database.
2181
2182 =back
2183
2184 You can use any combination of the methods, from none, to all four.
2185
2186 All filter methods return the existing filter, if present, or C<undef>
2187 in not.
2188
2189 To delete a filter pass C<undef> to it.
2190
2191 =head2 The Filter
2192
2193 When each filter is called by Perl, a local copy of C<$_> will contain
2194 the key or value to be filtered. Filtering is achieved by modifying
2195 the contents of C<$_>. The return code from the filter is ignored.
2196
2197 =head2 An Example -- the NULL termination problem.
2198
2199 Consider the following scenario. You have a DBM database that you need
2200 to share with a third-party C application. The C application assumes
2201 that I<all> keys and values are NULL terminated. Unfortunately when
2202 Perl writes to DBM databases it doesn't use NULL termination, so your
2203 Perl application will have to manage NULL termination itself. When you
2204 write to the database you will have to use something like this:
2205
2206 $hash{"$key\0"} = "$value\0" ;
2207
2208 Similarly the NULL needs to be taken into account when you are considering
2209 the length of existing keys/values.
2210
2211 It would be much better if you could ignore the NULL terminations issue
2212 in the main application code and have a mechanism that automatically
2213 added the terminating NULL to all keys and values whenever you write to
2214 the database and have them removed when you read from the database. As I'm
2215 sure you have already guessed, this is a problem that DBM Filters can
2216 fix very easily.
2217
2218 ## nullFilter
2219
2220 Hopefully the contents of each of the filters should be
2221 self-explanatory. Both "fetch" filters remove the terminating NULL,
2222 and both "store" filters add a terminating NULL.
2223
2224
2225 =head2 Another Example -- Key is a C int.
2226
2227 Here is another real-life example. By default, whenever Perl writes to
2228 a DBM database it always writes the key and value as strings. So when
2229 you use this:
2230
2231 $hash{12345} = "something" ;
2232
2233 the key 12345 will get stored in the DBM database as the 5 byte string
2234 "12345". If you actually want the key to be stored in the DBM database
2235 as a C int, you will have to use C<pack> when writing, and C<unpack>
2236 when reading.
2237
2238 Here is a DBM Filter that does it:
2239
2240 ## intFilter
2241
2242 This time only two filters have been used -- we only need to manipulate
2243 the contents of the key, so it wasn't necessary to install any value
2244 filters.
2245
2246 =head1 Using BerkeleyDB with MLDBM
2247
2248 Both BerkeleyDB::Hash and BerkeleyDB::Btree can be used with the MLDBM
2249 module. The code fragment below shows how to open associate MLDBM with
2250 BerkeleyDB::Btree. To use BerkeleyDB::Hash just replace
2251 BerkeleyDB::Btree with BerkeleyDB::Hash.
2252
2253 use strict ;
2254 use BerkeleyDB ;
2255 use MLDBM qw(BerkeleyDB::Btree) ;
2256 use Data::Dumper;
2257
2258 my $filename = 'testmldbm' ;
2259 my %o ;
2260
2261 unlink $filename ;
2262 tie %o, 'MLDBM', -Filename => $filename,
2263 -Flags => DB_CREATE
2264 or die "Cannot open database '$filename: $!\n";
2265
2266 See the MLDBM documentation for information on how to use the module
2267 and for details of its limitations.
2268
2269 =head1 EXAMPLES
2270
2271 TODO.
2272
2273 =head1 HINTS & TIPS
2274
2275 =head2 Sharing Databases With C Applications
2276
2277 There is no technical reason why a Berkeley DB database cannot be
2278 shared by both a Perl and a C application.
2279
2280 The vast majority of problems that are reported in this area boil down
2281 to the fact that C strings are NULL terminated, whilst Perl strings
2282 are not. See L<An Example -- the NULL termination problem.> in the DBM
2283 FILTERS section for a generic way to work around this problem.
2284
2285
2286 =head2 The untie Gotcha
2287
2288 TODO
2289
2290 =head1 COMMON QUESTIONS
2291
2292 This section attempts to answer some of the more common questions that
2293 I get asked.
2294
2295
2296 =head2 Relationship with DB_File
2297
2298 Before Berkeley DB 2.x was written there was only one Perl module that
2299 interfaced to Berkeley DB. That module is called B<DB_File>. Although
2300 B<DB_File> can be build with Berkeley DB 1.x, 2.x, 3.x or 4.x, it only
2301 provides an interface to the functionality available in Berkeley DB
2302 1.x. That means that it doesn't support transactions, locking or any of
2303 the other new features available in DB 2.x or better.
2304
2305 =head2 How do I store Perl data structures with BerkeleyDB?
2306
2307 See L<Using BerkeleyDB with MLDBM>.
2308
2309 =head1 HISTORY
2310
2311 See the Changes file.
2312
2313 =head1 AVAILABILITY
2314
2315 The most recent version of B<BerkeleyDB> can always be found
2316 on CPAN (see L<perlmod/CPAN> for details), in the directory
2317 F<modules/by-module/BerkeleyDB>.
2318
2319 The official web site for Berkeley DB is F<http://www.oracle.com/technology/products/berkeley-db/db/index.html>.
2320
2321 =head1 COPYRIGHT
2322
2323 Copyright (c) 1997-2004 Paul Marquess. All rights reserved. This program
2324 is free software; you can redistribute it and/or modify it under the
2325 same terms as Perl itself.
2326
2327 Although B<BerkeleyDB> is covered by the Perl license, the library it
2328 makes use of, namely Berkeley DB, is not. Berkeley DB has its own
2329 copyright and its own license. Please take the time to read it.
2330
2331 Here are few words taken from the Berkeley DB FAQ (at
2332 F<http://www.oracle.com/technology/products/berkeley-db/db/index.html>) regarding the license:
2333
2334 Do I have to license DB to use it in Perl scripts?
2335
2336 No. The Berkeley DB license requires that software that uses
2337 Berkeley DB be freely redistributable. In the case of Perl, that
2338 software is Perl, and not your scripts. Any Perl scripts that you
2339 write are your property, including scripts that make use of Berkeley
2340 DB. Neither the Perl license nor the Berkeley DB license
2341 place any restriction on what you may do with them.
2342
2343 If you are in any doubt about the license situation, contact either the
2344 Berkeley DB authors or the author of BerkeleyDB.
2345 See L<"AUTHOR"> for details.
2346
2347
2348 =head1 AUTHOR
2349
2350 Paul Marquess E<lt>[email protected]<gt>.
2351
2352
2353 =head1 SEE ALSO
2354
2355 perl(1), DB_File, Berkeley DB.
2356
2357 =cut