view release on metacpan or  search on metacpan

lib/IP/World.pod  view on Meta::CPAN

Mmap, keeps data in Mmap memory, may reduce total memory 
requirement of sibling processes. If your system doesn't support Mmap, 
1 operates like 0.

=item 2 or IP_WORLD_TINY

tiny, slow but saves memory by searching the database on disk using traditional
C library I/O calls.

=item 3 or IP_WORLD_TINY_PERL

tiny PerlIO, slow but saves memory by searching the database on disk using Perl
I/O calls.  If your system doesn't support Perl I/O, 3 works like 2.  If it
does, performance may differ between this option and the preceding one.

=back

=head3 getcc

  $ccod = $ipw->getcc($ipad);

I<$ipad> should contain an IP4 address in one of two formats:

=over 4

=item * a I<dotted quad> string like C<'13.117.255.3'>

=item * a 4-byte packed binary string produced by I<inet_aton> or
C<pack('C4', four values 0-255)>

=back

The return value from I<getcc> will always be a 2-character string.
For most IP addresses this will be one of the codes defined in
the ISO-3166 standard.  You can see these codes on
L<http://www.iso.org/iso/english_country_names_and_code_elements>.

Two return values indicate problems in determining the country code:

=over 4

=item * ** indicates that I<$ipad> was not in either of the
two formats described above.

=item * ?? indicates that the database doesn't include a mapping
for the IP address.

=back

=head2 SCRIPTS

Three Perl scripts are installed with IP::World:

=head3 maint_ip_world_db

The application checks whether new data is available from either data 
source.  If there is, it downloads the data and builds a new database.

You can run this manually to check for a new database, or (on a
server or other 24/7 system) you can schedule it for automatic
execution at a non-busy time.

In either case you should run I<maint_ip_world_db> with privilege to
rewrite the database file.  For Unix/Linux systems this means
running it as I<root>, such as by entering the command
C<sudo maint_ip_world_db>.

During installation, you will be asked if a command should be
executed by I<maint_ip_world_db> when a new database has been
created (e.g., to restart a web server that uses the database).

The install process for IP::World runs I<maint_ip_world_db> to ensure
that the most recent data is installed.  

=head3 ip_world_dump

Lists the database created by I<maint_ip_world_db>.

=head3 ip_cc_benchmark

Compares the performance of IP::World with that of similar modules.

=head2 PERFORMANCE

I<ip-benchmark> showed the following results in one run on the 
author's server:

  Module                       Total uS  uS/call  % not covered
  Geo::IP Standard               281982    68.84  32
  Geo::IP Memory Cache            25626     6.26  32
  IP::Country::Fast              131887    32.20  29
  IP::Country::Fast    packed    101378    24.75  29
  IP::World fast                   9311     2.27  27
  IP::World fast       packed      6965     1.70  27
  IP::World mmap                   9084     2.22  27
  IP::World mmap       packed      7023     1.71  27
  IP::World tinyC                207054    50.55  27
  IP::World tinyC      packed    210123    51.30  27
  IP::World tinyPerl             654634   159.82  27
  IP::World tinyPerl   packed    554801   135.45  27

I<packed> indicates conversion of a packed 32-bit IP address rather
than a text address.  I<ip-benchmark> uses the same set of random 
IP addresses for all of the modules in each execution.

=head2 TERMINOLOGY

Our scripts I<ip_world_dump> and I<ip-benchmark> both use the term 
'not covered' to describe IP addresses that do not map to country 
codes.  These fall into 4 categories:

=over 4

=item addresses that were once used but are no longer used,

=item addresses that are assigned for private use,

=item addresses that are not assigned/allocated, and

=item addresses that were assigned/allocated in the last month 
      or two, that our data sources do not yet include.