1GDBM_File(3pm) Perl Programmers Reference Guide GDBM_File(3pm)
2
6 GDBM_File - Perl5 access to the gdbm library.
7
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 $e = $db->errno;
15 $e = $db->syserrno;
16 $str = $db->strerror;
17 $bool = $db->needs_recovery;
18 $db->clear_error;
20 $db->reorganize;
22 $db->sync;
23 $n = $db->count;
25 $n = $db->flags;
27 $str = $db->dbname;
29 $db->cache_size;
31 $db->cache_size($newsize);
32 $n = $db->block_size;
34 $bool = $db->sync_mode;
36 $db->sync_mode($bool);
37 $bool = $db->centfree;
39 $db->centfree($bool);
40 $bool = $db->coalesce;
42 $db->coalesce($bool);
43 $bool = $db->mmap;
45 $size = $db->mmapsize;
47 $db->mmapsize($newsize);
48 $db->recover(%args);
50 untie %hash ;
52
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 Most of the gdbm functions are available through the GDBM_File
61 interface.
62 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 Tie
68 Use the Perl built-in tie to associate a GDBM database with a Perl
69 hash:
70 tie %hash, 'GDBM_File', $filename, $flags, $mode;
72 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 GDBM_READER
78 Open existing database file in read-only mode.
79 GDBM_WRITER
81 Open existing database file in read-write mode.
82 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 GDBM_NEWDB
88 Create new database and open it read-write. If the database
89 already exists, truncate it first.
90 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 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 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
111 GDBM_version
112 $str = GDBM_File->GDBM_version;
113 @ar = GDBM_File->GDBM_version;
114 Returns the version number of the underlying libgdbm library. In scalar
116 context, returns the library version formatted as string:
117 MINOR.MAJOR[.PATCH][ (GUESS)]
119 where MINOR, MAJOR, and PATCH are version numbers, and GUESS is a guess
121 level (see below).
122 In list context, returns a list:
124 ( MINOR, MAJOR, PATCH [, GUESS] )
126 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 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 2 - approximate
140 The major and minor number are guaranteed to be correct. The
141 patchlevel is set to the upper bound.
142 3 - rough guess
144 The version is guaranteed to be not newer than MAJOR.MINOR.
145
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 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 tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640
163 or die "$GDBM_File::gdbm_errno";
164 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 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 gdbm_check_syserr
182 if (gdbm_check_syserr(gdbm_errno)) ...
183 Returns true if the system error number ($!) gives more information on
185 the cause of the error.
186
188 close
189 $db->close;
190 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 $db = tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640;
197 # Do something with %hash or $db...
198 untie %hash;
199 $db->close;
200 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 errno
207 $db->errno
208 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 syserrno
214 $db->syserrno
215 Returns the last system error status (C "errno" variable), associated
217 with this database,
218 strerror
220 $db->strerror
221 Returns textual description of the last error that occurred in this
223 database.
224 clear_error
226 $db->clear_error
227 Clear error status.
229 needs_recovery
231 $db->needs_recovery
232 Returns true if the database needs recovery.
234 reorganize
236 $db->reorganize;
237 Reorganizes the database.
239 sync
241 $db->sync;
242 Synchronizes recent changes to the database with its disk copy.
244 count
246 $n = $db->count;
247 Returns number of keys in the database.
249 flags
251 $db->flags;
252 Returns flags passed as 4th argument to tie.
254 dbname
256 $db->dbname;
257 Returns the database name (i.e. 3rd argument to tie.
259 cache_size
261 $db->cache_size;
262 $db->cache_size($newsize);
263 Returns the size of the internal GDBM cache for that database.
265 Called with argument, sets the size to $newsize.
267 block_size
269 $db->block_size;
270 Returns the block size of the database.
272 sync_mode
274 $db->sync_mode;
275 $db->sync_mode($bool);
276 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 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 Synchronization mode is off by default.
287 centfree
289 $db->centfree;
290 $db->centfree($bool);
291 Returns status of the central free block pool (0 - disabled, 1 -
293 enabled).
294 With argument, changes its status.
296 By default, central free block pool is disabled.
298 coalesce
300 $db->coalesce;
301 $db->coalesce($bool);
302 mmap
304 $db->mmap;
305 Returns true if memory mapping is enabled.
307 This method will croak if the libgdbm library is complied without
309 memory mapping support.
310 mmapsize
312 $db->mmapsize;
313 $db->mmapsize($newsize);
314 If memory mapping is enabled, returns the size of memory mapping. With
316 argument, sets the size to $newsize.
317 This method will croak if the libgdbm library is complied without
319 memory mapping support.
320 recover
322 $db->recover(%args);
323 Recovers data from a failed database. %args is optional and can contain
325 following keys:
326 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 backup => \$str
333 Creates a backup copy of the database before recovery and returns
334 its filename in $str.
335 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 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 max_failures => $n
345 Maximum allowed number of failures during recovery.
346 stat => \%hash
348 Return recovery statistics in %hash. Upon return, the following
349 keys will be present:
350 recovered_keys
352 Number of successfully recovered keys.
353 recovered_buckets
355 Number of successfully recovered buckets.
356 failed_keys
358 Number of keys that failed to be retrieved.
359 failed_buckets
361 Number of buckets that failed to be retrieved.
362 convert
364 $db->convert($format);
365 Changes the format of the database file referred to by $db.
367 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 <https://www.gnu.org.ua/software/gdbm/manual/Numsync.html>, for the
375 discussion of both formats.
376 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 If the database is already in the requested format, the function
382 returns success without doing anything.
383 dump
385 $db->dump($filename, %options)
386 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 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 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 These defaults can be altered using the following %options:
404 binary => 1
406 Create dump in binary format.
407 mode => MODE
409 Set file mode to MODE.
410 overwrite => 1
412 Silently overwrite existing files.
413 load
415 $db->load($filename, %options)
416 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 replace => 1
425 Replace existing keys.
426 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 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 strict_errors => 1
436 Croak if failed to restore ownership and/or mode.
437 The usual sequence to recreate a database from the dump file is:
439 my %hash;
441 my $db = tie %hash, 'GDBM_File', 'a.db', GDBM_NEWDB, 0640;
442 $db->load('a.dump');
443
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 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 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 $db = tie %hash, 'GDBM_File', $filename,
463 GDBM_NEWDB|GDBM_NUMSYNC, 0640;
464 To convert existing database to the extended format, use the convert
466 method, described above, e.g.:
467 $db->convert(GDBM_NUMSYNC);
469 crash_tolerance_status
471 GDBM_File->crash_tolerance_status;
472 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 failure_atomic
478 $db->failure_atomic($even, $odd)
479 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 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 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 latest_snapshot
497 $file = GDBM_File->latest_snapshot($even, $odd);
498 ($file, $error) = GDBM_File->latest_snapshot($even, $odd);
500 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 In scalar context, it returns the selected file name or undef in case
507 of failure.
508 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 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 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 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 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
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
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 Do not accept GDBM files from untrusted sources.
545 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
556 perl(1), DB_File(3), perldbmfilter, gdbm(3),
557 <https://www.gnu.org.ua/software/gdbm/manual.html>.
558perl v5.38.2 2023-11-30 GDBM_File(3pm)