Debian Codegraph @

upstream/debian-unstable/man3/GDBM_File.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "GDBM_File 3perl"
58 .TH GDBM_File 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 GDBM_File \- Perl5 access to the gdbm library.
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 4
68 \& use GDBM_File;
69 \& [$db =] tie %hash, \*(AqGDBM_File\*(Aq, $filename, GDBM_WRCREAT, 0640
70 \& or die "$GDBM_File::gdbm_errno";
71 \& # Use the %hash...
72 \&
73 \& $e = $db\->errno;
74 \& $e = $db\->syserrno;
75 \& $str = $db\->strerror;
76 \& $bool = $db\->needs_recovery;
77 \&
78 \& $db\->clear_error;
79 \&
80 \& $db\->reorganize;
81 \& $db\->sync;
82 \&
83 \& $n = $db\->count;
84 \&
85 \& $n = $db\->flags;
86 \&
87 \& $str = $db\->dbname;
88 \&
89 \& $db\->cache_size;
90 \& $db\->cache_size($newsize);
91 \&
92 \& $n = $db\->block_size;
93 \&
94 \& $bool = $db\->sync_mode;
95 \& $db\->sync_mode($bool);
96 \&
97 \& $bool = $db\->centfree;
98 \& $db\->centfree($bool);
99 \&
100 \& $bool = $db\->coalesce;
101 \& $db\->coalesce($bool);
102 \&
103 \& $bool = $db\->mmap;
104 \&
105 \& $size = $db\->mmapsize;
106 \& $db\->mmapsize($newsize);
107 \&
108 \& $db\->recover(%args);
109 \&
110 \& untie %hash ;
111 .Ve
112 .SH DESCRIPTION
113 .IX Header "DESCRIPTION"
114 \&\fBGDBM_File\fR is a module which allows Perl programs to make use of the
115 facilities provided by the GNU gdbm library. If you intend to use this
116 module you should really have a copy of the \fBGDBM manual\fR at hand.
117 The manual is avaialble online at
118 <https://www.gnu.org.ua/software/gdbm/manual>.
119 .PP
120 Most of the \fBgdbm\fR functions are available through the \fBGDBM_File\fR
121 interface.
122 .PP
123 Unlike Perl's built-in hashes, it is not safe to \f(CW\*(C`delete\*(C'\fR the current
124 item from a GDBM_File tied hash while iterating over it with \f(CW\*(C`each\*(C'\fR.
125 This is a limitation of the gdbm library.
126 .SS Tie
127 .IX Subsection "Tie"
128 Use the Perl built-in \fBtie\fR to associate a \fBGDBM\fR database with a Perl
129 hash:
130 .PP
131 .Vb 1
132 \& tie %hash, \*(AqGDBM_File\*(Aq, $filename, $flags, $mode;
133 .Ve
134 .PP
135 Here, \fR\f(CI$filename\fR\fI\fR is the name of the database file to open or create.
136 \&\fI\fR\f(CI$flags\fR\fI\fR is a bitwise OR of \fIaccess mode\fR and optional \fImodifiers\fR.
137 Access mode is one of:
138 .IP \fBGDBM_READER\fR 4
139 .IX Item "GDBM_READER"
140 Open existing database file in read-only mode.
141 .IP \fBGDBM_WRITER\fR 4
142 .IX Item "GDBM_WRITER"
143 Open existing database file in read-write mode.
144 .IP \fBGDBM_WRCREAT\fR 4
145 .IX Item "GDBM_WRCREAT"
146 If the database file exists, open it in read-write mode. If it doesn't,
147 create it first and open read-write.
148 .IP \fBGDBM_NEWDB\fR 4
149 .IX Item "GDBM_NEWDB"
150 Create new database and open it read-write. If the database already exists,
151 truncate it first.
152 .PP
153 A number of modifiers can be OR'd to the access mode. Most of them are
154 rarely needed (see <https://www.gnu.org.ua/software/gdbm/manual/Open.html>
155 for a complete list), but one is worth mentioning. The \fBGDBM_NUMSYNC\fR
156 modifier, when used with \fBGDBM_NEWDB\fR, instructs \fBGDBM\fR to create the
157 database in \fIextended\fR (so called \fInumsync\fR) format. This format is
158 best suited for crash-tolerant implementations. See \fBCRASH TOLERANCE\fR
159 below for more information.
160 .PP
161 The \fR\f(CI$mode\fR\fI\fR parameter is the file mode for creating new database
162 file. Use an octal constant or a combination of \f(CW\*(C`S_I*\*(C'\fR constants
163 from the \fBFcntl\fR module. This parameter is used if \fI\fR\f(CI$flags\fR\fI\fR is
164 \&\fBGDBM_NEWDB\fR or \fBGDBM_WRCREAT\fR.
165 .PP
166 On success, \fBtie\fR returns an object of class \fBGDBM_File\fR. On failure,
167 it returns \fBundef\fR. It is recommended to always check the return value,
168 to make sure your hash is successfully associated with the database file.
169 See \fBERROR HANDLING\fR below for examples.
170 .SH "STATIC METHODS"
171 .IX Header "STATIC METHODS"
172 .SS GDBM_version
173 .IX Subsection "GDBM_version"
174 .Vb 2
175 \& $str = GDBM_File\->GDBM_version;
176 \& @ar = GDBM_File\->GDBM_version;
177 .Ve
178 .PP
179 Returns the version number of the underlying \fBlibgdbm\fR library. In scalar
180 context, returns the library version formatted as string:
181 .PP
182 .Vb 1
183 \& MINOR.MAJOR[.PATCH][ (GUESS)]
184 .Ve
185 .PP
186 where \fIMINOR\fR, \fIMAJOR\fR, and \fIPATCH\fR are version numbers, and \fIGUESS\fR is
187 a guess level (see below).
188 .PP
189 In list context, returns a list:
190 .PP
191 .Vb 1
192 \& ( MINOR, MAJOR, PATCH [, GUESS] )
193 .Ve
194 .PP
195 The \fIGUESS\fR component is present only if \fBlibgdbm\fR version is 1.8.3 or
196 earlier. This is because earlier releases of \fBlibgdbm\fR did not include
197 information about their version and the \fBGDBM_File\fR module has to implement
198 certain guesswork in order to determine it. \fIGUESS\fR is a textual description
199 in string context, and a positive number indicating how rough the guess is
200 in list context. Possible values are:
201 .IP "1 \- exact guess" 4
202 .IX Item "1 - exact guess"
203 The major and minor version numbers are guaranteed to be correct. The actual
204 patchlevel is most probably guessed right, but can be 1\-2 less than indicated.
205 .IP "2 \- approximate" 4
206 .IX Item "2 - approximate"
207 The major and minor number are guaranteed to be correct. The patchlevel is
208 set to the upper bound.
209 .IP "3 \- rough guess" 4
210 .IX Item "3 - rough guess"
211 The version is guaranteed to be not newer than \fR\f(BIMAJOR\fR\fB.\fR\f(BIMINOR\fR\fB\fR.
212 .SH "ERROR HANDLING"
213 .IX Header "ERROR HANDLING"
214 .ie n .SS $GDBM_File::gdbm_errno
215 .el .SS \f(CW$GDBM_File::gdbm_errno\fP
216 .IX Subsection "$GDBM_File::gdbm_errno"
217 When referenced in numeric context, retrieves the current value of the
218 \&\fBgdbm_errno\fR variable, i.e. a numeric code describing the state of the
219 most recent operation on any \fBgdbm\fR database. Each numeric code has a
220 symbolic name associated with it. For a comprehensive list of these, see
221 <https://www.gnu.org.ua/software/gdbm/manual/Error\-codes.html>. Notice,
222 that this list includes all error codes defined for the most recent
223 version of \fBgdbm\fR. Depending on the actual version of the library
224 \&\fBGDBM_File\fR is built with, some of these may be missing.
225 .PP
226 In string context, \fR\f(CB$gdbm_errno\fR\fB\fR returns a human-readable description of
227 the error. If necessary, this description includes the value of \fB$!\fR.
228 This makes it possible to use it in diagnostic messages. For example,
229 the usual tying sequence is
230 .PP
231 .Vb 2
232 \& tie %hash, \*(AqGDBM_File\*(Aq, $filename, GDBM_WRCREAT, 0640
233 \& or die "$GDBM_File::gdbm_errno";
234 .Ve
235 .PP
236 The following, more complex, example illustrates how you can fall back
237 to read-only mode if the database file permissions forbid read-write
238 access:
239 .PP
240 .Vb 11
241 \& use Errno qw(EACCES);
242 \& unless (tie(%hash, \*(AqGDBM_File\*(Aq, $filename, GDBM_WRCREAT, 0640)) {
243 \& if ($GDBM_File::gdbm_errno == GDBM_FILE_OPEN_ERROR
244 \& && $!{EACCES}) {
245 \& if (tie(%hash, \*(AqGDBM_File\*(Aq, $filename, GDBM_READER, 0640)) {
246 \& die "$GDBM_File::gdbm_errno";
247 \& }
248 \& } else {
249 \& die "$GDBM_File::gdbm_errno";
250 \& }
251 \& }
252 .Ve
253 .SS gdbm_check_syserr
254 .IX Subsection "gdbm_check_syserr"
255 .Vb 1
256 \& if (gdbm_check_syserr(gdbm_errno)) ...
257 .Ve
258 .PP
259 Returns true if the system error number (\fB$!\fR) gives more information on
260 the cause of the error.
261 .SH "DATABASE METHODS"
262 .IX Header "DATABASE METHODS"
263 .SS close
264 .IX Subsection "close"
265 .Vb 1
266 \& $db\->close;
267 .Ve
268 .PP
269 Closes the database. Normally you would just do \fBuntie\fR. However, you
270 will need to use this function if you have explicitly assigned the result
271 of \fBtie\fR to a variable, and wish to release the database to another
272 users. Consider the following code:
273 .PP
274 .Vb 4
275 \& $db = tie %hash, \*(AqGDBM_File\*(Aq, $filename, GDBM_WRCREAT, 0640;
276 \& # Do something with %hash or $db...
277 \& untie %hash;
278 \& $db\->close;
279 .Ve
280 .PP
281 In this example, doing \fBuntie\fR alone is not enough, since the database
282 would remain referenced by \fR\f(CB$db\fR\fB\fR, and, as a consequence, the database file
283 would remain locked. Calling \fB\fR\f(CB$db\fR\fB\->close\fR ensures the database file is
284 closed and unlocked.
285 .SS errno
286 .IX Subsection "errno"
287 .Vb 1
288 \& $db\->errno
289 .Ve
290 .PP
291 Returns the last error status associated with this database. In string
292 context, returns a human-readable description of the error. See also
293 \&\fR\f(CB$GDBM_File::gdbm_errno\fR\fB\fR variable above.
294 .SS syserrno
295 .IX Subsection "syserrno"
296 .Vb 1
297 \& $db\->syserrno
298 .Ve
299 .PP
300 Returns the last system error status (C \f(CW\*(C`errno\*(C'\fR variable), associated with
301 this database,
302 .SS strerror
303 .IX Subsection "strerror"
304 .Vb 1
305 \& $db\->strerror
306 .Ve
307 .PP
308 Returns textual description of the last error that occurred in this database.
309 .SS clear_error
310 .IX Subsection "clear_error"
311 .Vb 1
312 \& $db\->clear_error
313 .Ve
314 .PP
315 Clear error status.
316 .SS needs_recovery
317 .IX Subsection "needs_recovery"
318 .Vb 1
319 \& $db\->needs_recovery
320 .Ve
321 .PP
322 Returns true if the database needs recovery.
323 .SS reorganize
324 .IX Subsection "reorganize"
325 .Vb 1
326 \& $db\->reorganize;
327 .Ve
328 .PP
329 Reorganizes the database.
330 .SS sync
331 .IX Subsection "sync"
332 .Vb 1
333 \& $db\->sync;
334 .Ve
335 .PP
336 Synchronizes recent changes to the database with its disk copy.
337 .SS count
338 .IX Subsection "count"
339 .Vb 1
340 \& $n = $db\->count;
341 .Ve
342 .PP
343 Returns number of keys in the database.
344 .SS flags
345 .IX Subsection "flags"
346 .Vb 1
347 \& $db\->flags;
348 .Ve
349 .PP
350 Returns flags passed as 4th argument to \fBtie\fR.
351 .SS dbname
352 .IX Subsection "dbname"
353 .Vb 1
354 \& $db\->dbname;
355 .Ve
356 .PP
357 Returns the database name (i.e. 3rd argument to \fBtie\fR.
358 .SS cache_size
359 .IX Subsection "cache_size"
360 .Vb 2
361 \& $db\->cache_size;
362 \& $db\->cache_size($newsize);
363 .Ve
364 .PP
365 Returns the size of the internal \fBGDBM\fR cache for that database.
366 .PP
367 Called with argument, sets the size to \fR\f(CI$newsize\fR\fI\fR.
368 .SS block_size
369 .IX Subsection "block_size"
370 .Vb 1
371 \& $db\->block_size;
372 .Ve
373 .PP
374 Returns the block size of the database.
375 .SS sync_mode
376 .IX Subsection "sync_mode"
377 .Vb 2
378 \& $db\->sync_mode;
379 \& $db\->sync_mode($bool);
380 .Ve
381 .PP
382 Returns the status of the automatic synchronization mode. Called with argument,
383 enables or disables the sync mode, depending on whether \f(CW$bool\fR is \fBtrue\fR or
384 \&\fBfalse\fR.
385 .PP
386 When synchronization mode is on (\fBtrue\fR), any changes to the database are
387 immediately written to the disk. This ensures database consistency in case
388 of any unforeseen errors (e.g. power failures), at the expense of considerable
389 slowdown of operation.
390 .PP
391 Synchronization mode is off by default.
392 .SS centfree
393 .IX Subsection "centfree"
394 .Vb 2
395 \& $db\->centfree;
396 \& $db\->centfree($bool);
397 .Ve
398 .PP
399 Returns status of the central free block pool (\fB0\fR \- disabled,
400 \&\fB1\fR \- enabled).
401 .PP
402 With argument, changes its status.
403 .PP
404 By default, central free block pool is disabled.
405 .SS coalesce
406 .IX Subsection "coalesce"
407 .Vb 2
408 \& $db\->coalesce;
409 \& $db\->coalesce($bool);
410 .Ve
411 .SS mmap
412 .IX Subsection "mmap"
413 .Vb 1
414 \& $db\->mmap;
415 .Ve
416 .PP
417 Returns true if memory mapping is enabled.
418 .PP
419 This method will \fBcroak\fR if the \fBlibgdbm\fR library is complied without
420 memory mapping support.
421 .SS mmapsize
422 .IX Subsection "mmapsize"
423 .Vb 2
424 \& $db\->mmapsize;
425 \& $db\->mmapsize($newsize);
426 .Ve
427 .PP
428 If memory mapping is enabled, returns the size of memory mapping. With
429 argument, sets the size to \fR\f(CB$newsize\fR\fB\fR.
430 .PP
431 This method will \fBcroak\fR if the \fBlibgdbm\fR library is complied without
432 memory mapping support.
433 .SS recover
434 .IX Subsection "recover"
435 .Vb 1
436 \& $db\->recover(%args);
437 .Ve
438 .PP
439 Recovers data from a failed database. \fR\f(CB%args\fR\fB\fR is optional and can contain
440 following keys:
441 .IP "err => sub { ... }" 4
442 .IX Item "err => sub { ... }"
443 Reference to code for detailed error reporting. Upon encountering an error,
444 \&\fBrecover\fR will call this sub with a single argument \- a description of the
445 error.
446 .IP "backup => \e$str" 4
447 .IX Item "backup => $str"
448 Creates a backup copy of the database before recovery and returns its
449 filename in \fR\f(CB$str\fR\fB\fR.
450 .ie n .IP "max_failed_keys => $n" 4
451 .el .IP "max_failed_keys => \f(CW$n\fR" 4
452 .IX Item "max_failed_keys => $n"
453 Maximum allowed number of failed keys. If the actual number becomes equal
454 to \fR\f(CI$n\fR\fI\fR, \fBrecover\fR aborts and returns error.
455 .ie n .IP "max_failed_buckets => $n" 4
456 .el .IP "max_failed_buckets => \f(CW$n\fR" 4
457 .IX Item "max_failed_buckets => $n"
458 Maximum allowed number of failed buckets. If the actual number becomes equal
459 to \fR\f(CI$n\fR\fI\fR, \fBrecover\fR aborts and returns error.
460 .ie n .IP "max_failures => $n" 4
461 .el .IP "max_failures => \f(CW$n\fR" 4
462 .IX Item "max_failures => $n"
463 Maximum allowed number of failures during recovery.
464 .IP "stat => \e%hash" 4
465 .IX Item "stat => %hash"
466 Return recovery statistics in \fR\f(CI%hash\fR\fI\fR. Upon return, the following keys will
467 be present:
468 .RS 4
469 .IP recovered_keys 8
470 .IX Item "recovered_keys"
471 Number of successfully recovered keys.
472 .IP recovered_buckets 8
473 .IX Item "recovered_buckets"
474 Number of successfully recovered buckets.
475 .IP failed_keys 8
476 .IX Item "failed_keys"
477 Number of keys that failed to be retrieved.
478 .IP failed_buckets 8
479 .IX Item "failed_buckets"
480 Number of buckets that failed to be retrieved.
481 .RE
482 .RS 4
483 .RE
484 .SS convert
485 .IX Subsection "convert"
486 .Vb 1
487 \& $db\->convert($format);
488 .Ve
489 .PP
490 Changes the format of the database file referred to by \fR\f(CB$db\fR\fB\fR.
491 .PP
492 Starting from version 1.20, \fBgdbm\fR supports two database file formats:
493 \&\fIstandard\fR and \fIextended\fR. The former is the traditional database
494 format, used by previous \fBgdbm\fR versions. The \fIextended\fR format contains
495 additional data and is recommended for use in crash tolerant applications.
496 .PP
497 <https://www.gnu.org.ua/software/gdbm/manual/Numsync.html>, for the
498 discussion of both formats.
499 .PP
500 The \fR\f(CB$format\fR\fB\fR argument sets the new desired database format. It is
501 \&\fBGDBM_NUMSYNC\fR to convert the database from standard to extended format, and
502 \&\fB0\fR to convert it from extended to standard format.
503 .PP
504 If the database is already in the requested format, the function returns
505 success without doing anything.
506 .SS dump
507 .IX Subsection "dump"
508 .Vb 1
509 \& $db\->dump($filename, %options)
510 .Ve
511 .PP
512 Creates a dump of the database file in \fR\f(CI$filename\fR\fI\fR. Such file can be used
513 as a backup copy or sent over a wire to recreate the database on another
514 machine. To create a database from the dump file, use the \fBload\fR method.
515 .PP
516 \&\fBGDBM\fR supports two dump formats: old \fIbinary\fR and new \fIascii\fR. The
517 binary format is not portable across architectures and is deprecated. It
518 is supported for backward compatibility. The ascii format is portable and
519 stores additional meta-data about the file. It was introduced with the
520 \&\fBgdbm\fR version 1.11 and is the preferred dump format. The \fBdump\fR method
521 creates ascii dumps by default.
522 .PP
523 If the named file already exists, the function will refuse to overwrite and
524 will croak an error. If it doesn't exist, it will be created with the
525 mode \fB0666\fR modified by the current \fBumask\fR.
526 .PP
527 These defaults can be altered using the following \fR\f(CI%options\fR\fI\fR:
528 .IP "\fBbinary\fR => 1" 4
529 .IX Item "binary => 1"
530 Create dump in \fIbinary\fR format.
531 .IP "\fBmode\fR => \fIMODE\fR" 4
532 .IX Item "mode => MODE"
533 Set file mode to \fIMODE\fR.
534 .IP "\fBoverwrite\fR => 1" 4
535 .IX Item "overwrite => 1"
536 Silently overwrite existing files.
537 .SS load
538 .IX Subsection "load"
539 .Vb 1
540 \& $db\->load($filename, %options)
541 .Ve
542 .PP
543 Load the data from the dump file \fR\f(CI$filename\fR\fI\fR into the database \fI\fR\f(CI$db\fR\fI\fR.
544 The file must have been previously created using the \fBdump\fR method. File
545 format is recognized automatically. By default, the function will croak
546 if the dump contains a key that already exists in the database. It will
547 silently ignore the failure to restore database mode and/or ownership.
548 These defaults can be altered using the following \fI\fR\f(CI%options\fR\fI\fR:
549 .IP "\fBreplace\fR => 1" 4
550 .IX Item "replace => 1"
551 Replace existing keys.
552 .IP "\fBrestore_mode\fR => 0 | 1" 4
553 .IX Item "restore_mode => 0 | 1"
554 If \fI0\fR, don't try to restore the mode of the database file to that stored
555 in the dump.
556 .IP "\fBrestore_owner\fR => 0 | 1" 4
557 .IX Item "restore_owner => 0 | 1"
558 If \fI0\fR, don't try to restore the owner of the database file to that stored
559 in the dump.
560 .IP "\fBstrict_errors\fR => 1" 4
561 .IX Item "strict_errors => 1"
562 Croak if failed to restore ownership and/or mode.
563 .PP
564 The usual sequence to recreate a database from the dump file is:
565 .PP
566 .Vb 3
567 \& my %hash;
568 \& my $db = tie %hash, \*(AqGDBM_File\*(Aq, \*(Aqa.db\*(Aq, GDBM_NEWDB, 0640;
569 \& $db\->load(\*(Aqa.dump\*(Aq);
570 .Ve
571 .SH "CRASH TOLERANCE"
572 .IX Header "CRASH TOLERANCE"
573 Crash tolerance is a new feature that, given appropriate support from the OS
574 and the filesystem, guarantees that a logically consistent recent state of the
575 database can be recovered following a crash, such as power outage, OS kernel
576 panic, or the like.
577 .PP
578 Crash tolerance support appeared in \fBgdbm\fR version 1.21. The theory behind
579 it is explained in "Crashproofing the Original NoSQL Key-Value Store",
580 by Terence Kelly (<https://queue.acm.org/detail.cfm?id=3487353>). A
581 detailed discussion of the \fBgdbm\fR implementation is available in the
582 \&\fBGDBM Manual\fR (<https://www.gnu.org.ua/software/gdbm/manual/Crash\-Tolerance.html>). The information below describes the Perl interface.
583 .PP
584 For maximum robustness, we recommend to use \fIextended database format\fR
585 for crash tolerant databases. To create a database in extended format,
586 use the \fBGDBM_NEWDB|GDBM_NUMSYNC\fR when opening the database, e.g.:
587 .PP
588 .Vb 2
589 \& $db = tie %hash, \*(AqGDBM_File\*(Aq, $filename,
590 \& GDBM_NEWDB|GDBM_NUMSYNC, 0640;
591 .Ve
592 .PP
593 To convert existing database to the extended format, use the \fBconvert\fR
594 method, described above, e.g.:
595 .PP
596 .Vb 1
597 \& $db\->convert(GDBM_NUMSYNC);
598 .Ve
599 .SS crash_tolerance_status
600 .IX Subsection "crash_tolerance_status"
601 .Vb 1
602 \& GDBM_File\->crash_tolerance_status;
603 .Ve
604 .PP
605 This static method returns the status of crash tolerance support. A
606 non-zero value means crash tolerance is compiled in and supported by
607 the operating system.
608 .SS failure_atomic
609 .IX Subsection "failure_atomic"
610 .Vb 1
611 \& $db\->failure_atomic($even, $odd)
612 .Ve
613 .PP
614 Enables crash tolerance for the database \fR\f(CB$db\fR\fB\fR, Arguments are
615 the pathnames of two files that will be created and filled with
616 \&\fIsnapshots\fR of the database file. The two files must not exist
617 when this method is called and must reside on the same filesystem
618 as the database file. This filesystem must be support the \fIreflink\fR
619 operation (https://www.gnu.org.ua/software/gdbm/manual/Filesystems\-supporting\-crash\-tolerance.html>.
620 .PP
621 After a successful call to \fBfailure_atomic\fR, every call to \fR\f(CB$db\fR\fB\-\fRsync>
622 method will make an efficient reflink snapshot of the database file in
623 one of these files; consecutive calls to \fBsync\fR alternate between the
624 two, hence the names.
625 .PP
626 The most recent of these files can be used to recover the database after
627 a crash. To select the right snapshot, use the \fBlatest_snapshot\fR
628 static method.
629 .SS latest_snapshot
630 .IX Subsection "latest_snapshot"
631 .Vb 1
632 \& $file = GDBM_File\->latest_snapshot($even, $odd);
633 \&
634 \& ($file, $error) = GDBM_File\->latest_snapshot($even, $odd);
635 .Ve
636 .PP
637 Given the two snapshot names (the ones used previously in a call to
638 \&\fBfailure_atomic\fR), this method selects the one suitable for database
639 recovery, i.e. the file which contains the most recent database snapshot.
640 .PP
641 In scalar context, it returns the selected file name or \fBundef\fR in case
642 of failure.
643 .PP
644 In array context, the returns a list of two elements: the file name
645 and status code. On success, the file name is defined and the code
646 is \fBGDBM_SNAPSHOT_OK\fR. On error, the file name is \fBundef\fR, and
647 the status is one of the following:
648 .IP GDBM_SNAPSHOT_BAD 4
649 .IX Item "GDBM_SNAPSHOT_BAD"
650 Neither snapshot file is applicable. This means that the crash has occurred
651 before a call to \fBfailure_atomic\fR completed. In this case, it is best to
652 fall back on a safe backup copy of the data file.
653 .IP GDBM_SNAPSHOT_ERR 4
654 .IX Item "GDBM_SNAPSHOT_ERR"
655 A system error occurred. Examine \fB$!\fR for details. See
656 <https://www.gnu.org.ua/software/gdbm/manual/Crash\-recovery.html> for
657 a comprehensive list of error codes and their meaning.
658 .IP GDBM_SNAPSHOT_SAME 4
659 .IX Item "GDBM_SNAPSHOT_SAME"
660 The file modes and modification dates of both snapshot files are exactly the
661 same. This can happen only for databases in standard format.
662 .IP GDBM_SNAPSHOT_SUSPICIOUS 4
663 .IX Item "GDBM_SNAPSHOT_SUSPICIOUS"
664 The \fInumsync\fR counters of the two snapshots differ by more than one. The
665 most probable reason is programmer's error: the two parameters refer to
666 snapshots belonging to different database files.
667 .SH AVAILABILITY
668 .IX Header "AVAILABILITY"
669 gdbm is available from any GNU archive. The master site is
670 \&\f(CW\*(C`ftp.gnu.org\*(C'\fR, but you are strongly urged to use one of the many
671 mirrors. You can obtain a list of mirror sites from
672 <http://www.gnu.org/order/ftp.html>.
673 .SH "SECURITY AND PORTABILITY"
674 .IX Header "SECURITY AND PORTABILITY"
675 GDBM files are not portable across platforms. If you wish to transfer
676 a GDBM file over the wire, dump it to a portable format first.
677 .PP
678 \&\fBDo not accept GDBM files from untrusted sources.\fR
679 .PP
680 Robustness of GDBM against corrupted databases depends highly on its
681 version. Versions prior to 1.15 did not implement any validity
682 checking, so that a corrupted or maliciously crafted database file
683 could cause perl to crash or even expose a security vulnerability.
684 Versions between 1.15 and 1.20 were progressively strengthened against
685 invalid inputs. Finally, version 1.21 had undergone extensive fuzzy
686 checking which proved its ability to withstand any kinds of inputs
687 without crashing.
688 .SH "SEE ALSO"
689 .IX Header "SEE ALSO"
690 \&\fBperl\fR\|(1), \fBDB_File\fR\|(3), perldbmfilter,
691 \&\fBgdbm\fR\|(3),
692 <https://www.gnu.org.ua/software/gdbm/manual.html>.