Debian Codegraph @

upstream/opensuse-tumbleweed/man3/GDBM_File.3pm

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