IP(3) User Contributed Perl Documentation IP(3)
NAME
Net::IP - Perl extension for manipulating IPv4/IPv6 addresses
SYNOPSIS
use Net::IP;
my $ip = new Net::IP ('193.0.1/24') or die (Net::IP::Error());
print ("IP : ".$ip->ip()."\n");
print ("Sho : ".$ip->short()."\n");
print ("Bin : ".$ip->binip()."\n");
print ("Int : ".$ip->intip()."\n");
print ("Mask: ".$ip->mask()."\n");
print ("Last: ".$ip->lastip()."\n");
print ("Len : ".$ip->prefixlen()."\n");
print ("Size: ".$ip->size()."\n");
print ("Type: ".$ip->iptype()."\n");
print ("Rev: ".$ip->reverseip()."\n");
DESCRIPTION
This module provides functions to deal with IIPPvv44//IIPPvv66 addresses. The
module can be used as a class, allowing the user to instantiate IP
objects, which can be single IP addresses, prefixes, or ranges of
addresses. There is also a procedural way of accessing most of the
functions. Most subroutines can take either IIPPvv44 or IIPPvv66 addresses
transparently.
OOBBJJEECCTT-OORRIIEENNTTEEDD IINNTTEERRFFAACCEE
OObbjjeecctt CCrreeaattiioonn
A Net::IP object can be created from a single IP address:
$ip = new Net::IP ('193.0.1.46') || die ...
Or from a Classless Prefix (a /24 prefix is equivalent to a C class):
$ip = new Net::IP ('195.114.80/24') || die ...
Or from a range of addresses:
$ip = new Net::IP ('20.34.101.207 - 201.3.9.99') || die ...
Or from a address plus a number:
$ip = new Net::IP ('20.34.10.0 + 255') || die ...
The new() function accepts IPv4 and IPv6 addresses:
$ip = new Net::IP ('dead:beef::/32') || die ...
Optionnaly, the function can be passed the version of the IP.
Otherwise, it tries to guess what the version is (see iissiippvv44(()) and
iissiippvv66(())).
$ip = new Net::IP ('195/8',4); # Class A
OOBBJJEECCTT MMEETTHHOODDSS
Most of these methods are front-ends for the real functions, which use
a procedural interface. Most functions return undef on failure, and a
true value on success. A detailed description of the procedural
interface is provided below.
sseett
Set an IP address in an existing IP object. This method has the same
functionality as the new() method, except that it reuses an existing
object to store the new IP.
"$ip->set('130.23.1/24',4);"
Like new(), set() takes two arguments - a string used to build an IP
address, prefix, or range, and optionally, the IP version of the
considered address.
It returns an IP object on success, and undef on failure.
eerrrroorr
Return the current object error string. The error string is set
whenever one of the methods produces an error. Also, a global, class-
wide EErrrroorr(()) function is avaliable.
"warn ($ip->error());"
eerrrrnnoo
Return the current object error number. The error number is set
whenever one of the methods produces an error. Also, a global $$EERRRRNNOO
variable is set when an error is produced.
"warn ($ip->errno());"
iipp
Return the IP address (or first IP of the prefix or range) in quad
format, as a string.
"print ($ip->ip());"
bbiinniipp
Return the IP address as a binary string of 0s and 1s.
"print ($ip->binip());"
pprreeffiixxlleenn
Return the length in bits of the current prefix.
"print ($ip->prefixlen());"
vveerrssiioonn
Return the version of the current IP object (4 or 6).
"print ($ip->version());"
ssiizzee
Return the number of IP addresses in the current prefix or range. Use
of this function requires Math::BigInt.
"print ($ip->size());"
bbiinnmmaasskk
Return the binary mask of the current prefix, if applicable.
"print ($ip->binmask());"
mmaasskk
Return the mask in quad format of the current prefix.
"print ($ip->mask());"
pprreeffiixx
Return the full prefix (ip+prefix length) in quad (standard) format.
"print ($ip->prefix());"
pprriinntt
Print the IP object (IP/Prefix or First - Last)
"print ($ip->print());"
iinnttiipp
Convert the IP in integer format and return it as a Math::BigInt
object.
"print ($ip->intip());"
hheexxiipp
Return the IP in hex format
"print ($ip->hexip());"
hheexxmmaasskk
Return the mask in hex format
"print ($ip->hexmask());"
sshhoorrtt
Return the IP in short format: IPv4 addresses: 194.5/16 IPv6
addresses: ab32:f000::
"print ($ip->short());"
iippttyyppee
Return the IP Type - this describes the type of an IP (Public, Private,
Reserved, etc.)
"print ($ip->iptype());"
rreevveerrsseeiipp
Return the reverse IP for a given IP address (in.addr. format).
"print ($ip->reserveip());"
llaassttiipp
Return the last IP of a prefix/range in quad format.
"print ($ip->lastip());"
llaassttbbiinn
Return the last IP of a prefix/range in binary format.
"print ($ip->lastbin());"
llaassttiinntt
Return the last IP of a prefix/range in integer format.
"print ($ip->lastint());"
ffiinnddpprreeffiixxeess
This function finds all the prefixes that can be found between the two
addresses of a range. The function returns a list of prefixes.
"@list = $ip->findprefixes($otherip));"
bbiinnccoommpp
Binary comparaison of two IP objects. The function takes an operation
and an IP object as arguments. It returns a boolean value.
The operation can be one of: lt: less than (smaller than) le: smaller
or equal to gt: greater than ge: greater or equal to
"if ($ip->bincomp('lt',$ip2) {...}"
bbiinnaadddd
Binary addition of two IP objects. The value returned is an IP object.
"my $sum = $ip->binadd($ip2);"
aaggggrreeggaattee
Aggregate 2 IPs - Append one range/prefix of IPs to another. The last
address of the first range must be the one immediately preceding the
first address of the second range. A new IP object is returned.
"my $total = $ip->aggregate($ip2);"
oovveerrllaappss
Check if two IP ranges/prefixes overlap each other. The value returned
by the function should be one of: $IPPARTIALOVERLAP (ranges
overlap) $IPNOOVERLAP (no overlap) $IPAINBOVERLAP
(range2 contains range1) $IPBINAOVERLAP (range1 contains
range2) $IPIDENTICAL (ranges are identical) undef
(problem)
"if ($ip->overlaps($ip2)==$IPAINBOVERLAP) {...};"
llooooppiinngg
The "+" operator is overloaded in order to allow looping though a whole
range of IP addresses:
my $ip = new Net::IP ('195.45.6.7 - 195.45.6.19') || die;
# Loop
do {
print $ip->ip(), "\n";
} while (++$ip);
The ++ operator returns undef when the last address of the range is
reached.
aauutthh
Return IP authority information from the IP::Authority module
"$auth = ip-"auth ();>
Note: IPv4 only
PPRROOCCEEDDUURRAALL IINNTTEERRFFAACCEE
These functions do the real work in the module. Like the OO methods,
most of these return undef on failure. In order to access error codes
and strings, instead of using $ip->error() and $ip->errno(), use the
global functions "Error()" and "Errno()".
The functions of the procedural interface are not exported by default.
In order to import these functions, you need to modify the use
statement for the module:
"use Net::IP qw(:PROC);"
EErrrroorr
Returns the error string corresponding to the last error generated in
the module. This is also useful for the OO interface, as if the new()
function fails, we cannot call $ip->error() and so we have to use
Error().
warn Error();
EErrrrnnoo
Returns a numeric error code corresponding to the error string returned
by Error.
iippiippttoobbiinn
Transform an IP address into a bit string.
Params : IP address, IP version
Returns : binary IP string on success, undef otherwise
"$binip = ipiptobin ($ip,6);"
iippbbiinnttooiipp
Transform a bit string into an IP address
Params : binary IP, IP version
Returns : IP address on success, undef otherwise
"$ip = ipbintoip ($binip,6);"
iippbbiinnttooiinntt
Transform a bit string into a BigInt.
Params : binary IP
Returns : BigInt
"$bigint = new Math::BigInt (ipbintoint($binip));"
iippiinnttttoobbiinn
Transform a BigInt into a bit string. Warning: sets warnings ("-w")
off. This is necessary because Math::BigInt is not compliant.
Params : BigInt, IP version
Returns : binary IP
"$binip = ipinttobin ($bigint);"
iippggeettvveerrssiioonn
Try to guess the IP version of an IP address.
Params : IP address
Returns : 4, 6, undef(unable to determine)
"$version = ipgetversion ($ip)"
iippiissiippvv44
Check if an IP address is of type 4.
Params : IP address
Returns : 1 (yes) or 0 (no)
"ipisipv4($ip) and print "$ip is IPv4";"
iippiissiippvv66
Check if an IP address is of type 6.
Params : IP address
Returns : 1 (yes) or 0 (no)
"ipisipv6($ip) and print "$ip is IPv6";"
iippeexxppaannddaaddddrreessss
Expand an IP address from compact notation.
Params : IP address, IP version
Returns : expanded IP address or undef on failure
"$ip = ipexpandaddress ($ip,4);"
iippggeettmmaasskk
Get IP mask from prefix length.
Params : Prefix length, IP version
Returns : Binary Mask
"$mask = ipgetmask ($len,6);"
iippllaassttaaddddrreessssbbiinn
Return the last binary address of a prefix.
Params : First binary IP, prefix length, IP version
Returns : Binary IP
"$lastbin = iplastaddressbin ($ip,$len,6);"
iippsspplliittpprreeffiixx
Split a prefix into IP and prefix length. If it was passed a simple
IP, it just returns it.
Params : Prefix
Returns : IP, optionnaly length of prefix
"($ip,$len) = ipsplitprefix ($prefix)"
iipppprreeffiixxttoorraannggee
Get a range of IPs from a prefix.
Params : Prefix, IP version
Returns : First IP, last IP
"($ip1,$ip2) = ipprefixtorange ($prefix,6);"
iippbbiinnccoommpp
Compare binary Ips with <, >, <=, >=.
Operators are lt(<), le(<=), gt(>), and ge(>=)
Params : First binary IP, operator, Last binary IP
Returns : 1 (yes), 0 (no), or undef (problem)
"ipbincomp ($ip1,'lt',$ip2) == 1 or do {}"
iippbbiinnaadddd
Add two binary IPs.
Params : First binary IP, Last binary IP
Returns : Binary sum or undef (problem)
"$binip = ipbinadd ($bin1,$bin2);"
iippggeettpprreeffiixxlleennggtthh
Get the prefix length for a given range of 2 IPs.
Params : First binary IP, Last binary IP
Returns : Length of prefix or undef (problem)
"$len = ipgetprefixlength ($ip1,$ip2);"
iipprraannggeettoopprreeffiixx
Return all prefixes between two IPs.
Params : First IP, Last IP, IP version
Returns : List of Prefixes or undef (problem)
The prefixes returned have the form q.q.q.q/nn.
"@prefix = iprangetoprefix ($ip1,$ip2,6);"
iippccoommpprreessssvv44pprreeffiixx
Compress an IPv4 Prefix.
Params : IP, Prefix length
Returns : Compressed Prefix
"$ip = ipcompressv4prefix ($ip, $len);"
iippccoommpprreessssaaddddrreessss
Compress an IPv6 address. Just returns the IP if it is an IPv4.
Params : IP, IP version
Returns : Compressed IP or undef (problem)
"$ip = ipcompressadress ($ip, $version);"
iippiissoovveerrllaapp
Check if two ranges of IPs overlap.
Params : Four binary IPs (begin of range 1,end1,begin2,end2), IP version
$IPPARTIALOVERLAP (ranges overlap)
$IPNOOVERLAP (no overlap)
$IPAINBOVERLAP (range2 contains range1)
$IPBINAOVERLAP (range1 contains range2)
$IPIDENTICAL (ranges are identical)
undef (problem)
"(ipisoverlap($rb1,$re1,$rb2,$re2,4) eq $IPAINBOVERLAP) and do
{};"
iippggeetteemmbbeeddddeeddiippvv44
Get an IPv4 embedded in an IPv6 address
Params : IPv6
Returns : IPv4 string or undef (not found)
"$ip4 = ipgetembedded($ip6);"
iippcchheecckkmmaasskk
Check the validity of a binary IP mask
Params : Mask
Returns : 1 or undef (invalid)
"ipcheckmask($binmask) or do {};"
Checks if mask has only 1s followed by 0s.
iippaaggggrreeggaattee
Aggregate 2 ranges of binary IPs
Params : 1st range (1st IP, Last IP), last range (1st IP, last IP), IP version
Returns : prefix or undef (invalid)
"$prefix = ipaggregate ($bip1,$eip1,$bip2,$eip2) || die ..."
iippiippttyyppee
Return the type of an IP (Public, Private, Reserved)
Params : IP to test, IP version
Returns : type or undef (invalid)
"$type = ipiptype ($ip);"
iippcchheecckkpprreeffiixx
Check the validity of a prefix
Params : binary IP, length of prefix, IP version
Returns : 1 or undef (invalid)
Checks if the variant part of a prefix only has 0s, and the length is
correct.
"ipcheckprefix ($ip,$len,$ipv) or do {};"
iipprreevveerrssee
Get a reverse name from a prefix
Params : IP, length of prefix, IP version
Returns : Reverse name or undef (error)
"$reverse = ipreverse ($ip);"
iippnnoorrmmaalliizzee
Normalize data to a range/prefix of IP addresses
Params : Data String (Single IP, Range, Prefix)
Returns : ip1, ip2 (if range/prefix) or undef (error)
"($ip1,$ip2) = ipnormalize ($data);"
iippaauutthh
Return IP authority information from the IP::Authority module
Params : IP, version
Returns : Auth info (RI for RIPE, AR for ARIN, etc)
"$auth = ipauth ($ip,4);"
Note: IPv4 only
BUGS
The Math::BigInt library is needed for functions that use integers.
These are ipinttobin, ipbintoint, and the size method. In a next
version, Math::BigInt will become optionnal.
AUTHORS Manuel Valente .
Original IPv4 code by Monica Cortes Sack .
Original IPv6 code by Lee Wilmot .
BBAASSEEDD OONN
ipv4pack.pm, iplib.pm, iplibncc.pm.
SEE ALSO
perl(1), IP::Authority
perl v5.8.8 2006-05-22 IP(3)