1Geo::IPfree(3)        User Contributed Perl Documentation       Geo::IPfree(3)
2
3
4

NAME

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

SYNOPSIS

9           use Geo::IPfree;
10
11           my $geo = Geo::IPfree->new;
12           my( $code1, $name1 ) = $geo->LookUp( '200.176.3.142' );
13
14           # use memory to speed things up
15           $geo->Faster;
16
17           # lookup by hostname
18           my( $code2, $name2, $ip2 ) = $geo->LookUp( 'www.cnn.com' );
19

DESCRIPTION

21       Geo::IPfree is a Perl module that determines the originating country of
22       an arbitrary IPv4 address. It uses a local file-based database to
23       provide basic geolocation services.
24
25       An updated version of the database can be obtained by visiting the
26       Webnet77 website: http://software77.net/geo-ip/
27       <http://software77.net/geo-ip/>.
28

METHODS

30   new( [$db] )
31       Creates a new Geo::IPfree instance. Optionally, a database filename may
32       be passed in to load a custom data set rather than the version shipped
33       with the module.
34
35   LoadDB( $filename )
36       Load the database to use to LookUp the IPs.
37
38   LookUp( $ip|$hostname )
39       Given an ip address or a hostname, this function returns three things:
40
41       ·   The ISO 3166 country code (2 chars)
42
43       ·   The country name
44
45       ·   The IP address resolved
46
47       NB: In order to use the location services on a hostname, you will need
48       to have an internet connection to resolve a host to an IP address.
49
50   Clean_Cache( )
51       Clears any cached lookup data.
52
53   Faster( )
54       Make the LookUp() faster, good for big amount of LookUp()s. This will
55       load all the DB in the memory (639Kb) and read from there, not from HD
56       (good way for slow HD or network disks), but use more memory. The
57       module "Memoize" will be enabled for some internal functions too.
58
59       Note that if you make a big amount of querys to LookUp(), in the end
60       the amount of memory can be big, than is better to use more memory from
61       the begin and make all faster.
62
63   nslookup( $host, [$last_lookup] )
64       Attempts to resolve a hostname to an IP address. If it fails on the
65       first pass it will attempt to resolve the same hostname with 'www.'
66       prepended. $last_lookup is used to supress this behavior.
67
68   ip2nb( $ip )
69       Encodes $ip into a numerical representation.
70
71   nb2ip( $number )
72       Decodes $number back to an IP address.
73
74   dec2baseX( $number )
75       Converts a base 10 (decimal) number to base 86.
76
77   baseX2dec( $number )
78       Converts a base 86 number to base 10 (decimal).
79

VARS

81       $GeoIP->{db}
82           The database file in use.
83
84       $GeoIP->{handler}
85           The database file handler.
86
87       $GeoIP->{dbfile}
88           The database file path.
89
90       $GeoIP->{cache} BOOLEAN
91           Set/tell if the cache of LookUp() is on. If it's on it will cache
92           the last 1000 querys. Default: 1
93
94           The cache is good when you are parsing a list of IPs, generally a
95           web log.  If in the log you have many lines with the same IP,
96           GEO::IPfree don't need to make a full search for each query, it
97           will cache the last 1000 different IPs. After each 1000 IPs the
98           cache is cleaned to restart it.
99
100           Note that the Lookup make the query without the last IP number
101           (xxx.xxx.xxx.0), then the cache for the IP 192.168.0.1 will be the
102           same for 192.168.0.2 (they are the same query, 192.168.0.0).
103

DB FORMAT

105       the DB has a list of IP ranges & countrys, for example, from
106       200.128.0.0 to 200.103.255.255 the IPs are from BR. To make a fast
107       access to the DB the format try to use less bytes per input (block).
108       The file was in ASCII and in blocks of 7 bytes: XXnnnnn
109
110         XX    -> the country code (BR,US...)
111         nnnnn -> the IP range using a base of 85 digits
112                  (not in dec or hex to get space).
113
114       See CPAN for updates of the DB...
115

NOTES

117       The file ipscountry.dat is made only for Geo::IPfree and has their own
118       format.  To convert it see the tool "ipct2txt.pl" in the "misc"
119       directoy.
120
121       The module looks for "ipscountry.dat" in the following locations:
122
123       ·   /usr/local/share
124
125       ·   /usr/local/share/GeoIPfree
126
127       ·   through @INC (as well as all @INC directories plus "/Geo")
128
129       ·   from the same location that IPfree.pm was loaded
130

SEE ALSO

132       ·   http://software77.net/geo-ip/
133

AUTHOR

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

MAINTAINER

138       Brian Cassidy <bricas@cpan.org>
139

THANK YOU

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

146       This program is free software; you can redistribute it and/or modify it
147       under the same terms as Perl itself.
148
149
150
151perl v5.12.1                      2010-06-14                    Geo::IPfree(3)
Impressum