Gecko [ fernandoquevedodop.com ]

Name	Size	Permission
IPfree.pm	11.56 KB	-rw-r--r--
IPfree.pod	5.45 KB	-rw-r--r--
METAR.pm	46.42 KB	-rw-r--r--
ipscountry.dat	1.04 MB	-rw-r--r--

Code Editor : IPfree.pod

# PODNAME: Geo::IPfree
# ABSTRACT: Geo::IPfree - Look up the country of an IPv4 address

__END__

=pod

=encoding UTF-8

=head1 NAME

Geo::IPfree - Geo::IPfree - Look up the country of an IPv4 address

=head1 VERSION

version 1.160000

=head1 SYNOPSIS

use Geo::IPfree;
    
    my $geo = Geo::IPfree->new;
    my( $code1, $name1 ) = $geo->LookUp( '200.176.3.142' );
    
    # use memory to speed things up
    $geo->Faster;
    
    # lookup by hostname
    my( $code2, $name2, $ip2 ) = $geo->LookUp( 'www.cnn.com' );

=head1 DESCRIPTION

Geo::IPfree is a Perl module that determines the originating country of an
arbitrary IPv4 address. It uses a local file-based database to provide basic
geolocation services.

An updated version of the database can be obtained by visiting the Webnet77 
website: L<http://software77.net/geo-ip/>.

=head1 METHODS

=head2 new( [$db] )

Creates a new Geo::IPfree instance. Optionally, a database filename may be
passed in to load a custom data set rather than the version shipped with the
module.

=head2 LoadDB( $filename )

Load a specific database to use to look up the IP addresses.

=head2 LookUp( $ip | $hostname )

Given an IP address or a hostname, this function returns three things:

=over 4

=item * The ISO 3166 country code (2 chars)

=item * The country name

=item * The IP address resolved

=back

B<NB:> In order to use the location services on a hostname, you will need
to have an internet connection to resolve a host to an IP address.

If you pass a private IP address (for example 192.168.0.1), you'll get back a country
code of ZZ, and country name of "Reserved for private IP addresses".

=head2 Clean_Cache( )

Clears any cached lookup data.

=head2 Faster( )

Make the LookUp() faster, which is good if you're going to be calling Lookup() many times. This will load the entire DB into memory and read from there,
not from disk (good way for slow disk or network disks), but use more memory. The module "Memoize" will be enabled for some internal functions too.

Note that if you call Lookup() many times, you'll end up using a lot of memory anyway, so you'll be better off using a lot of memory from the start by calling Faster(),
and getting an improvement for all calls.

=head2 nslookup( $host, [$last_lookup] )

Attempts to resolve a hostname to an IP address. If it fails on the first pass
it will attempt to resolve the same hostname with 'www.' prepended. C<$last_lookup>
is used to suppress this behavior.

=head2 ip2nb( $ip )

Encodes C<$ip> into a numerical representation.

=head2 nb2ip( $number )

Decodes C<$number> back to an IP address.

=head2 dec2baseX( $number )

Converts a base 10 (decimal) number to base 86.

=head2 baseX2dec( $number )

Converts a base 86 number to base 10 (decimal).

=head2 get_all_countries()

Returns one Hash Ref with the list of known countries.
The key is the ISO 3166 country code (2 chars) and the value the country name in english.

Example:

{
           '--' => 'N/A',
           'A1' => 'Anonymous Proxy',
           'A2' => 'Satellite Provider',
           'AC' => 'Ascension Island',
           'AD' => 'Andorra',
           'AE' => 'United Arab Emirates',
           'AF' => 'Afghanistan',
           'AG' => 'Antigua and Barbuda',
           ...
        }

=head1 VARS

=over 4

=item $GeoIP->{db}

The database file in use.

=item $GeoIP->{handler}

The database file handler.

=item $GeoIP->{dbfile}

The database file path.

=item $GeoIP->{cache} BOOLEAN

Set/tell if the cache of LookUp() is on. If it's on it will cache the last 5000 queries. Default: 1

The cache is good when you are parsing a list of IPs, generally a web log.
If in the log you have many lines with the same IP, GEO::IPfree won't have to make a full search for each query,
it will cache the last 5000 different IPs. After 5000 IPs an existing IP is removed from the cache and the new
data is stored.

Note that the Lookup make the query without the last IP number (xxx.xxx.xxx.0),
then the cache for the IP 192.168.0.1 will be the same for 192.168.0.2 (they are the same query, 192.168.0.0).

=back

=head1 DB FORMAT

The data file has a list of IP ranges & countries, for example, from 200.128.0.0 to
200.103.255.255 the IPs are from BR. To make a fast access to the DB the format
tries to use less bytes per input (block). The file was in ASCII and in blocks
of 7 bytes: XXnnnnn

XX    -> the country code (BR,US...)
  nnnnn -> the IP range using a base of 85 digits
           (not in dec or hex to get space).

See CPAN for updates of the DB...

=head1 NOTES

The file ipscountry.dat is a dedicated format for Geo::IPfree.
To convert it see the tool "ipct2txt.pl" in the C<misc> directoy.

The module looks for C<ipscountry.dat> in the following locations:

=over 4

=item * /usr/local/share

=item * /usr/local/share/GeoIPfree

=item * through @INC (as well as all @INC directories plus "/Geo")

=item * from the same location that IPfree.pm was loaded

=back

=head1 SEE ALSO

=over 4

=item * http://software77.net/geo-ip/

=back

=head1 MAINTAINER

Brian Cassidy E<lt>bricas@cpan.orgE<gt>

=head1 THANK YOU

Thanks to Laurent Destailleur (author of AWStats) that tested it on many OS and
fixed bugs for them, like the not portable sysread, and asked for some speed improvement.

=head1 AUTHOR

Graciliano M. P. <gm@virtuasites.com.br>

=head1 COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut

${this.title}

Code Editor : IPfree.pod