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

METHODS

29   new( [$db] )
30       Creates a new Geo::IPfree instance. Optionally, a database filename may
31       be passed in to load a custom data set rather than the version shipped
32       with the module.
33
34   LoadDB( $filename )
35       Load a specific database to use to look up the IP addresses.
36
37   LookUp( $ip | $hostname )
38       Given an IP address or a hostname, this function returns three things:
39
40       •   The ISO 3166 country code (2 chars)
41
42       •   The country name
43
44       •   The IP address resolved
45
46       NB: In order to use the location services on a hostname, you will need
47       to have an internet connection to resolve a host to an IP address.
48
49       If you pass a private IP address (for example 192.168.0.1), you'll get
50       back a country code of ZZ, and country name of "Reserved for private IP
51       addresses".
52
53   Clean_Cache( )
54       Clears any cached lookup data.
55
56   Faster( )
57       Make the LookUp() faster, which is good if you're going to be calling
58       Lookup() many times. This will load the entire DB into memory and read
59       from there, not from disk (good way for slow disk or network disks),
60       but use more memory. The module "Memoize" will be enabled for some
61       internal functions too.
62
63       Note that if you call Lookup() many times, you'll end up using a lot of
64       memory anyway, so you'll be better off using a lot of memory from the
65       start by calling Faster(), and getting an improvement for all calls.
66
67   nslookup( $host, [$last_lookup] )
68       Attempts to resolve a hostname to an IP address. If it fails on the
69       first pass it will attempt to resolve the same hostname with 'www.'
70       prepended. $last_lookup is used to suppress this behavior.
71
72   ip2nb( $ip )
73       Encodes $ip into a numerical representation.
74
75   nb2ip( $number )
76       Decodes $number back to an IP address.
77
78   dec2baseX( $number )
79       Converts a base 10 (decimal) number to base 86.
80
81   baseX2dec( $number )
82       Converts a base 86 number to base 10 (decimal).
83

VARS

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

DB FORMAT

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

NOTES

121       The file ipscountry.dat is a dedicated format for Geo::IPfree.  To
122       convert it see the tool "ipct2txt.pl" in the "misc" directoy.
123
124       The module looks for "ipscountry.dat" in the following locations:
125
126       •   /usr/local/share
127
128       •   /usr/local/share/GeoIPfree
129
130       •   through @INC (as well as all @INC directories plus "/Geo")
131
132       •   from the same location that IPfree.pm was loaded
133

SEE ALSO

135       •   http://software77.net/geo-ip/
136

AUTHOR

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

MAINTAINER

141       Brian Cassidy <bricas@cpan.org>
142

THANK YOU

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

149       This program is free software; you can redistribute it and/or modify it
150       under the same terms as Perl itself.
151
152
153
154perl v5.34.0                      2021-07-22                    Geo::IPfree(3)
Impressum