Net::IP • man page

Net::IP (3)

Leading comments

Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Net::IP.3pm".)

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->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

objects, which can be single

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

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

. 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

address in an existing

object. This method has the same functionality as the new() method, except that it reuses an existing object to store the new

"$ip->set('130.23.1/24',4);"

Like new(), set() takes two arguments - a string used to build an

address, prefix, or range, and optionally, the

version of the considered address.

It returns an

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.

"warn ($ip->error());"

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.

"warn ($ip->errno());"

ip

Return the

address (or first

of the prefix or range) in quad format, as a string.

"print ($ip->ip());"

binip

Return the

address as a binary string of 0s and 1s.

"print ($ip->binip());"

prefixlen

Return the length in bits of the current prefix.

"print ($ip->prefixlen());"

version

Return the version of the current

object (4 or 6).

"print ($ip->version());"

size

Return the number of

addresses in the current prefix or range. Use of this function requires Math::BigInt.

"print ($ip->size());"

binmask

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

"print ($ip->binmask());"

mask

Return the mask in quad format of the current prefix.

"print ($ip->mask());"

prefix

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

"print ($ip->prefix());"

print

Print the

object (IP/Prefix or First - Last)

"print ($ip->print());"

intip

Convert the

in integer format and return it as a Math::BigInt object.

"print ($ip->intip());"

hexip

Return the

in hex format

"print ($ip->hexip());"

hexmask

Return the mask in hex format

"print ($ip->hexmask());"

short

Return the

in short format: IPv4 addresses: 194.5/16
IPv6 addresses: ab32:f000::

"print ($ip->short());"

iptype

Return the

Type - this describes the type of an

(Public, Private, Reserved, etc.) See procedural interface ip_iptype for more details.

"print ($ip->iptype());"

reverse_ip

Return the reverse

for a given

address (in.addr. format).

"print ($ip->reserve_ip());"

last_ip

Return the last

of a prefix/range in quad format.

"print ($ip->last_ip());"

last_bin

Return the last

of a prefix/range in binary format.

"print ($ip->last_bin());"

last_int

Return the last

of a prefix/range in integer format.

"print ($ip->last_int());"

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.

"@list = $ip->find_prefixes($other_ip));"

bincomp

Binary comparaison of two

objects. The function takes an operation and an

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) {...}"

binadd

Binary addition of two

objects. The value returned is an

object.

"my $sum = $ip->binadd($ip2);"

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

object is returned.

"my $total = $ip->aggregate($ip2);"

overlaps

Check if two

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)

"if ($ip->overlaps($ip2)==$IP_A_IN_B_OVERLAP) {...};"

looping

The "+" operator is overloaded in order to allow looping though a whole range of

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

authority information from the IP::Authority module

"$auth = ip-"auth ();>

Note: IPv4 only

PROCEDURAL INTERFACE

These functions do the real work in the module. Like the

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);"

Error

Returns the error string corresponding to the last error generated in the module. This is also useful for the

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

address into a bit string.

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

"$binip = ip_iptobin ($ip,6);"

ip_bintoip

Transform a bit string into an

address

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

"$ip = ip_bintoip ($binip,6);"

ip_bintoint

Transform a bit string into a BigInt.

    Params  : binary IP
    Returns : BigInt

"$bigint = new Math::BigInt (ip_bintoint($binip));"

ip_inttobin

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 = ip_inttobin ($bigint);"

ip_get_version

Try to guess the

version of an

address.

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

"$version = ip_get_version ($ip)"

ip_is_ipv4

Check if an

address is of type 4.

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

"ip_is_ipv4($ip) and print "$ip is IPv4";"

ip_is_ipv6

Check if an

address is of type 6.

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

"ip_is_ipv6($ip) and print "$ip is IPv6";"

ip_expand_address

Expand an

address from compact notation.

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

"$ip = ip_expand_address ($ip,4);"

ip_get_mask

Get

mask from prefix length.

    Params  : Prefix length, IP version
    Returns : Binary Mask

"$mask = ip_get_mask ($len,6);"

ip_last_address_bin

Return the last binary address of a prefix.

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

"$lastbin = ip_last_address_bin ($ip,$len,6);"

ip_splitprefix

Split a prefix into

and prefix length. If it was passed a simple

, it just returns it.

    Params  : Prefix
    Returns : IP, optionally length of prefix

"($ip,$len) = ip_splitprefix ($prefix)"

ip_prefix_to_range

Get a range of IPs from a prefix.

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

"($ip1,$ip2) = ip_prefix_to_range ($prefix,6);"

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)

"ip_bincomp ($ip1,'lt',$ip2) == 1 or do {}"

ip_binadd

Add two binary IPs.

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

"$binip = ip_binadd ($bin1,$bin2);"

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)

"$len = ip_get_prefix_length ($ip1,$ip2);"

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.

"@prefix = ip_range_to_prefix ($ip1,$ip2,6);"

ip_compress_v4_prefix

Compress an IPv4 Prefix.

    Params  : IP, Prefix length
    Returns : Compressed Prefix

"$ip = ip_compress_v4_prefix ($ip, $len);"

ip_compress_address

Compress an IPv6 address. Just returns the

if it is an IPv4.

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

"$ip = ip_compress_adress ($ip, $version);"

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)

"(ip_is_overlap($rb1,$re1,$rb2,$re2,4) eq $IP_A_IN_B_OVERLAP) and do {};"

ip_get_embedded_ipv4

Get an IPv4 embedded in an IPv6 address

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

"$ip4 = ip_get_embedded($ip6);"

ip_check_mask

Check the validity of a binary

mask

    Params  : Mask
    Returns : 1 or undef (invalid)

"ip_check_mask($binmask) or do {};"

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)

"$prefix = ip_aggregate ($bip1,$eip1,$bip2,$eip2) || die ..."

ip_iptypev4

Return the type of an IPv4 address.

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

See

RFC

5735 and

RFC

6598

Address Block Present Use Reference ------------------------------------------------------------------- 0.0.0.0/8 ``This'' Network

RFC

1122

PRIVATE

10.0.0.0/8 Private-Use Networks

RFC

1918

PRIVATE

100.64.0.0/10

CGN

Shared Address Space

RFC

6598

SHARED

127.0.0.0/8 Loopback

RFC

1122

LOOPBACK

169.254.0.0/16 Link Local

RFC

3927 LINK-LOCAL 172.16.0.0/12 Private-Use Networks

RFC

1918

PRIVATE

192.0.0.0/24

IETF

Protocol Assignments

RFC

5736

RESERVED

192.0.2.0/24

TEST-NET-1

RFC

5737 TEST-NET 192.88.99.0/24 6to4 Relay Anycast

RFC

3068 6TO4-RELAY 192.168.0.0/16 Private-Use Networks

RFC

1918

PRIVATE

198.18.0.0/15 Network Interconnect Device Benchmark Testing

RFC

2544

RESERVED

198.51.100.0/24

TEST-NET-2

RFC

5737 TEST-NET 203.0.113.0/24

TEST-NET-3

RFC

5737 TEST-NET 224.0.0.0/4 Multicast

RFC

3171

MULTICAST

240.0.0.0/4 Reserved for Future Use

RFC

1112

RESERVED

255.255.255.255/32 Limited Broadcast

RFC

919

BROADCAST

RFC

922

ip_iptypev6

Return the type of an IPv6 address.

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

See

IANA

Internet Protocol Version 6 Address Space <www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt> and

IANA

IPv6 Special Purpose Address Registry <www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.txt>

Prefix Allocation Reference ------------------------------------------------------------- 0000::/8 Reserved by

IETF

[

RFC4291

]

RESERVED

0100::/8 Reserved by

IETF

[

RFC4291

]

RESERVED

0200::/7 Reserved by

IETF

[

RFC4048

]

RESERVED

0400::/6 Reserved by

IETF

[

RFC4291

]

RESERVED

0800::/5 Reserved by

IETF

[

RFC4291

]

RESERVED

1000::/4 Reserved by

IETF

[

RFC4291

]

RESERVED

2000::/3 Global Unicast [

RFC4291

] GLOBAL-UNICAST 4000::/3 Reserved by

IETF

[

RFC4291

]

RESERVED

6000::/3 Reserved by

IETF

[

RFC4291

]

RESERVED

8000::/3 Reserved by

IETF

[

RFC4291

]

RESERVED

A000::/3 Reserved by

IETF

[

RFC4291

]

RESERVED

C000::/3 Reserved by

IETF

[

RFC4291

]

RESERVED

E000::/4 Reserved by

IETF

[

RFC4291

]

RESERVED

F000::/5 Reserved by

IETF

[

RFC4291

]

RESERVED

F800::/6 Reserved by

IETF

[

RFC4291

]

RESERVED

FC00::/7

Unique Local Unicast [

RFC4193

] UNIQUE-LOCAL-UNICAST

FE00::/9

Reserved by

IETF

[

RFC4291

]

RESERVED

FE80::/10

Link Local Unicast [

RFC4291

] LINK-LOCAL-UNICAST

FEC0::/10

Reserved by

IETF

[

RFC3879

]

RESERVED

FF00::/8

Multicast [

RFC4291

]

MULTICAST

Prefix Assignment Reference --------------------------------------------------------------------- ::1/128 Loopback Address [

RFC4291

]

UNSPECIFIED

::/128 Unspecified Address [

RFC4291

]

LOOPBACK

::FFFF:0:0/96 IPv4-mapped Address [

RFC4291

]

IPV4MAP

0100::/64 Discard-Only Prefix [

RFC6666

]

DISCARD

2001:0000::/32

TEREDO

[

RFC4380

]

TEREDO

2001:0002::/48

BMWG

[

RFC5180

]

BMWG

2001:db8::/32 Documentation Prefix [

RFC3849

]

DOCUMENTATION

2001:10::/28

ORCHID

[

RFC4843

]

ORCHID

2002::/16 6to4 [

RFC3056

] 6TO4

FC00::/7

Unique-Local [

RFC4193

] UNIQUE-LOCAL-UNICAST

FE80::/10

Linked-Scoped Unicast [

RFC4291

] LINK-LOCAL-UNICAST

FF00::/8

Multicast [

RFC4291

]

MULTICAST

ip_iptype

Return the type of an

(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)

"$type = ip_iptype ($ip);"

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.

"ip_check_prefix ($ip,$len,$ipv) or do {};"

ip_reverse

Get a reverse name from a prefix

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

"$reverse = ip_reverse ($ip);"

ip_normalize

Normalize data to a range/prefix of

addresses

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

"($ip1,$ip2) = ip_normalize ($data);"

ip_auth

Return

authority information from the IP::Authority module

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

"$auth = ip_auth ($ip,4);"

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 <manuel.valente@gmail.com>.

Original IPv4 code by Monica Cortes Sack <mcortes@ripe.net>.

Original IPv6 code by Lee Wilmot <lee@ripe.net>.

BASED ON

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

Net::IP • man page

Net::IP • man page

Net::IP (3)

Leading comments

NAME

SYNOPSIS

DESCRIPTION

OBJECT-ORIENTED INTERFACE

Object Creation

OBJECT METHODS

set

error

errno

ip

binip

prefixlen

version

size

binmask

mask

prefix

print

intip

hexip

hexmask

short

iptype

reverse_ip

last_ip

last_bin

last_int

find_prefixes

bincomp

binadd

aggregate

overlaps

looping

auth

PROCEDURAL INTERFACE

Error

Errno

ip_iptobin

ip_bintoip

ip_bintoint

ip_inttobin

ip_get_version

ip_is_ipv4

ip_is_ipv6

ip_expand_address

ip_get_mask

ip_last_address_bin

ip_splitprefix

ip_prefix_to_range

ip_bincomp

ip_binadd

ip_get_prefix_length

ip_range_to_prefix

ip_compress_v4_prefix

ip_compress_address

ip_is_overlap

ip_get_embedded_ipv4

ip_check_mask

ip_aggregate

ip_iptypev4

ip_iptypev6

ip_iptype

ip_check_prefix

ip_reverse

ip_normalize

ip_auth

BUGS

AUTHORS

BASED ON

SEE ALSO

Man Section

extra • Version

extra • Source

extra • Book

References