Michael Robinton > IPTables-IPv4-DBTarpit > bdbtarpit

Download:
IPTables-IPv4-DBTarpit-0.44.tar.gz

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Source  

NAME ^

bdbtarpit - api

Shared library for DBTarpit Berkeley DB access distributed with perl module IPTables::IPv4::DBTarpit

libdbtarpit.so.0.0.0

SYNOPSIS ^

Include the following statements in foo.xs and Makefile.PL

  /*    foo.xs  */
  ...

  #include <bdbtarpit.h>
  ...

  /* end foo.xs */

  ----------------------

  # Makefile.PL
  
  WriteMakefile(
        ...
        
        'LIBS'  => ['-ldb -ldbtarpit'],
        
        ...
  }

DESCRIPTION ^

This file contains the documentation of the bdbtarpit public API, specifically a listing of functions, macros, flags, and variables that may be used by extension writers. The interfaces of any functions that are not listed here are subject to change without notice. For this reason, blindly using functions listed is to be avoided when writing extensions.

item * DBTPD The structure that holds the instance of data passed to and from the shared library by your extension. One of these should be declared within your extension.

  #define DBTP_MAXdbf 10  /* maximum number of open databases */

  typedef struct {
    int     dberr;              /* BDB status returned */
    DB_ENV  * dbenv;            /* BDB environment descriptor */
    DBT     mgdbt;              /* BDB data descriptor */
    DBT     keydbt;             /* BDB key descriptor  */
    DB      * dbaddr[DBTP_MAXdbf]; /* BDB database descriptor */
    char    * dbfile[DBTP_MAXdbf]; /* BDB database name
  } DBTPD;

Declare a structure of this type in your extension

  DBTPD dptp;

For detailed explanation of DB_ENV, DBT, and DB; see the documentation for Berkeley DB at http://www.sleepycat.com

* int dbtp_init(DBTPD * dbtp, unsigned char * home, int index);

Initialize database(s).

  status = dbtp_init(&dbtp, home, index);

  DBTPD * dbtp
        Contains the array of database file name
        pointers char * dbfile

  char * home
        Pointer to the text of the absolute path
        to the Berkeley DB environment directory

  int index
        Normally -1, however if you wish to 
        initialize a SINGLE specific database
        which has a 'dbfile' array entry, this
        is the index to that specific file name

        If 'index' is specified with the value
        DB_RUNRECOVERY, then the old Berkeley DB
        environment will be destroyed and a new
        one created when the database(s) are opened.
        This requires a single controling thread.
        Since this is not a tranactional DB, there
        is no point in trying to use the DB_RECOVER
        flag. DBENV->remove is used instead.

The array 'dbfile' should contain pointers to the character strings representing the name of each database that should be opened. Pointers should be set in ascending order with unused pointers set to zero (NULL).

  i.e. 
        dbfile[0] -> first dbfile name
        dbfile[1] -> second dbfile name
        ... and so on...

The function returns zero (0) on success or the Berkeley DB error code on failure.

  dbtp->dberr is set to zero or the error code.

  dbtp->dbenv is set as the BDB environment pointer

  dbtp->dbaddr[n] is set as the database pointer
                  for each open database

* void dbtp_env_close(DBTPD * dbtp);

Close the environment opened by dbtp_init. Normally only used from within the shared library since it is done as part of dbtp_close.

  DBTPD * dbtp  pointer to private data structure

  dbtp->dbenv is set to NULL

* void dbtp_close(DBTPD * dbtp);

Close the environment and each open database found in dbtp->dbaddr

  DBTPD * dbtp  pointer to private data structure

  dbtp->dbaddr[n] is set to NULL

* int dbtp_index(DBTPD * dbtp, char * name);

Find and return the address index of 'name' in dbtp->dbaddr[n]

  DBTPD * dbtp  pointer to private data structure

  char * name   pointer to the name string of database

If the index is not found, the function returns -1

  dbtp->dberr is set to zero or the error code.

* int dbtp_get(DBTPD * dbtp, int ai, void * addr, size_t size);

Get a record by key from the database.

  DBTPD * dbtp  pointer to private data structure

  int ai        index to the database of interest

  void * addr   pointer to database key
                This is normally network address
                of the form returned by inet_aton
        i.e.    &in_addr.s_addr

  size_t size   sizeof(in_addr.saddr)

The function returns zero (0) on success or the Berkeley DB error code

  dbtp->dberr is set to zero or the error code.

  dbtp->keydbt contains the key information

  dbtp->mgdbt contains the data information

See the Berkeley DB documentation for DBT

* int dbtp_getrecno(DBTPD * dbtp, int ai, u_int32_t cursor);

Get a record by record number from the database.

  DBTPD * dbtp  pointer to private data structure

  int ai        index to the database of interest

  u_int32_t cursor      the record number

        NOTE: record numbers in the Berkeley DB
        database start with record number ONE (1)
        Trying to access record ZERO will return
        an error.

The function returns zero (0) on success or the Berkeley DB error code

  dbtp->dberr is set to zero or the error code.

  dbtp->keydbt contains the key information

  dbtp->mgdbt contains the data information

See the Berkeley DB documentation for DBT

* u_int32_t dbtp_stati(DBTPD * dbtp, int ai);

Returns the number of unique keys or records in a database.

If an error is encountered, the function will return zero (0). If you expect zero (0) keys in a database, check the error status code for success or failure.

  DBTPD * dbtp  pointer to private data structure

  int ai        index to the database of interest

* u_int32_t dbtp_statn(DBTPD * dbtp, char * name);

Get status by name instead of index.

Exactly the same as calling:

  u_int32_t number_of_keys;
  int ai = dbtp_index(&dbtp, name)
  number_of_keys = dbtp_stati(&dbtp, ai);

* int dbtp_readOne(DBTPD * dbtp, u_char how, int ai, void * ptr, int is_network);

This function provides a single access point to retrieve data and is implemented with calls to get and getrecno, described above.

  DBTPD * dbtp  pointer to private data structure

  u_char how    access method
        0  access by key
        1  access by record number

  int ai        index to the database of interest

  void * pointer
        a pointer to either the key or record
        record number depending on 'how'

  int is_network
        if true, the function will convert the 
        key and data records to and from
        host to network order as appropriate

If the function is called for access by record number with a record number of zero (0), the number of records and the version number of the host Berkeley DB database is returned as follows:

  The key will contain the version number as
  a packed network address which will expand
  to a string representing the version number 
  when fed to inet_ntoa

        i.e.    0.3.1.17

    dbtp->keydbt.data->[0] = 0;
    dbtp->keydbt.data->[1] = 3;
    dbtp->keydbt.data->[2] = 1;
    dbtp->keydbt.data->[3] = 17;

  data will contain the number of keys

    *(dbtp->mgdbt.data) = nkeys;

For standard access, the data is returned as for get and getrecno.

The function returns zero (0) on success or the Berkeley DB error code

  dbtp->dberr is set to zero or the error code.

  dbtp->keydbt contains the key information

  dbtp->mgdbt contains the data information

See the Berkeley DB documentation for DBT

* int dbtp_readDB(DBTPD * dbtp, u_char how, char * name, void * ptr, int is_network);

Read one record by name instead of index.

Exactly the same as calling:

  int status;
  int ai = dbtp_index(&dbtp, name)              
  status = dbtp_readDB(&dbtp,how,name,ptr,is_network)

* int dbtp_put(DBTPD * dbtp, int ai, void * addr, size_t asize, void * data, size_t dsize);

Put a record into a database.

  DBTPD * dbtp  pointer to private data structure

  int ai        index to the database of interest

  void * addr   pointer to database key
                This is normally network address
                of the form returned by inet_aton
        i.e.    &in_addr.s_addr

  size_t asize  sizeof(in_addr.saddr)

  void * data   pointer to data

  size_t dsize  sizeof(the data)

Returns zero (0) on success else the Berkeley DB error code.

  dbtp->dberr is set to zero or the error code.

* int dbtp_sync(DBTPD * dbtp, int ai);

Flush any cached information to disk.

In order for other threads to see information added to a database, it is necessary to flush it from the current session's cache to disk. This is normally done after each write or delete operation if these operations are asynchronisly. For multiple record or cursor operations, do a sync after completion to update the disk.

  DBTPD * dbtp  pointer to private data structure

  int ai        index to the database of interest

Returns zero (0) on success else the Berkeley DB error code.

  dbtp->dberr is set to zero or the error code.

* int dbtp_find_addr(DBTPD * dbtp, int ai, void * addr, u_int32_t timestamp);

Find a record by key from the dbtarpit database and return the data which will in the form of a 32 bit timestamp number as returned from:

        date +%s

  DBTPD * dbtp  pointer to private data structure

  int ai        index to the database of interest

  void * addr   pointer to database key
                This is normally network address
                of the form returned by inet_aton
        i.e.    &in_addr.s_addr

  Returns zero (0) if the record is found.
  Returns one (1) if the record is NOT found.

If the record IS found, then the timestamp is updated to the current time.

  dbtp->dberr is set to zero or the BDB error code.

  dbtp->keydbt contains the key information

  dbtp->mgdbt contains the 32 bit timestamp

* int dbtp_del(DBTPD * dbtp, int ai, void * addr, size_t size);

Delete a record from a database.

  DBTPD * dbtp  pointer to private data structure

  int ai        index to the database of interest

  void * addr   pointer to database key
                This is normally network address
                of the form returned by inet_aton
        i.e.    &in_addr.s_addr

  size_t asize  sizeof(in_addr.saddr)

Returns zero (0) on success else the Berkeley DB error code.

  dbtp->dberr is set to zero or the error code.

* int dbtp_notfound();

Returns the numeric code for DB_NOTFOUND

* char * dbtp_libversion(int * major, int * minor, int * patch);

The dbtp_version method returns a pointer to a string containing bdbtarpit version information. If major is non-NULL, the major version of the bdbtarpit release is stored in the memory to which it refers. If minor is non-NULL, the minor version of the bdbtarpit release is stored in the memory to which it refers. If patch is non-NULL, the patch version of the bdbtarpit release is stored in the memory to which it refers.

* char * dbtp_bdbversion(int * major, int * minor, int * patch);

The dbtp_version method returns a pointer to a string containing Berkeley DB version information. If major is non-NULL, the major version of the Berkeley DB release is stored in the memory to which it refers. If minor is non-NULL, the minor version of the Berkeley DB release is stored in the memory to which it refers. If patch is non-NULL, the patch version of the Berkeley DB release is stored in the memory to which it refers.

char * dbtp_strerror(int err);

The dbtp_strerror method returns an error message string corresponding to the error number. The interface is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) interface. If the error number error is greater than or equal to 0, then the string returned by the system interface strerror(3) is returned. If the error number is less than 0, an error string appropriate to the corresponding Berkeley DB library error is returned. For more information, see Error returns to applications.

AUTHOR ^

Michael Robinton <michael@bizsystems.com>

COPYRIGHT AND LICENCE ^

  Copyright 2003, Michael Robinton <michael@bizsystems.com>
 
  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.

SEE ALSO ^

BerkeleyDB, IPTables::IPv4::DBTarpit

syntax highlighting: