SYNOPSIS

  use Mail::SpamCannibal::BDBclient qw(dataquery);

  [constants and functions from Socket avaliable for export]

  ($key,$val)=dataquery($how,$cursor_key,$name,$sockpath,$is_network);
  $count=retrieve($howmany,$cursor,$name,\@list,$sockpath,$is_network);

DESCRIPTION

Mail::SpamCannibal::BDBclient can retrieve either a single complete record (key + data) or a list of keys (IP addresses) from a BDBaccess daemon either on the local host via a UNIX domain socket, or on a remote host via a network connection.

($key,$val)=dataquery($how,$cursor_key,$name,$sockpath,$is_network);

Query a BDBaccess daemon for a single record.
$how = 0 lookup a record by key value
$how = 1 lookup a record by cursor (record number)
```
  $cursor_key   for $how = 0,
                IP address of the record of interest as
                returned by inet_ntoa('11.22.33.44')
         or     for $how = 1,
                the cursor (record number), where the 
                first valid record number is "1"
```
RETRIEVING DATABASE STATISTICS and VERSION NUMBER

The first record number in a Berkeley DB is record number ONE (1), there is no record ZERO (0). If the bdbaccess daemon is queried with $how = 1, for record ZERO (0), it will return the version number of the underlying database in a form that can be unpacked by inet_ntoa. The returned data record will contain the number of keys or unique records currently in the database. Both of these will be 32 bit fields.
```
  $name         the name of the database from which to
                fetch the record (usually 'evidence')
```
```
  $sockpath     the path to the socket filename, usually
                '/var/run/dbtarpit/bdbread'
        or
                a host and port to connect to in the form
                hostname:port or 123.11.22.10:port
```
```
  $is_network   zero for local socket, alarm timeout > 0
                if remote host. Timeout is in seconds.
```
On a successful lookup of a record, what is returned is the access key, a packed 4 byte network address as returned by inet_aton('11.22.33.44'), and the data found for the record. The data may be either a character string or a numeric value depending on which database was accessed. In the case of the 'evidence' database, it will be an character string.

If a record is not found or there is any other database error, $key will contain the value INADDR_NONE (the value returned by inet_aton('255.255.255.255') and $data will contain the error code returned by Berkeley DB.

If there is a catastrophic failure, such a failure to connect to the domain socket, dataquery will return 'undef' or and empty array () depending on the calling context and $@ will be set with the error.

$count=retrieve($howmany,$cursor,$name,\@list,$sockpath,$is_network);
Retrieve a list of $howmany keys from a BDBaccess daemon.

  $howmany = 2 -> 255   the number of keys to retrieve

  $cursor       the starting record number

  $name         the name of the database from which
                to fetch the record

  $listpointer  array reference in which to put list

  $sockpath     the path to the socket filename, usually
                '/var/run/dbtarpit/bdbread'
        or
                a host and port to connect to in the form
                hostname:port or 123.11.22.10:port

  $is_network   zero for local socket, alarm timeout > 0
                if remote host. Timeout is in seconds.

On successful lookup, returns the number of items found (this may be zero) and the list is filled accordingly with IP addresses in the form to be decoded by inet_ntoa. On failure, returns undef.

EXPORT

        none by default

EXPORT_OK

        dataquery
        retrieve

        all the functions and constants
        available from B<Socket>

AUTHOR

Michael Robinton <michael@bizsystems.com>

COPYRIGHT

Copyright 2003, Michael Robinton & BizSystems This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.