TDB_File - Perl access to the trivial database library
use TDB_File;
# tie interface
tie %hash, 'TDB_File', $filename, TDB_DEFAULT, O_RDWR, 0664;
$hash{key} = 'value';
while (my ($k,$v) = each %hash) { print "$k -> $v\n" }
# OO interface
my $tdb = TDB_File->open($filename, TDB_CLEAR_IF_FIRST) or die $!;
$tdb->store(key => 'value') or die $tdb->errorstr;
$tdb->traverse(sub { print "$_[0] -> $_[1]\n" });
TDB is a simple database similar to gdbm, but allows multiple simultaneous writers.
TDB_File provides a simple tie interface, similar to DB_File and friends; and an object-oriented interface, which provides access to all of the functions in the tdb library.
TDB_File constructor. Opens FILE and returns a TDB_File object. The same arguments may be passed to the tie function. On error, $! is set and undef is returned.
See tdb_open(3) for the meanings and possible values of TDB_FLAGS and HASH_SIZE.
OPEN_FLAGS and MODE are standard open(3) options. In perl, the relevant constants may be imported from the Fcntl module.
LOG_FN is a coderef or the name of a function to be called when this TDB object encounters errors. See "$tdb->logging_function(SUB)".
HASH_FN is a coderef or the name of a function to be called to generate key hashes. This argument is unsupported in some TDB libraries and will generate a Perl warning when this arg is specified. NB: See "BUGS" for a limitation in the current implementation.
Each argument except FILE has a reasonable default and may be omitted, so these two function calls are identical:
TDB_File->open('foo.tdb');
TDB_File->open('foo.tdb', TDB_DEFAULT, O_RDWR|O_CREAT, 0666,
0, undef, undef);
Note that the HASH_SIZE argument appears in a different position than in the C tdb_open(3) function.
There is no explicit close function. The database is closed implicitly when there are no remaining references.
Store VALUE in the database with key KEY. FLAG defaults to TDB_REPLACE, see tdb_store(3) for other values.
On failure, a perl false is returned. See "$tdb->error" and "$tdb->errorstr" for the reason.
Fetch the value associated with KEY, or undef if it is not found.
Delete the value associated with KEY.
On failure, a perl false is returned. See "$tdb->error" and "$tdb->errorstr" for the reason.
Return true if the KEY is found, false otherwise.
Return the key of the first value in the database. Returns undef on failure or if there are no keys in the database. See tdb_firstkey(3) for details.
Return the next key in the database after LASTKEY. Returns undef on failure or if there are no more keys in the database. See tdb_nextkey(3) for details.
Returns the current error state of the $tdb object. See the list of error codes given in "Exportable constants".
Returns a printable string that describes the error state of the database.
Closes and reopens the database. Required after a fork, if both processes wish to use the database.
NB: If reopen fails (returns false), then it is unsafe to call any further methods on $tdb. Thus, the only way to find out why reopen failed is to use a logging function.
Closes and reopens all open databases. See "$tdb->reopen".
NB: If reopen_all fails (returns false), there is no indication of which $tdb objects failed or why. If you have to survive failures, you may wish to do your own reopen loop instead.
Call SUB for each entry in the database. SUB should be a coderef or a string giving the name of a function.
SUB is called with the key and value as arguments and should return a true value if you wish to continue traversal.
traverse returns the number of elements traversed or undef on error. If SUB is undef, then this function simply counts the number of elements.
Set the logging function to use when this database object encounters errors. SUB should be a coderef or a string giving the name of a function.
SUB is called with the severity level (an integer) and the message (a string).
Locks a group of keys, returning false on error.
This is unnecessary when using fetch, store, etc. See tdb_chainlock(3).
Unlock a group of keys locked by "$tdb->chainlock(KEY)".
Lock an entire database, returning false on error.
Unlock an entire database previously locked with "$tdb->lockall".
Dump the records and freelist to STDOUT in an almost human readable form.
Dump the freelist to STDOUT.
All constants are exported by default.
Individually or with the tag :flags:
TDB_REPLACE TDB_INSERT TDB_MODIFY TDB_DEFAULT TDB_CLEAR_IF_FIRST TDB_INTERNAL TDB_NOLOCK TDB_NOMMAP TDB_CONVERT TDB_BIGENDIAN
Individually or with the tag :error:
TDB_SUCCESS TDB_ERR_CORRUPT TDB_ERR_IO TDB_ERR_LOCK TDB_ERR_OOM TDB_ERR_EXISTS TDB_ERR_NOLOCK TDB_ERR_LOCK_TIMEOUT TDB_ERR_NOEXIST
There is no way to survive an error during reopen_all. Unfortunately this is a limitation in the TDB C API.
Currently the hash function (if set) is set globally, so the last logging function to be set will be used for all TDB_File objects that specify a hash function. This is due to a limitation in the TDB C API.
tdb(3), perltie.
Angus Lees, <gus@inodes.org>
