Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  WHOSEIP::DB (3)

.ds Aq ’


Whoseip::DB - WhoseIP cache database



use Whoseip::DB; use Whoseip::DB qw(:all);

$dbf = Whoseip::DB::ipdb_open($filename[,
pagesize => $psize,
cachesize => $csize]);

$ref = Whoseip::DB::ipdb_lookup($ip); print $ref->{country} if defined($ref);

Whoseip::DB::ipdb_insert($dbf,, ’US’);



The <B>Whoseip::DBB> package provides functions for creating and accessing a <B>whoseipB>(1) cache database. This database is analogous to a GeoIP database, except that it keeps more information.

The database is kept in a single file and consists of <B>pagesB> of the same size. The file begins with a 512-byte header block of the following structure:

<B>OffsetB> <B>SizeB> <B>DescriptionB>
8 2 major version
10 2 minor version
12 16 UUID
28 4
page size
32 4 number of allocated pages
36 4 number of entries in root index table
40 472 root index table

The first three fields serve to identify the file format and its version. At the time of this writing, major and minor versions are <B>1B>.<B>0B>.

<B>Page sizeB> defines the size of the file page. It defaults to 1280 bytes.

Pages are of two types: <B>index pagesB>, that serve to navigate through the file, and <B>leaf pagesB>, that keep actual data. The <B>root index tableB>, located at the end of the file header keeps offsets of the initial index page for IP addresses of different sizes kept in the database. Each entry in this table consists of two 32-bit words: the first one keeps the length of the IP address in bits (e.g. 32 for IPv4 and 128 for IPv6), and the second one keeps the offset of the first index table for entries of that size. The table can accomodate at most 59 entries, which is more than enough for the purpose.

An <B>index pageB> contains a table of offsets of the next page to look up (whether index or leaf) and is indexed by the octet value (0 — 255). An extra slot keeps the offset of the leaf page. The overall structure of an index page is as follows:

<B>OffsetB> <B>SizeB> <B>DescriptionB>
0 4 Index page type: <B>1B>
4 4 OFF[0]
8 4 OFF[1]
. . .
. . .
. . .
1024 4 OFF[255]
1028 4 OFF[LEAF]

When looking up for an IP address, index pages are descended starting from the root page. The octets of the IP address in host order are iterated from left to right. Each subsequent octet is used to select offset of the next page from the current index page. If the corresponding offset is zero the last entry (<B>OFF[LEAF]B>) is used. This process stops when the <B>leaf pageB> is encountered.

A <B>leaf pageB> contains a table of <B>CIDRB>s and their descriptions. Its structure is as follows:

<B>OffsetB> <B>SizeB> <B>DescriptionB>
0 4 Leaf page type: <B>2B>
4 4 Number of entries in the table
8 4 Offset of the continuation page (0 if none)

     12        4        Entry 0: network address
     16        4        Entry 0: network mask
     20        4        Entry 0: timestamp
     24        2        Entry 0: ISO 3166-1 country code
     26        4        Entry 0: length of additional data
     30        ?        Entry 0: additional data
     .         .        .
     .         .        .
     .         .        .

     12+N*14   4        Entry N: network address          
     16+N*14   4        Entry N: network mask             
     20+N*14   4        Entry N: timestamp                
     24+N*14   2        Entry N: ISO 3166-1 country code
     26+N*14   4        Entry N: length of additional data
     30+N*14   ?        Entry N: additional data

When a leaf page is encountered, the IP address in question is compared with each entry in turn using the usual procedure (<B>ANDB>ing with the network mask and comparing the result with the network address). Search stops when a matching entry is found. Very large tables can span several leaf pages: if no entry matches in the current page, the search continues at the continuation page whose offset is indicated by the third field. If that field is 0, the search returns failure.

BICB$dbfBI = Whoseip::DB::ipdb_open(BICB$filenameBI[, options]);

Opens the database file $filename and returns a descriptor to be used for searches in that file. options is a hash that can contain the following keys:
<B>pagesizeB> Page size for the file. This option is honoured only when creating the file. It cannot be less than 1032 bytes. Default is 1280 bytes.
<B>cachesizeB> Maximum number of pages to keep in a <B>LRUB> cache. Defaults to 16.

Whoseip::DB::ipdb_locker(BICB$dbfBI[, BIopts]);

Lock or unlock the database.

opts is a hash of the following options:
<B>lockB> => MODE Defines the locking operation. MODE is one of: <B>exclusiveB> or <B>LOCK_EXB>, <B>sharedB> or <B>LOCK_SHB>, <B>unlockB> or <B>LOCK_UNB>.

If this option is not supplied, no locking will be done. This is useful to force syncronization with the disk state.

<B>syncB> => <B>0B>|<B>1B> When set to <B>0B>, disables synchronization with the disk file. Default is <B>1B>.


Sunchronizes the database with the disk.


Close the database. $dbf is the handle returned from the previous call to <B>ipdb_openB>.

CW$res = Whoseip::DB::ipdb_lookup(BICB$dbfBI, BICB$ipBI);

Look up IP address $ip in the database identified by $dbf (a handle returned by the previous call to <B>ipdb_openB>. If found, <B>B>$ref<B>B> is a reference to a hash that contains the following keys:
<B>countryB> ISO 3166-1 country code
<B>networkB> Network address in a dotted-quad form.
<B>netmaskB> Network mask in a dotted-quad form.
If not found, the function returns <B>undefB>.

CW$res = Whoseip::DB::ipdb_insert(BICB$dbfBI, BICB$cidrBI, BICB$countryBI[, BICB$hashrefBI]);

Inserts into the database $cidr and the corresponding country code $country and additional data $hashref.

Currently, $cidr must be in the form <B>B>Net-address<B>/B>Netmask-length<B>B>.

<B>Whoseip::DB::ipdb_export(B>$dbf<B>B>[<B>, B>$fd<B>B>]<B>);B>

Exports database $dbf in a portable plain-text format to file identified by $fd (<B>STDOUTB> by default).

The created file can be transferred over the network and used to recreate the database via <B>Whoseip::DB::ipdb_importB>.

<B>B>$res<B> = Whoseip::DB::ipdb_import(B>$dbf<B>B>[<B>, B>$fd<B>B>]<B>);B>

Imports data from the file descriptor $fd (<B>STDINB> by default) into the database file $dbf. Returns 1 on success and 0 on failure.
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 WHOSEIP::DB (3) 2014-10-19

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.