.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Geo::IPfree 3"
.TH Geo::IPfree 3 "2015-07-14" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Geo::IPfree \- Look up the country of an IPv4 address
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Geo::IPfree;
\&    
\&    my $geo = Geo::IPfree\->new;
\&    my( $code1, $name1 ) = $geo\->LookUp( \*(Aq200.176.3.142\*(Aq );
\&    
\&    # use memory to speed things up
\&    $geo\->Faster;
\&    
\&    # lookup by hostname
\&    my( $code2, $name2, $ip2 ) = $geo\->LookUp( \*(Aqwww.cnn.com\*(Aq );
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
An updated version of the database can be obtained by visiting the Webnet77 
website: <http://software77.net/geo\-ip/>.
.SH "METHODS"
.IX Header "METHODS"
.SS "new( [$db] )"
.IX Subsection "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.
.ie n .SS "LoadDB( $filename )"
.el .SS "LoadDB( \f(CW$filename\fP )"
.IX Subsection "LoadDB( $filename )"
Load a specific database to use to look up the \s-1IP\s0 addresses.
.ie n .SS "LookUp( $ip | $hostname )"
.el .SS "LookUp( \f(CW$ip\fP | \f(CW$hostname\fP )"
.IX Subsection "LookUp( $ip | $hostname )"
Given an \s-1IP\s0 address or a hostname, this function returns three things:
.IP "\(bu" 4
The \s-1ISO 3166\s0 country code (2 chars)
.IP "\(bu" 4
The country name
.IP "\(bu" 4
The \s-1IP\s0 address resolved
.PP
\&\fB\s-1NB:\s0\fR In order to use the location services on a hostname, you will need
to have an internet connection to resolve a host to an \s-1IP\s0 address.
.PP
If you pass a private \s-1IP\s0 address (for example 192.168.0.1), you'll get back a country
code of \s-1ZZ,\s0 and country name of \*(L"Reserved for private \s-1IP\s0 addresses\*(R".
.SS "Clean_Cache( )"
.IX Subsection "Clean_Cache( )"
Clears any cached lookup data.
.SS "Faster( )"
.IX Subsection "Faster( )"
Make the \fILookUp()\fR faster, which is good if you're going to be calling \fILookup()\fR many times. This will load the entire \s-1DB\s0 into memory and read from there,
not from disk (good way for slow disk or network disks), but use more memory. The module \*(L"Memoize\*(R" will be enabled for some internal functions too.
.PP
Note that if you call \fILookup()\fR 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 \fIFaster()\fR,
and getting an improvement for all calls.
.ie n .SS "nslookup( $host, [$last_lookup] )"
.el .SS "nslookup( \f(CW$host\fP, [$last_lookup] )"
.IX Subsection "nslookup( $host, [$last_lookup] )"
Attempts to resolve a hostname to an \s-1IP\s0 address. If it fails on the first pass
it will attempt to resolve the same hostname with 'www.' prepended. \f(CW$last_lookup\fR
is used to suppress this behavior.
.ie n .SS "ip2nb( $ip )"
.el .SS "ip2nb( \f(CW$ip\fP )"
.IX Subsection "ip2nb( $ip )"
Encodes \f(CW$ip\fR into a numerical representation.
.ie n .SS "nb2ip( $number )"
.el .SS "nb2ip( \f(CW$number\fP )"
.IX Subsection "nb2ip( $number )"
Decodes \f(CW$number\fR back to an \s-1IP\s0 address.
.ie n .SS "dec2baseX( $number )"
.el .SS "dec2baseX( \f(CW$number\fP )"
.IX Subsection "dec2baseX( $number )"
Converts a base 10 (decimal) number to base 86.
.ie n .SS "baseX2dec( $number )"
.el .SS "baseX2dec( \f(CW$number\fP )"
.IX Subsection "baseX2dec( $number )"
Converts a base 86 number to base 10 (decimal).
.SH "VARS"
.IX Header "VARS"
.ie n .IP "$GeoIP\->{db}" 4
.el .IP "\f(CW$GeoIP\fR\->{db}" 4
.IX Item "$GeoIP->{db}"
The database file in use.
.ie n .IP "$GeoIP\->{handler}" 4
.el .IP "\f(CW$GeoIP\fR\->{handler}" 4
.IX Item "$GeoIP->{handler}"
The database file handler.
.ie n .IP "$GeoIP\->{dbfile}" 4
.el .IP "\f(CW$GeoIP\fR\->{dbfile}" 4
.IX Item "$GeoIP->{dbfile}"
The database file path.
.ie n .IP "$GeoIP\->{cache} \s-1BOOLEAN\s0" 4
.el .IP "\f(CW$GeoIP\fR\->{cache} \s-1BOOLEAN\s0" 4
.IX Item "$GeoIP->{cache} BOOLEAN"
Set/tell if the cache of \fILookUp()\fR is on. If it's on it will cache the last 5000 queries. Default: 1
.Sp
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 \s-1IP,\s0 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 \s-1IP\s0 is removed from the cache and the new
data is stored.
.Sp
Note that the Lookup make the query without the last \s-1IP\s0 number (xxx.xxx.xxx.0),
then the cache for the \s-1IP 192.168.0.1\s0 will be the same for 192.168.0.2 (they are the same query, 192.168.0.0).
.SH "DB FORMAT"
.IX Header "DB FORMAT"
The data file has a list of \s-1IP\s0 ranges & countries, for example, from 200.128.0.0 to
200.103.255.255 the IPs are from \s-1BR.\s0 To make a fast access to the \s-1DB\s0 the format
tries to use less bytes per input (block). The file was in \s-1ASCII\s0 and in blocks
of 7 bytes: XXnnnnn
.PP
.Vb 3
\&  XX    \-> the country code (BR,US...)
\&  nnnnn \-> the IP range using a base of 85 digits
\&           (not in dec or hex to get space).
.Ve
.PP
See \s-1CPAN\s0 for updates of the \s-1DB...\s0
.SH "NOTES"
.IX Header "NOTES"
The file ipscountry.dat is a dedicated format for Geo::IPfree.
To convert it see the tool \*(L"ipct2txt.pl\*(R" in the \f(CW\*(C`misc\*(C'\fR directoy.
.PP
The module looks for \f(CW\*(C`ipscountry.dat\*(C'\fR in the following locations:
.IP "\(bu" 4
/usr/local/share
.IP "\(bu" 4
/usr/local/share/GeoIPfree
.IP "\(bu" 4
through \f(CW@INC\fR (as well as all \f(CW@INC\fR directories plus \*(L"/Geo\*(R")
.IP "\(bu" 4
from the same location that IPfree.pm was loaded
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
http://software77.net/geo\-ip/
.SH "AUTHOR"
.IX Header "AUTHOR"
Graciliano M. P. <gm@virtuasites.com.br>
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Brian Cassidy <bricas@cpan.org>
.SH "THANK YOU"
.IX Header "THANK YOU"
Thanks to Laurent Destailleur (author of AWStats) that tested it on many \s-1OS\s0 and
fixed bugs for them, like the not portable sysread, and asked for some speed improvement.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.