Net::IPv6Addr(3)

NAME
Net::IPv6Addr - Check validity of IPv6 addresses

VERSION
This documents version 0.91 of Net::IPv6Addr corresponding to git commit c2d4788cdfc81b2f08562860e4cfe0a2373a35c2 <https://github.com/benkasminbullock/net-ipv6addr/commit/c2d4788cdfc81b2f08562860e4cfe0a2373a35c2> released on Fri Oct 6 12:00:28 2017 +0900.

SYNOPSIS
    use Net::IPv6Addr;
    my $addr = "dead:beef:cafe:babe::f0ad";
    Net::IPv6Addr::ipv6_parse($addr);
    my $x = Net::IPv6Addr->new($addr);
    print $x->to_string_preferred(), "\n";

produces output

    dead:beef:cafe:babe:0:0:0:f0ad

(This example is included as synopsis.pl <https://api.metacpan.org/source/BKB/Net-IPv6Addr-0.91/examples/synopsis.pl> in the distribution.)

DESCRIPTION
"Net::IPv6Addr" checks strings for valid IPv6 addresses, as specified in RFC1884, and converts addresses into various formats. It is able to process addresses formatted in the following styles;

preferred form: x:x:x:x:x:x:x:x
zero-compressed form: the infamous double-colon.
    Too many pattern matches to describe in this margin.

mixed IPv4/IPv6 format: x:x:x:x:x:x:d.d.d.d
mixed IPv4/IPv6 with compression: ::d.d.d.d or ::FFFF:d.d.d.d
base-85-encoded: [0-9A-Za-z!#$%&()*+;<=>?@^_`{|}~-]{20}
    (This encoding was given in RFC1924 as an April Fool's joke.)

METHODS AND FUNCTIONS
Several of the following serve as both object methods and standalone functions.

  new
    my $ni = Net::IPv6Addr->new ('dead:beef:cafe:babe::f0ad');

Create a new Net::IPv6Addr object from a string. Internally, the object is a blessed array reference containing the eight parts of the address as integers.

Parameters

A string to be interpreted as an IPv6 address.

Returns

A "Net::IPv6Addr" object if successful.

Notes

Throws an exception if the string isn't a valid address.

  ipv6_parse
    my ($ni, $pl) = ipv6_parse ('dead:beef:cafe:babe::f0ad');

Parameters

Either a string containing an IPv6 address string, which may also include a "/" character and a numeric prefix length,

    my ($x, $y) = ipv6_parse ("a::/24");

or an IPv6 address string, with an optional second argument consisting of a numeric prefix length:

    my ($x, $y) = ipv6_parse('a::', '24');

Returns

Called in array context, the return value is a list consisting of the address string and the prefix, if it parses correctly. Called in scalar context, the address and prefix are concatenated with "/".

Notes

Throws an exception on malformed input.

  is_ipv6
    my $niok = is_ipv6 ('dead:beef:cafe:babe::f0ad');

Parameters

Identical to "ipv6_parse".

Returns

This returns the return value of "ipv6_parse", called in scalar context, if it does parse out correctly, otherwise it returns "undef". Unlike "ipv6_parse", is_ipv6 does not throw exceptions.

  ipv6_chkip
    my $niok = ipv6_chkip ('dead:beef:cafe:babe::f0ad');

Parameters

An IPv6 address string, without a prefix.

Returns

Something true if it's a valid address; something false otherwise.

  to_string_preferred
    use Net::IPv6Addr;
    print Net::IPv6Addr::to_string_preferred ('dead:beef:cafe:babe::f0ad');

produces output

    dead:beef:cafe:babe:0:0:0:f0ad

(This example is included as preferred.pl <https://api.metacpan.org/source/BKB/Net-IPv6Addr-0.91/examples/preferred.pl> in the distribution.)

Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

The IPv6 address, formatted in the "preferred" way (as detailed by RFC1884).

Notes

Invalid input will generate an exception.

  to_string_compressed
Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

The IPv6 address in the "compressed" format detailed by RFC1884.

Notes

Invalid input will generate an exception.

  to_string_ipv4
Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

The IPv6 address in the IPv4 format detailed by RFC1884.

Notes

Invalid input (such as an address that was not originally IPv4) will generate an exception.

  to_string_ipv4_compressed
Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

The IPv6 address in the compressed IPv4 format detailed by RFC1884.

Notes

Invalid input (such as an address that was not originally IPv4) will generate an exception.

  to_string_base85
Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

The IPv6 address in the style detailed by RFC1924.

Notes

Invalid input will generate an exception.

The base 85 encoding described in RFC1924 was an April Fool's joke.

  to_bigint
Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

The BigInt representation of the given IPv6 address.

Notes

Invalid input will generate an exception.

  to_array
Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

An array [0..7] of 16-bit hexadecimal numbers (strings).

Notes

Invalid input will generate an exception.

  to_intarray
Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

An array [0..7] of numbers.

Notes

Invalid input will generate an exception.

  to_string_ip6_int
Parameters

If used as an object method, none; if used as a subroutine, an IPv6 address string in any format.

Returns

The reverse-address pointer as defined by RFC1886.

Notes

Invalid input will generate an exception.

  in_network_of_size
    my $obj = $x->in_network_of_size ($n);

Given an input IPv6 address $x, this returns the $n most-significant bits of $x as a new Net::IPv6Addr object.

Parameters

If used as an object method, network size in bits

    my $obj = $x->in_network_of_size (64);

If used as a subroutine, an IPv6 address string in any format and network size in bits.

    my $obj = Net::IPv6::in_network_of_size ($addr, 64);

Network size may be given with / notation:

    my $obj = Net::IPv6::in_network_of_size ("$addr/64");

Returns

Network IPv6Addr of given size.

Notes

Invalid input will generate an exception.

Prior to version 0.9, this did not work correctly unless the net size was a multiple of sixteen.

  in_network
    my $ok = $x->in_network ("aa:bb:cc:dd::/64");

Parameters

If used as an object method, a network and its size in bits

    my $ok = $x->in_network ("aa:bb:cc:dd::", 64);

If used as a subroutine, an IPv6 address string in any format, followed by a network address string and its size in bits.

    my $addr = 'fd00::54:20c:29fe:fe14:ab4b';
    my $ok = Net::IPv6Addr::in_network ($addr, "aa:bb:cc:dd::", 64);

The network size may also be given with the / notation after the network address string:

    my $ok = $x->in_network("aa:bb:cc:dd::/64");

Returns

A true value if the address is a member of the network, false otherwise.

Notes

Invalid input will generate an exception.

Prior to version 0.9, this did not work correctly unless the net size was a multiple of sixteen.

EXPORTS
As of version 0.91, "in_network", "in_network_of_size", "ipv6_chkip", "ipv6_parse", "is_ipv6" may be exported on demand. The other routines need to be called in fully-qualified format, like "Net::IPv6Addr::is_ipv6". The exported functions may all be exported using

    use Net::IPv6Addr ':all';

BUGS
Known deficiencies include the following.

No tests
    Many of the routines do not have any tests. This means that alterations to the code may have unintentionally altered the module's behaviour.

Compressed + IPv4 are not accepted
    As of 0.91, the valid format consisting of a compressed-but-non-zero six-element IPv6 followed by an IPv4 is not accepted by the module. TODO tests are in t/Regexp-IPv6.t.

Report further bugs at <https://rt.cpan.org/Dist/Display.html?Name=Net-IPv6Addr> or by email to "bug-Net-IPv6Addr [at] rt.cpan.org".

DEPENDENCIES
Net::IPv4Addr, Math::Base85, Math::BigInt

  Reverse dependencies
Search grep.cpan.me for uses of this module <http://grep.cpan.me/?q=Net%3A%3AIPv6Addr%5Cb>

SEE ALSO

  RFCs
The following RFCs (requests for comment, internet standards documentation) contain information on IPv6.

RFC1884 <https://www.ietf.org/rfc/rfc1884.txt>, RFC1886 <https://www.ietf.org/rfc/rfc1886.txt>, RFC1924 <https://www.ietf.org/rfc/rfc1924.txt> (April Fool's joke), RFC2373 <https://www.ietf.org/rfc/rfc2373.txt>

The links go to the plain text online versions of the RFCs.

  Other CPAN modules
There are a very large number of CPAN modules which deal with IPv6 addresses. The following list gives all the ones I know about which overlap with this module, in alphabetical order.

Data::Checker::IP
    Uses "NetAddr::IP".

Data::Validate::IP
    Uses Socket to validate IP addresses.

IPv6::Address
Net::IP
Net::IP::Minimal
Net::IPAddress::Util
Net::IPv6Address
NetAddr::IP
NetAddr::IP::Lite
Regexp::IPv6
    Tests and one regex from "Regexp::IPv6" are included in this module. Unlike "Net::IPv6Addr", this module disallows the valid "::" IP address, which means "the unspecified addresses". See the module's documentation for details.

  Other

Online validator
    <https://www.helpsystems.com/intermapper/ipv6-test-address-validation>

HISTORY
This module was originally written by Tony Monroe in 2001 to simplify the task of maintaining DNS records after he set himself up with Freenet6.

In 2017 the module was adopted by Ben Bullock with the help of Neil Bowers as part of "CPAN day".

Exporting of some functions was added in version 0.8.

For version 0.91, IPv6 validating tests and an IPv4 validating regexp were taken from Regexp::IPv6 by Salvador Fandiño García.

AUTHOR
Tony Monroe(*)

The module's interface resembles Net::IPv4Addr by Francis J. Lacoste <francis dot lacoste at iNsu dot COM>.

Some fixes and subroutines from Jyrki Soini <jyrki dot soini at sonera dot com>.

(*) The current module maintainer (BKB) does not have any contact information for Tony Monroe. Those wishing to contact him can do so via Neil Bowers (see his CPAN user page for contact details).

LICENSE
This distribution is copyright (c) 2001-2002 Tony Monroe. All rights reserved. This software is distributed under the same license terms as Perl itself. This software comes with NO WARRANTIES WHATSOEVER, express, implied, or otherwise.