GDBM_File(3pm)

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           # Use the %hash array.
12
13           $e = $db->errno;
14           $e = $db->syserrno;
15           $str = $db->strerror;
16           $bool = $db->needs_recovery;
17
18           $db->clear_error;
19
20           $db->reorganize;
21           $db->sync;
22
23           $n = $db->count;
24
25           $n = $db->flags;
26
27           $str = $db->dbname;
28
29           $db->cache_size;
30           $db->cache_size($newsize);
31
32           $n = $db->block_size;
33
34           $bool = $db->sync_mode;
35           $db->sync_mode($bool);
36
37           $bool = $db->centfree;
38           $db->centfree($bool);
39
40           $bool = $db->coalesce;
41           $db->coalesce($bool);
42
43           $bool = $db->mmap;
44
45           $size = $db->mmapsize;
46           $db->mmapsize($newsize);
47
48           $db->recover(%args);
49
50           untie %hash ;
51

DESCRIPTION

53       GDBM_File is a module which allows Perl programs to make use of the
54       facilities provided by the GNU gdbm library.  If you intend to use this
55       module you should really have a copy of the gdbm manualpage at hand.
56
57       Most of the libgdbm.a functions are available through the GDBM_File
58       interface.
59
60       Unlike Perl's built-in hashes, it is not safe to "delete" the current
61       item from a GDBM_File tied hash while iterating over it with "each".
62       This is a limitation of the gdbm library.
63

STATIC METHODS

65   GDBM_version
66           $str = GDBM_File->GDBM_version;
67           @ar = GDBM_File->GDBM_version;
68
69       Returns the version number of the underlying libgdbm library. In scalar
70       context, returns the library version formatted as string:
71
72           MINOR.MAJOR[.PATCH][ (GUESS)]
73
74       where MINOR, MAJOR, and PATCH are version numbers, and GUESS is a guess
75       level (see below).
76
77       In list context, returns a list:
78
79           ( MINOR, MAJOR, PATCH [, GUESS] )
80
81       The GUESS component is present only if libgdbm version is 1.8.3 or
82       earlier. This is because earlier releases of libgdbm did not include
83       information about their version and the GDBM_File module has to
84       implement certain guesswork in order to determine it. GUESS is a
85       textual description in string context, and a positive number indicating
86       how rough the guess is in list context. Possible values are:
87
88       1  - exact guess
89           The major and minor version numbers are guaranteed to be correct.
90           The actual patchlevel is most probably guessed right, but can be
91           1-2 less than indicated.
92
93       2  - approximate
94           The major and minor number are guaranteed to be correct. The
95           patchlevel is set to the upper bound.
96
97       3  - rough guess
98           The version is guaranteed to be not newer than MAJOR.MINOR.
99

METHODS

101   close
102           $db->close;
103
104       Closes the database. You are not advised to use this method directly.
105       Please, use untie instead.
106
107   errno
108           $db->errno
109
110       Returns the last error status associated with this database.
111
112   syserrno
113           $db->syserrno
114
115       Returns the last system error status (C "errno" variable), associated
116       with this database,
117
118   strerror
119           $db->strerror
120
121       Returns textual description of the last error that occurred in this
122       database.
123
124   clear_error
125           $db->clear_error
126
127       Clear error status.
128
129   needs_recovery
130           $db->needs_recovery
131
132       Returns true if the database needs recovery.
133
134   reorganize
135           $db->reorganize;
136
137       Reorganizes the database.
138
139   sync
140           $db->sync;
141
142       Synchronizes recent changes to the database with its disk copy.
143
144   count
145           $n = $db->count;
146
147       Returns number of keys in the database.
148
149   flags
150           $db->flags;
151
152       Returns flags passed as 4th argument to tie.
153
154   dbname
155           $db->dbname;
156
157       Returns the database name (i.e. 3rd argument to tie.
158
159   cache_size
160           $db->cache_size;
161           $db->cache_size($newsize);
162
163       Returns the size of the internal GDBM cache for that database.
164
165       Called with argument, sets the size to $newsize.
166
167   block_size
168           $db->block_size;
169
170       Returns the block size of the database.
171
172   sync_mode
173           $db->sync_mode;
174           $db->sync_mode($bool);
175
176       Returns the status of the automatic synchronization mode. Called with
177       argument, enables or disables the sync mode, depending on whether $bool
178       is true or false.
179
180       When synchronization mode is on (true), any changes to the database are
181       immediately written to the disk. This ensures database consistency in
182       case of any unforeseen errors (e.g. power failures), at the expense of
183       considerable slowdown of operation.
184
185       Synchronization mode is off by default.
186
187   centfree
188           $db->centfree;
189           $db->centfree($bool);
190
191       Returns status of the central free block pool (0 - disabled, 1 -
192       enabled).
193
194       With argument, changes its status.
195
196       By default, central free block pool is disabled.
197
198   coalesce
199           $db->coalesce;
200           $db->coalesce($bool);
201
202   mmap
203           $db->mmap;
204
205       Returns true if memory mapping is enabled.
206
207       This method will croak if the libgdbm library is complied without
208       memory mapping support.
209
210   mmapsize
211           $db->mmapsize;
212           $db->mmapsize($newsize);
213
214       If memory mapping is enabled, returns the size of memory mapping. With
215       argument, sets the size to $newsize.
216
217       This method will croak if the libgdbm library is complied without
218       memory mapping support.
219
220   recover
221           $db->recover(%args);
222
223       Recovers data from a failed database. %args is optional and can contain
224       following keys:
225
226       err => sub { ... }
227           Reference to code for detailed error reporting. Upon encountering
228           an error, recover will call this sub with a single argument - a
229           description of the error.
230
231       backup => \$str
232           Creates a backup copy of the database before recovery and returns
233           its filename in $str.
234
235       max_failed_keys => $n
236           Maximum allowed number of failed keys. If the actual number becomes
237           equal to $n, recover aborts and returns error.
238
239       max_failed_buckets => $n
240           Maximum allowed number of failed buckets. If the actual number
241           becomes equal to $n, recover aborts and returns error.
242
243       max_failures => $n
244           Maximum allowed number of failures during recovery.
245
246       stat => \%hash
247           Return recovery statistics in %hash. Upon return, the following
248           keys will be present:
249
250           recovered_keys
251                   Number of successfully recovered keys.
252
253           recovered_buckets
254                   Number of successfully recovered buckets.
255
256           failed_keys
257                   Number of keys that failed to be retrieved.
258
259           failed_buckets
260                   Number of buckets that failed to be retrieved.
261

AVAILABILITY

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

SECURITY AND PORTABILITY

269       Do not accept GDBM files from untrusted sources.
270
271       GDBM files are not portable across platforms.
272
273       The GDBM documentation doesn't imply that files from untrusted sources
274       can be safely used with "libgdbm".
275
276       A maliciously crafted file might cause perl to crash or even expose a
277       security vulnerability.
278