1GDBM_File(3pm)         Perl Programmers Reference Guide         GDBM_File(3pm)
2
3
4

NAME

6       GDBM_File - Perl5 access to the gdbm library.
7

SYNOPSIS

9           use GDBM_File;
10           [$db =] tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640
11                       or die "$GDBM_File::gdbm_errno";
12           # Use the %hash...
13
14           $e = $db->errno;
15           $e = $db->syserrno;
16           $str = $db->strerror;
17           $bool = $db->needs_recovery;
18
19           $db->clear_error;
20
21           $db->reorganize;
22           $db->sync;
23
24           $n = $db->count;
25
26           $n = $db->flags;
27
28           $str = $db->dbname;
29
30           $db->cache_size;
31           $db->cache_size($newsize);
32
33           $n = $db->block_size;
34
35           $bool = $db->sync_mode;
36           $db->sync_mode($bool);
37
38           $bool = $db->centfree;
39           $db->centfree($bool);
40
41           $bool = $db->coalesce;
42           $db->coalesce($bool);
43
44           $bool = $db->mmap;
45
46           $size = $db->mmapsize;
47           $db->mmapsize($newsize);
48
49           $db->recover(%args);
50
51           untie %hash ;
52

DESCRIPTION

54       GDBM_File is a module which allows Perl programs to make use of the
55       facilities provided by the GNU gdbm library.  If you intend to use this
56       module you should really have a copy of the GDBM manual at hand.  The
57       manual is avaialble online at
58       <https://www.gnu.org.ua/software/gdbm/manual>.
59
60       Most of the gdbm functions are available through the GDBM_File
61       interface.
62
63       Unlike Perl's built-in hashes, it is not safe to "delete" the current
64       item from a GDBM_File tied hash while iterating over it with "each".
65       This is a limitation of the gdbm library.
66
67   Tie
68       Use the Perl built-in tie to associate a GDBM database with a Perl
69       hash:
70
71          tie %hash, 'GDBM_File', $filename, $flags, $mode;
72
73       Here, $filename is the name of the database file to open or create.
74       $flags is a bitwise OR of access mode and optional modifiers.  Access
75       mode is one of:
76
77       GDBM_READER
78           Open existing database file in read-only mode.
79
80       GDBM_WRITER
81           Open existing database file in read-write mode.
82
83       GDBM_WRCREAT
84           If the database file exists, open it in read-write mode.  If it
85           doesn't, create it first and open read-write.
86
87       GDBM_NEWDB
88           Create new database and open it read-write.  If the database
89           already exists, truncate it first.
90
91       A number of modifiers can be OR'd to the access mode.  Most of them are
92       rarely needed (see
93       <https://www.gnu.org.ua/software/gdbm/manual/Open.html> for a complete
94       list), but one is worth mentioning.  The GDBM_NUMSYNC modifier, when
95       used with GDBM_NEWDB, instructs GDBM to create the database in extended
96       (so called numsync) format.  This format is best suited for crash-
97       tolerant implementations.  See CRASH TOLERANCE below for more
98       information.
99
100       The $mode parameter is the file mode for creating new database file.
101       Use an octal constant or a combination of "S_I*" constants from the
102       Fcntl module.  This parameter is used if $flags is GDBM_NEWDB or
103       GDBM_WRCREAT.
104
105       On success, tie returns an object of class GDBM_File.  On failure, it
106       returns undef.  It is recommended to always check the return value, to
107       make sure your hash is successfully associated with the database file.
108       See ERROR HANDLING below for examples.
109

STATIC METHODS

111   GDBM_version
112           $str = GDBM_File->GDBM_version;
113           @ar = GDBM_File->GDBM_version;
114
115       Returns the version number of the underlying libgdbm library. In scalar
116       context, returns the library version formatted as string:
117
118           MINOR.MAJOR[.PATCH][ (GUESS)]
119
120       where MINOR, MAJOR, and PATCH are version numbers, and GUESS is a guess
121       level (see below).
122
123       In list context, returns a list:
124
125           ( MINOR, MAJOR, PATCH [, GUESS] )
126
127       The GUESS component is present only if libgdbm version is 1.8.3 or
128       earlier. This is because earlier releases of libgdbm did not include
129       information about their version and the GDBM_File module has to
130       implement certain guesswork in order to determine it. GUESS is a
131       textual description in string context, and a positive number indicating
132       how rough the guess is in list context. Possible values are:
133
134       1  - exact guess
135           The major and minor version numbers are guaranteed to be correct.
136           The actual patchlevel is most probably guessed right, but can be
137           1-2 less than indicated.
138
139       2  - approximate
140           The major and minor number are guaranteed to be correct. The
141           patchlevel is set to the upper bound.
142
143       3  - rough guess
144           The version is guaranteed to be not newer than MAJOR.MINOR.
145

ERROR HANDLING

147   $GDBM_File::gdbm_errno
148       When referenced in numeric context, retrieves the current value of the
149       gdbm_errno variable, i.e. a numeric code describing the state of the
150       most recent operation on any gdbm database.  Each numeric code has a
151       symbolic name associated with it.   For a comprehensive list  of these,
152       see <https://www.gnu.org.ua/software/gdbm/manual/Error-codes.html>.
153       Notice, that this list includes all error codes defined for the most
154       recent version of gdbm.  Depending on the actual version of the library
155       GDBM_File is built with, some of these may be missing.
156
157       In string context, $gdbm_errno returns a human-readable description of
158       the error.  If necessary, this description includes the value of $!.
159       This makes it possible to use it in diagnostic messages.  For example,
160       the usual tying sequence is
161
162           tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640
163                or die "$GDBM_File::gdbm_errno";
164
165       The following, more complex, example illustrates how you can fall back
166       to read-only mode if the database file permissions forbid read-write
167       access:
168
169           use Errno qw(EACCES);
170           unless (tie(%hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640)) {
171               if ($GDBM_File::gdbm_errno == GDBM_FILE_OPEN_ERROR
172                   && $!{EACCES}) {
173                   if (tie(%hash, 'GDBM_File', $filename, GDBM_READER, 0640)) {
174                       die "$GDBM_File::gdbm_errno";
175                   }
176               } else {
177                   die "$GDBM_File::gdbm_errno";
178               }
179           }
180
181   gdbm_check_syserr
182           if (gdbm_check_syserr(gdbm_errno)) ...
183
184       Returns true if the system error number ($!) gives more information on
185       the cause of the error.
186

DATABASE METHODS

188   close
189           $db->close;
190
191       Closes the database.  Normally you would just do untie.  However, you
192       will need to use this function if you have explicitly assigned the
193       result of tie to a variable, and wish to release the database to
194       another users.  Consider the following code:
195
196           $db = tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640;
197           # Do something with %hash or $db...
198           untie %hash;
199           $db->close;
200
201       In this example, doing untie alone is not enough, since the database
202       would remain referenced by $db, and, as a consequence, the database
203       file would remain locked.  Calling $db->close ensures the database file
204       is closed and unlocked.
205
206   errno
207           $db->errno
208
209       Returns the last error status associated with this database.  In string
210       context, returns a human-readable description of the error.  See also
211       $GDBM_File::gdbm_errno variable above.
212
213   syserrno
214           $db->syserrno
215
216       Returns the last system error status (C "errno" variable), associated
217       with this database,
218
219   strerror
220           $db->strerror
221
222       Returns textual description of the last error that occurred in this
223       database.
224
225   clear_error
226           $db->clear_error
227
228       Clear error status.
229
230   needs_recovery
231           $db->needs_recovery
232
233       Returns true if the database needs recovery.
234
235   reorganize
236           $db->reorganize;
237
238       Reorganizes the database.
239
240   sync
241           $db->sync;
242
243       Synchronizes recent changes to the database with its disk copy.
244
245   count
246           $n = $db->count;
247
248       Returns number of keys in the database.
249
250   flags
251           $db->flags;
252
253       Returns flags passed as 4th argument to tie.
254
255   dbname
256           $db->dbname;
257
258       Returns the database name (i.e. 3rd argument to tie.
259
260   cache_size
261           $db->cache_size;
262           $db->cache_size($newsize);
263
264       Returns the size of the internal GDBM cache for that database.
265
266       Called with argument, sets the size to $newsize.
267
268   block_size
269           $db->block_size;
270
271       Returns the block size of the database.
272
273   sync_mode
274           $db->sync_mode;
275           $db->sync_mode($bool);
276
277       Returns the status of the automatic synchronization mode. Called with
278       argument, enables or disables the sync mode, depending on whether $bool
279       is true or false.
280
281       When synchronization mode is on (true), any changes to the database are
282       immediately written to the disk. This ensures database consistency in
283       case of any unforeseen errors (e.g. power failures), at the expense of
284       considerable slowdown of operation.
285
286       Synchronization mode is off by default.
287
288   centfree
289           $db->centfree;
290           $db->centfree($bool);
291
292       Returns status of the central free block pool (0 - disabled, 1 -
293       enabled).
294
295       With argument, changes its status.
296
297       By default, central free block pool is disabled.
298
299   coalesce
300           $db->coalesce;
301           $db->coalesce($bool);
302
303   mmap
304           $db->mmap;
305
306       Returns true if memory mapping is enabled.
307
308       This method will croak if the libgdbm library is complied without
309       memory mapping support.
310
311   mmapsize
312           $db->mmapsize;
313           $db->mmapsize($newsize);
314
315       If memory mapping is enabled, returns the size of memory mapping. With
316       argument, sets the size to $newsize.
317
318       This method will croak if the libgdbm library is complied without
319       memory mapping support.
320
321   recover
322           $db->recover(%args);
323
324       Recovers data from a failed database. %args is optional and can contain
325       following keys:
326
327       err => sub { ... }
328           Reference to code for detailed error reporting. Upon encountering
329           an error, recover will call this sub with a single argument - a
330           description of the error.
331
332       backup => \$str
333           Creates a backup copy of the database before recovery and returns
334           its filename in $str.
335
336       max_failed_keys => $n
337           Maximum allowed number of failed keys. If the actual number becomes
338           equal to $n, recover aborts and returns error.
339
340       max_failed_buckets => $n
341           Maximum allowed number of failed buckets. If the actual number
342           becomes equal to $n, recover aborts and returns error.
343
344       max_failures => $n
345           Maximum allowed number of failures during recovery.
346
347       stat => \%hash
348           Return recovery statistics in %hash. Upon return, the following
349           keys will be present:
350
351           recovered_keys
352                   Number of successfully recovered keys.
353
354           recovered_buckets
355                   Number of successfully recovered buckets.
356
357           failed_keys
358                   Number of keys that failed to be retrieved.
359
360           failed_buckets
361                   Number of buckets that failed to be retrieved.
362
363   convert
364           $db->convert($format);
365
366       Changes the format of the database file referred to by $db.
367
368       Starting from version 1.20, gdbm supports two database file formats:
369       standard and extended.  The former is the traditional database format,
370       used by previous gdbm versions.  The extended format contains
371       additional data and is recommended for use in crash tolerant
372       applications.
373
374       <https://www.gnu.org.ua/software/gdbm/manual/Numsync.html>, for the
375       discussion of both formats.
376
377       The $format argument sets the new desired database format.  It is
378       GDBM_NUMSYNC to convert the database from standard to extended format,
379       and 0 to convert it from extended to standard format.
380
381       If the database is already in the requested format, the function
382       returns success without doing anything.
383
384   dump
385           $db->dump($filename, %options)
386
387       Creates a dump of the database file in $filename.  Such file can be
388       used as a backup copy or sent over a wire to recreate the database on
389       another machine.  To create a database from the dump file, use the load
390       method.
391
392       GDBM supports two dump formats: old binary and new ascii.  The binary
393       format is not portable across architectures and is deprecated.  It is
394       supported for backward compatibility.  The ascii format is portable and
395       stores additional meta-data about the file.  It was introduced with the
396       gdbm version 1.11 and is the preferred dump format.  The dump method
397       creates ascii dumps by default.
398
399       If the named file already exists, the function will refuse to overwrite
400       and will croak an error.  If it doesn't exist, it will be created with
401       the mode 0666 modified by the current umask.
402
403       These defaults can be altered using the following %options:
404
405       binary => 1
406           Create dump in binary format.
407
408       mode => MODE
409           Set file mode to MODE.
410
411       overwrite => 1
412           Silently overwrite existing files.
413
414   load
415           $db->load($filename, %options)
416
417       Load the data from the dump file $filename into the database $db.  The
418       file must have been previously created using the dump method.  File
419       format is recognized automatically.  By default, the function will
420       croak if the dump contains a key that already exists in the database.
421       It will silently ignore the failure to restore database mode and/or
422       ownership.  These defaults can be altered using the following %options:
423
424       replace => 1
425           Replace existing keys.
426
427       restore_mode => 0 | 1
428           If 0, don't try to restore the mode of the database file to that
429           stored in the dump.
430
431       restore_owner => 0 | 1
432           If 0, don't try to restore the owner of the database file to that
433           stored in the dump.
434
435       strict_errors => 1
436           Croak if failed to restore ownership and/or mode.
437
438       The usual sequence to recreate a database from the dump file is:
439
440           my %hash;
441           my $db = tie %hash, 'GDBM_File', 'a.db', GDBM_NEWDB, 0640;
442           $db->load('a.dump');
443

CRASH TOLERANCE

445       Crash tolerance is a new feature that, given appropriate support from
446       the OS and the filesystem, guarantees that a logically consistent
447       recent state of the database can be recovered following a crash, such
448       as power outage, OS kernel panic, or the like.
449
450       Crash tolerance support appeared in gdbm version 1.21.  The theory
451       behind it is explained in "Crashproofing the Original NoSQL Key-Value
452       Store", by Terence Kelly
453       (<https://queue.acm.org/detail.cfm?id=3487353>).  A detailed discussion
454       of the gdbm implementation is available in the GDBM Manual
455       (<https://www.gnu.org.ua/software/gdbm/manual/Crash-Tolerance.html>).
456       The information below describes the Perl interface.
457
458       For maximum robustness, we recommend to use extended database format
459       for crash tolerant databases.  To create a database in extended format,
460       use the GDBM_NEWDB|GDBM_NUMSYNC when opening the database, e.g.:
461
462           $db = tie %hash, 'GDBM_File', $filename,
463                     GDBM_NEWDB|GDBM_NUMSYNC, 0640;
464
465       To convert existing database to the extended format, use the convert
466       method, described above, e.g.:
467
468           $db->convert(GDBM_NUMSYNC);
469
470   crash_tolerance_status
471           GDBM_File->crash_tolerance_status;
472
473       This static method returns the status of crash tolerance support.  A
474       non-zero value means crash tolerance is compiled in and supported by
475       the operating system.
476
477   failure_atomic
478           $db->failure_atomic($even, $odd)
479
480       Enables crash tolerance for the database $db,  Arguments are the
481       pathnames of two files that will be created and filled with snapshots
482       of the database file.  The two files must not exist when this method is
483       called and must reside on the same filesystem as the database file.
484       This filesystem must be support the reflink operation
485       (https://www.gnu.org.ua/software/gdbm/manual/Filesystems-supporting-crash-tolerance.html>.
486
487       After a successful call to failure_atomic, every call to $db-sync>
488       method will make an efficient reflink snapshot of the database file in
489       one of these files; consecutive calls to sync alternate between the
490       two, hence the names.
491
492       The most recent of these files can be used to recover the database
493       after a crash.  To select the right snapshot, use the latest_snapshot
494       static method.
495
496   latest_snapshot
497           $file = GDBM_File->latest_snapshot($even, $odd);
498
499           ($file, $error) = GDBM_File->latest_snapshot($even, $odd);
500
501       Given the two snapshot names (the ones used previously in a call to
502       failure_atomic), this method selects the one suitable for database
503       recovery, i.e. the file which contains the most recent database
504       snapshot.
505
506       In scalar context, it returns the selected file name or undef in case
507       of failure.
508
509       In array context, the returns a list of two elements: the file name and
510       status code.  On success, the file name is defined and the code is
511       GDBM_SNAPSHOT_OK.  On error, the file name is undef, and the status is
512       one of the following:
513
514       GDBM_SNAPSHOT_BAD
515           Neither snapshot file is applicable. This means that the crash has
516           occurred before a call to failure_atomic completed.  In this case,
517           it is best to fall back on a safe backup copy of the data file.
518
519       GDBM_SNAPSHOT_ERR
520           A system error occurred.  Examine $! for details.  See
521           <https://www.gnu.org.ua/software/gdbm/manual/Crash-recovery.html>
522           for a comprehensive list of error codes and their meaning.
523
524       GDBM_SNAPSHOT_SAME
525           The file modes and modification dates of both snapshot files are
526           exactly the same.  This can happen only for databases in standard
527           format.
528
529       GDBM_SNAPSHOT_SUSPICIOUS
530           The numsync counters of the two snapshots differ by more than one.
531           The most probable reason is programmer's error: the two parameters
532           refer to snapshots belonging to different database files.
533

AVAILABILITY

535       gdbm is available from any GNU archive.  The master site is
536       "ftp.gnu.org", but you are strongly urged to use one of the many
537       mirrors.  You can obtain a list of mirror sites from
538       <http://www.gnu.org/order/ftp.html>.
539

SECURITY AND PORTABILITY

541       GDBM files are not portable across platforms.  If you wish to transfer
542       a GDBM file over the wire, dump it to a portable format first.
543
544       Do not accept GDBM files from untrusted sources.
545
546       Robustness of GDBM against corrupted databases depends highly on its
547       version.  Versions prior to 1.15 did not implement any validity
548       checking, so that a corrupted or maliciously crafted database file
549       could cause perl to crash or even expose a security vulnerability.
550       Versions between 1.15 and 1.20 were progressively strengthened against
551       invalid inputs.  Finally, version 1.21 had undergone extensive fuzzy
552       checking which proved its ability to withstand any kinds of inputs
553       without crashing.
554

SEE ALSO

556       perl(1), DB_File(3), perldbmfilter, gdbm(3),
557       <https://www.gnu.org.ua/software/gdbm/manual.html>.
558
559
560
561perl v5.36.0                      2022-08-30                    GDBM_File(3pm)
Impressum