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->last_ip()."\n");
  print ("Len : ".$ip->prefixlen()."\n");
  print ("Size: ".$ip->size()."\n");
  print ("Type: ".$ip->iptype()."\n");
  print ("Rev:  ".$ip->reverse_ip()."\n");

DESCRIPTION

This module provides functions to deal with IPv4/IPv6 addresses. The module can be used as a class, allowing the user to instantiate \s-1IP\s0 objects, which can be single \s-1IP\s0 addresses, prefixes, or ranges of addresses. There is also a procedural way of accessing most of the functions. Most subroutines can take either IPv4 or IPv6 addresses transparently.

OBJECT-ORIENTED INTERFACE

Object Creation

A Net::IP object can be created from a single \s-1IP\s0 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 \s-1IP\s0. Otherwise, it tries to guess what the version is (see _is_ipv4() and _is_ipv6()).

$ip = new Net::IP ('195/8',4); # Class A

OBJECT METHODS

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.

set

Set an \s-1IP\s0 address in an existing \s-1IP\s0 object. This method has the same functionality as the new() method, except that it reuses an existing object to store the new \s-1IP\s0.

\*(C`$ip->set('130.23.1/24',4);\*(C'

Like new(), set() takes two arguments - a string used to build an \s-1IP\s0 address, prefix, or range, and optionally, the \s-1IP\s0 version of the considered address.

It returns an \s-1IP\s0 object on success, and undef on failure.

error

Return the current object error string. The error string is set whenever one of the methods produces an error. Also, a global, class-wide Error() function is available.

\*(C`warn ($ip->error());\*(C'

errno

Return the current object error number. The error number is set whenever one of the methods produces an error. Also, a global $ERRNO variable is set when an error is produced.

\*(C`warn ($ip->errno());\*(C'

ip

Return the \s-1IP\s0 address (or first \s-1IP\s0 of the prefix or range) in quad format, as a string.

\*(C`print ($ip->ip());\*(C'

binip

Return the \s-1IP\s0 address as a binary string of 0s and 1s.

\*(C`print ($ip->binip());\*(C'

prefixlen

Return the length in bits of the current prefix.

\*(C`print ($ip->prefixlen());\*(C'

version

Return the version of the current \s-1IP\s0 object (4 or 6).

\*(C`print ($ip->version());\*(C'

size

Return the number of \s-1IP\s0 addresses in the current prefix or range. Use of this function requires Math::BigInt.

\*(C`print ($ip->size());\*(C'

binmask

Return the binary mask of the current prefix, if applicable.

\*(C`print ($ip->binmask());\*(C'

mask

Return the mask in quad format of the current prefix.

\*(C`print ($ip->mask());\*(C'

prefix

Return the full prefix (ip+prefix length) in quad (standard) format.

\*(C`print ($ip->prefix());\*(C'

print

Print the \s-1IP\s0 object (IP/Prefix or First - Last)

\*(C`print ($ip->print());\*(C'

intip

Convert the \s-1IP\s0 in integer format and return it as a Math::BigInt object.

\*(C`print ($ip->intip());\*(C'

hexip

Return the \s-1IP\s0 in hex format

\*(C`print ($ip->hexip());\*(C'

hexmask

Return the mask in hex format

\*(C`print ($ip->hexmask());\*(C'

short

Return the \s-1IP\s0 in short format: IPv4 addresses: 194.5/16 IPv6 addresses: ab32:f000::

\*(C`print ($ip->short());\*(C'

iptype

Return the \s-1IP\s0 Type - this describes the type of an \s-1IP\s0 (Public, Private, Reserved, etc.) See procedural interface ip_iptype for more details.

\*(C`print ($ip->iptype());\*(C'

reverse_ip

Return the reverse \s-1IP\s0 for a given \s-1IP\s0 address (in.addr. format).

\*(C`print ($ip->reserve_ip());\*(C'

last_ip

Return the last \s-1IP\s0 of a prefix/range in quad format.

\*(C`print ($ip->last_ip());\*(C'

last_bin

Return the last \s-1IP\s0 of a prefix/range in binary format.

\*(C`print ($ip->last_bin());\*(C'

last_int

Return the last \s-1IP\s0 of a prefix/range in integer format.

\*(C`print ($ip->last_int());\*(C'

find_prefixes

This function finds all the prefixes that can be found between the two addresses of a range. The function returns a list of prefixes.

\*(C`@list = $ip->find_prefixes($other_ip));\*(C'

bincomp

Binary comparaison of two \s-1IP\s0 objects. The function takes an operation and an \s-1IP\s0 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

\*(C`if ($ip->bincomp('lt',$ip2) {...}\*(C'

binadd

Binary addition of two \s-1IP\s0 objects. The value returned is an \s-1IP\s0 object.

\*(C`my $sum = $ip->binadd($ip2);\*(C'

aggregate

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 \s-1IP\s0 object is returned.

\*(C`my $total = $ip->aggregate($ip2);\*(C'

overlaps

Check if two \s-1IP\s0 ranges/prefixes overlap each other. The value returned by the function should be one of: $IP_PARTIAL_OVERLAP (ranges overlap) $IP_NO_OVERLAP (no overlap) $IP_A_IN_B_OVERLAP (range2 contains range1) $IP_B_IN_A_OVERLAP (range1 contains range2) $IP_IDENTICAL (ranges are identical) undef (problem)

\*(C`if ($ip->overlaps($ip2)==$IP_A_IN_B_OVERLAP) {...};\*(C'

looping

The \*(C`+\*(C' operator is overloaded in order to allow looping though a whole range of \s-1IP\s0 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.

auth

Return \s-1IP\s0 authority information from the IP::Authority module

\*(C`$auth = ip-\*(C'auth ();>

Note: IPv4 only

PROCEDURAL INTERFACE

These functions do the real work in the module. Like the \s-1OO\s0 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 \*(C`Error()\*(C' and \*(C`Errno()\*(C'.

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:

\*(C`use Net::IP qw(:PROC);\*(C'

Error

Returns the error string corresponding to the last error generated in the module. This is also useful for the \s-1OO\s0 interface, as if the new() function fails, we cannot call $ip->error() and so we have to use Error().

warn Error();

Errno

Returns a numeric error code corresponding to the error string returned by Error.

ip_iptobin

Transform an \s-1IP\s0 address into a bit string.

Params : IP address, IP version Returns : binary IP string on success, undef otherwise

\*(C`$binip = ip_iptobin ($ip,6);\*(C'

ip_bintoip

Transform a bit string into an \s-1IP\s0 address

Params : binary IP, IP version Returns : IP address on success, undef otherwise

\*(C`$ip = ip_bintoip ($binip,6);\*(C'

ip_bintoint

Transform a bit string into a BigInt.

Params : binary IP Returns : BigInt

\*(C`$bigint = new Math::BigInt (ip_bintoint($binip));\*(C'

ip_inttobin

Transform a BigInt into a bit string. Warning: sets warnings (\*(C`-w\*(C') off. This is necessary because Math::BigInt is not compliant.

Params : BigInt, IP version Returns : binary IP

\*(C`$binip = ip_inttobin ($bigint);\*(C'

ip_get_version

Try to guess the \s-1IP\s0 version of an \s-1IP\s0 address.

Params : IP address Returns : 4, 6, undef(unable to determine)

\*(C`$version = ip_get_version ($ip)\*(C'

ip_is_ipv4

Check if an \s-1IP\s0 address is of type 4.

Params : IP address Returns : 1 (yes) or 0 (no)

\*(C`ip_is_ipv4($ip) and print "$ip is IPv4";\*(C'

ip_is_ipv6

Check if an \s-1IP\s0 address is of type 6.

Params : IP address Returns : 1 (yes) or 0 (no)

\*(C`ip_is_ipv6($ip) and print "$ip is IPv6";\*(C'

ip_expand_address

Expand an \s-1IP\s0 address from compact notation.

Params : IP address, IP version Returns : expanded IP address or undef on failure

\*(C`$ip = ip_expand_address ($ip,4);\*(C'

ip_get_mask

Get \s-1IP\s0 mask from prefix length.

Params : Prefix length, IP version Returns : Binary Mask

\*(C`$mask = ip_get_mask ($len,6);\*(C'

ip_last_address_bin

Return the last binary address of a prefix.

Params : First binary IP, prefix length, IP version Returns : Binary IP

\*(C`$lastbin = ip_last_address_bin ($ip,$len,6);\*(C'

ip_splitprefix

Split a prefix into \s-1IP\s0 and prefix length. If it was passed a simple \s-1IP\s0, it just returns it.

Params : Prefix Returns : IP, optionally length of prefix

\*(C`($ip,$len) = ip_splitprefix ($prefix)\*(C'

ip_prefix_to_range

Get a range of IPs from a prefix.

Params : Prefix, IP version Returns : First IP, last IP

\*(C`($ip1,$ip2) = ip_prefix_to_range ($prefix,6);\*(C'

ip_bincomp

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)

\*(C`ip_bincomp ($ip1,'lt',$ip2) == 1 or do {}\*(C'

ip_binadd

Add two binary IPs.

Params : First binary IP, Last binary IP Returns : Binary sum or undef (problem)

\*(C`$binip = ip_binadd ($bin1,$bin2);\*(C'

ip_get_prefix_length

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)

\*(C`$len = ip_get_prefix_length ($ip1,$ip2);\*(C'

ip_range_to_prefix

Return all prefixes between two IPs.

Params : First IP (binary format), Last IP (binary format), IP version Returns : List of Prefixes or undef (problem)

The prefixes returned have the form q.q.q.q/nn.

\*(C`@prefix = ip_range_to_prefix ($ip1,$ip2,6);\*(C'

ip_compress_v4_prefix

Compress an IPv4 Prefix.

Params : IP, Prefix length Returns : Compressed Prefix

\*(C`$ip = ip_compress_v4_prefix ($ip, $len);\*(C'

ip_compress_address

Compress an IPv6 address. Just returns the \s-1IP\s0 if it is an IPv4.

Params : IP, IP version Returns : Compressed IP or undef (problem)

\*(C`$ip = ip_compress_adress ($ip, $version);\*(C'

ip_is_overlap

Check if two ranges of IPs overlap.

Params : Four binary IPs (begin of range 1,end1,begin2,end2), IP version $IP_PARTIAL_OVERLAP (ranges overlap) $IP_NO_OVERLAP (no overlap) $IP_A_IN_B_OVERLAP (range2 contains range1) $IP_B_IN_A_OVERLAP (range1 contains range2) $IP_IDENTICAL (ranges are identical) undef (problem)

\*(C`(ip_is_overlap($rb1,$re1,$rb2,$re2,4) eq $IP_A_IN_B_OVERLAP) and do {};\*(C'

ip_get_embedded_ipv4

Get an IPv4 embedded in an IPv6 address

Params : IPv6 Returns : IPv4 string or undef (not found)

\*(C`$ip4 = ip_get_embedded($ip6);\*(C'

ip_check_mask

Check the validity of a binary \s-1IP\s0 mask

Params : Mask Returns : 1 or undef (invalid)

\*(C`ip_check_mask($binmask) or do {};\*(C'

Checks if mask has only 1s followed by 0s.

ip_aggregate

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)

\*(C`$prefix = ip_aggregate ($bip1,$eip1,$bip2,$eip2) || die ...\*(C'

ip_iptypev4

Return the type of an IPv4 address.

Params: binary IP Returns: type as of the following table or undef (invalid ip)

See \s-1RFC\s0 5735 and \s-1RFC\s0 6598

Address Block       Present Use                Reference ------------------------------------------------------------------- 0.0.0.0/8           \*(L"This\*(R" Network             \s-1RFC\s0 1122 \s-1PRIVATE\s0 10.0.0.0/8          Private-Use Networks       \s-1RFC\s0 1918 \s-1PRIVATE\s0 100.64.0.0/10       \s-1CGN\s0 Shared Address Space   \s-1RFC\s0 6598 \s-1SHARED\s0 127.0.0.0/8         Loopback                   \s-1RFC\s0 1122 \s-1LOOPBACK\s0 169.254.0.0/16      Link Local                 \s-1RFC\s0 3927 LINK-LOCAL 172.16.0.0/12       Private-Use Networks       \s-1RFC\s0 1918 \s-1PRIVATE\s0 192.0.0.0/24        \s-1IETF\s0 Protocol Assignments  \s-1RFC\s0 5736 \s-1RESERVED\s0 192.0.2.0/24        \s-1TEST-NET-1\s0                 \s-1RFC\s0 5737 TEST-NET 192.88.99.0/24      6to4 Relay Anycast         \s-1RFC\s0 3068 6TO4-RELAY 192.168.0.0/16      Private-Use Networks       \s-1RFC\s0 1918 \s-1PRIVATE\s0 198.18.0.0/15       Network Interconnect                     Device Benchmark Testing   \s-1RFC\s0 2544 \s-1RESERVED\s0 198.51.100.0/24     \s-1TEST-NET-2\s0                 \s-1RFC\s0 5737 TEST-NET 203.0.113.0/24      \s-1TEST-NET-3\s0                 \s-1RFC\s0 5737 TEST-NET 224.0.0.0/4         Multicast                  \s-1RFC\s0 3171 \s-1MULTICAST\s0 240.0.0.0/4         Reserved for Future Use    \s-1RFC\s0 1112 \s-1RESERVED\s0 255.255.255.255/32  Limited Broadcast          \s-1RFC\s0 919  \s-1BROADCAST\s0                                                \s-1RFC\s0 922

ip_iptypev6

Return the type of an IPv6 address.

Params: binary ip Returns: type as of the following table or undef (invalid)

See \s-1IANA\s0 Internet Protocol Version 6 Address Space <http://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt> and \s-1IANA\s0 IPv6 Special Purpose Address Registry <http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.txt>

Prefix      Allocation           Reference ------------------------------------------------------------- 0000::/8    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 0100::/8    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 0200::/7    Reserved by \s-1IETF\s0     [\s-1RFC4048\s0] \s-1RESERVED\s0 0400::/6    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 0800::/5    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 1000::/4    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 2000::/3    Global Unicast       [\s-1RFC4291\s0] GLOBAL-UNICAST 4000::/3    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 6000::/3    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 8000::/3    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 A000::/3    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 C000::/3    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 E000::/4    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 F000::/5    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 F800::/6    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 \s-1FC00::/7\s0    Unique Local Unicast [\s-1RFC4193\s0] UNIQUE-LOCAL-UNICAST \s-1FE00::/9\s0    Reserved by \s-1IETF\s0     [\s-1RFC4291\s0] \s-1RESERVED\s0 \s-1FE80::/10\s0   Link Local Unicast   [\s-1RFC4291\s0] LINK-LOCAL-UNICAST \s-1FEC0::/10\s0   Reserved by \s-1IETF\s0     [\s-1RFC3879\s0] \s-1RESERVED\s0 \s-1FF00::/8\s0    Multicast            [\s-1RFC4291\s0] \s-1MULTICAST\s0

Prefix          Assignment            Reference --------------------------------------------------------------------- ::1/128         Loopback Address      [\s-1RFC4291\s0] \s-1UNSPECIFIED\s0 ::/128          Unspecified Address   [\s-1RFC4291\s0] \s-1LOOPBACK\s0 ::FFFF:0:0/96   IPv4-mapped Address   [\s-1RFC4291\s0] \s-1IPV4MAP\s0 0100::/64       Discard-Only Prefix   [\s-1RFC6666\s0] \s-1DISCARD\s0 2001:0000::/32  \s-1TEREDO\s0                [\s-1RFC4380\s0] \s-1TEREDO\s0 2001:0002::/48  \s-1BMWG\s0                  [\s-1RFC5180\s0] \s-1BMWG\s0 2001:db8::/32   Documentation Prefix  [\s-1RFC3849\s0] \s-1DOCUMENTATION\s0 2001:10::/28    \s-1ORCHID\s0                [\s-1RFC4843\s0] \s-1ORCHID\s0 2002::/16       6to4                  [\s-1RFC3056\s0] 6TO4 \s-1FC00::/7\s0        Unique-Local          [\s-1RFC4193\s0] UNIQUE-LOCAL-UNICAST \s-1FE80::/10\s0       Linked-Scoped Unicast [\s-1RFC4291\s0] LINK-LOCAL-UNICAST \s-1FF00::/8\s0        Multicast             [\s-1RFC4291\s0] \s-1MULTICAST\s0

ip_iptype

Return the type of an \s-1IP\s0 (Public, Private, Reserved)

Params : Binary IP to test, IP version (defaults to 6) Returns : type (see ip_iptypev4 and ip_iptypev6 for details) or undef (invalid)

\*(C`$type = ip_iptype ($ip);\*(C'

ip_check_prefix

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.

\*(C`ip_check_prefix ($ip,$len,$ipv) or do {};\*(C'

ip_reverse

Get a reverse name from a prefix

Params : IP, length of prefix, IP version Returns : Reverse name or undef (error)

\*(C`$reverse = ip_reverse ($ip);\*(C'

ip_normalize

Normalize data to a range/prefix of \s-1IP\s0 addresses

Params : Data String (Single IP, Range, Prefix) Returns : ip1, ip2 (if range/prefix) or undef (error)

\*(C`($ip1,$ip2) = ip_normalize ($data);\*(C'

ip_auth

Return \s-1IP\s0 authority information from the IP::Authority module

Params : IP, version Returns : Auth info (RI for RIPE, AR for ARIN, etc)

\*(C`$auth = ip_auth ($ip,4);\*(C'

Note: IPv4 only

BUGS

The Math::BigInt library is needed for functions that use integers. These are ip_inttobin, ip_bintoint, and the size method. In a next version, Math::BigInt will become optional.

AUTHORS

Manuel Valente <[email protected]>.

Original IPv4 code by Monica Cortes Sack <[email protected]>.

Original IPv6 code by Lee Wilmot <[email protected]>.

BASED ON

ipv4pack.pm, iplib.pm, iplibncc.pm.

RELATED TO Net::IP…

perl\|(1), IP::Authority