NAME

TDB_File - Perl access to the trivial database library

SYNOPSIS

  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" });

DESCRIPTION

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.

FUNCTIONS

TDB_File->open(FILE [, TDB_FLAGS [, OPEN_FLAGS [, MODE [, HASH_SIZE [, LOG_FN [, HASH_FN]]]]]])

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. 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.

$tdb->store(KEY, VALUE [, FLAG])

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.

$tdb->fetch(KEY)

Fetch the value associated with KEY, or undef if it is not found.

$tdb->delete(KEY)

Delete the value associated with KEY.

On failure, a perl false is returned. See "$tdb->error" and "$tdb->errorstr" for the reason.

$tdb->exists(KEY)

Return true if the KEY is found, false otherwise.

$tdb->firstkey

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.

$tdb->nextkey(LASTKEY)

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.

$tdb->error

Returns the current error state of the $tdb object. See the list of error codes given in "Exportable constants".

$tdb->errorstr

Returns a printable string that describes the error state of the database.

$tdb->reopen

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.

TDB_File::reopen_all

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.

$tdb->traverse(SUB)

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.

$tdb->logging_function(SUB)

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).

$tdb->chainlock(KEY)

Locks a group of keys, returning false on error.

This is unnecessary when using fetch, store, etc. See tdb_chainlock(3).

$tdb->chainunlock(KEY)

Unlock a group of keys locked by "$tdb->chainlock(KEY)".

$tdb->lockall

Lock an entire database, returning false on error.

$tdb->unlockall

Unlock an entire database previously locked with "$tdb->lockall".

$tdb->dump_all

Dump the records and freelist to STDOUT in an almost human readable form.

$tdb->printfreelist

Dump the freelist to STDOUT.

EXPORT

All constants are exported by default.

Exportable constants

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

BUGS

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.

SEE ALSO

tdb(3), perltie.

AUTHOR

Angus Lees, <gus@inodes.org>