Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

bdbtarpit
api

bdbtarpit - api


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, the IPTables::IPv4::DBTarpit manpage

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy