Net::IPv6Addr(3pm) User Contributed Perl Documentation Net::IPv6Addr(3pm)
NAME
Net::IPv6Addr - Check and manipulate IPv6 addresses
VERSION
This documents version 1.02 of Net::IPv6Addr corresponding to git
commit f9065cb7b044da442df16443d65593a5a3fc6baa
<https://github.com/benkasminbullock/net-
ipv6addr/commit/f9065cb7b044da442df16443d65593a5a3fc6baa> released on
Wed Mar 31 11:11:47 2021 +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://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/synopsis.pl> in the distribution.)
DESCRIPTION
"Net::IPv6Addr" checks whether strings contain valid IPv6 addresses,
and converts IPv6 addresses into various formats.
All of "new", "is_ipv6", and "ipv6_parse" can process the following
formats:
Preferred form: x:x:x:x:x:x:x:x
"2001:db8:0:0:0:ff00:42:8329"
This is the form described as the "preferred form" in section 2.2
of "RFC1884" et al. Output with "to_string_preferred".
Compressed form with double colon: x::x etc.
"2001:db8::ff00:42:8329"
This is the "canonical text representation format" of "RFC5952".
Output with "to_string_compressed".
Mixed IPv4/IPv6 format: x:x:x:x:x:x:d.d.d.d
"2001:db8:0:0:0:ff00:0.66.131.41"
Output with "to_string_ipv4".
Mixed IPv4/IPv6 with compression: x::x:d.d.d.d, etc.
"2001:db8::ff00:0.66.131.41"
Output with "to_string_ipv4_compressed".
Big integers
An IPv6 can be changed to a Math::BigInt object or a digit string
using "to_bigint". Big integers can also be input with
"from_bigint".
Base-85-encoded: [0-9A-Za-z!#$%&()*+;<=>?@^_`{|}~-]{20}
"9R}vSQ9RqiCvG6zn?Zyh"
This encoding was given in "RFC1924" as an April Fool's joke.
Output with "to_string_base85".
In addition, the following formats can be output:
Arrays
An IPv6 can be processed into its component pieces with "to_array"
or "to_intarray".
Reverse-address pointer
An IPv6 can be processed into its reverse-address pointer, as
defined by "RFC1886", using "to_string_ip6_int".
METHODS AND FUNCTIONS
The methods and functions are listed in alphabetical order. All except
"new" serve as both object methods and standalone functions.
from_bigint
use Net::IPv6Addr 'from_bigint';
print from_bigint ('12345678901234567890')->to_string_compressed ();
produces output
::ab54:a98c:eb1f:ad2
(This example is included as from-bigint.pl
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/from-bigint.pl> in the distribution.)
Given a string or a Math::BigInt object containing a number, this
converts it into a Net::IPv6Addr object.
Parameters
A string or a Math::BigInt object. If the input is a scalar, it's
converted into a Math::BigInt object.
Returns
A Net::IPv6Addr object
Notes
Invalid input will generate an exception.
This function was added in "0.95".
in_network
use Net::IPv6Addr;
my $obj = Net::IPv6Addr->new ('dead:beef:cafe:babe:dead:beef:cafe:babe');
if ($obj->in_network ('dead:beef:ca0::/21')) {
print $obj->to_string_compressed, " is in network.\n";
}
produces output
dead:beef:cafe:babe:dead:beef:cafe:babe is in network.
(This example is included as inet.pl
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/inet.pl> in the distribution.)
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 $x is a member of the network given as the
argument, or 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.
in_network_of_size
use Net::IPv6Addr 'in_network_of_size';
my $obj = in_network_of_size ('dead:beef:cafe:babe:dead:beef:cafe:babe', 42);
print $obj->to_string_compressed ();
produces output
dead:beef:cac0::
(This example is included as inos.pl
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/inos.pl> in the distribution.)
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 a
network size in bits:
my $obj = in_network_of_size ($addr, 64);
Network size may also be given with "/" notation:
my $obj = in_network_of_size ("$addr/64");
Returns
The $n most-significant bits of $x as a new Net::IPv6Addr object.
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.
ipv6_chkip
my $niok = ipv6_chkip ('dead:beef:cafe:babe::f0ad');
Parameters
An IPv6 address string, without a prefix.
Returns
A true value (a code reference for the parser for this IP) if it's a
valid address; a false value ("undef") if not.
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.
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.
to_array
use Net::IPv6Addr 'to_array';
my @int = to_array ('dead::beef');
my $ipobj = Net::IPv6Addr->new ('dead::beef');
my @int2 = $ipobj->to_array ();
print "@int\n@int2\n";
produces output
dead 0000 0000 0000 0000 0000 0000 beef
dead 0000 0000 0000 0000 0000 0000 beef
(This example is included as array.pl
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/array.pl> in the distribution.)
Convert an IPv6 address into an array of eight hexadecimal numbers.
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.
See also "to_intarray" and "to_bigint".
to_bigint
use Net::IPv6Addr 'to_bigint';
my $int = to_bigint ('dead::beef');
my $ipobj = Net::IPv6Addr->new ('dead::beef');
my $int2 = $ipobj->to_bigint ();
print "$int\n$int2\n";
produces output
295986882420777848964380943247191621359
295986882420777848964380943247191621359
(This example is included as bigint.pl
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/bigint.pl> in the distribution.)
Convert an IPv6 address into a Math::BigInt object containing the IP
address as a single number.
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.
See also "from_bigint", "to_intarray" and "to_array".
to_intarray
use Net::IPv6Addr 'to_array';
my @int = to_array ('dead::beef');
my $ipobj = Net::IPv6Addr->new ('dead::beef');
my @int2 = $ipobj->to_array ();
print "@int\n@int2\n";
produces output
dead 0000 0000 0000 0000 0000 0000 beef
dead 0000 0000 0000 0000 0000 0000 beef
(This example is included as array.pl
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/array.pl> in the distribution.)
Convert an IPv6 address into an array of eight integer numbers.
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.
See also "to_array" and "to_bigint".
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_string_compressed
use Net::IPv6Addr 'to_string_compressed';
print to_string_compressed ('dead:beef:0000:0000:0000:0000:cafe:babe');
produces output
dead:beef::cafe:babe
(This example is included as compressed.pl
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/compressed.pl> in the distribution.)
This provides the "canonical text representation format" of "RFC5952".
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" ("RFC1884" et al.) or "canonical"
("RFC5952") format. Hexadecimal numbers are reduced to lower case,
consecutive zero elements are reduced to double colons, and leading
zeros are removed from strings of hexadecimal digits. All treatment of
ambiguities is as per RFC5952. (See t/rfc5952.t
<https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/t/rfc5952.t>
for tests.)
Notes
Invalid input will generate an exception.
to_string_ip6_int
use Net::IPv6Addr 'to_string_ip6_int';
my $s = to_string_ip6_int ('dead::beef');
my $ipobj = Net::IPv6Addr->new ('dead::beef');
my $s2 = $ipobj->to_string_ip6_int ();
print "$s\n$s2\n";
produces output
f.e.e.b.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.a.e.d.IP6.INT.
f.e.e.b.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.a.e.d.IP6.INT.
(This example is included as string-ip6-int.pl
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/examples/string-ip6-int.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 reverse-address pointer as defined by "RFC1886".
Notes
Invalid input will generate an exception.
The reverse process of converting these into Net::IPv6Addr objects is
not supported.
to_string_ipv4
use Net::IPv6Addr ':all';
print to_string_ipv4_compressed ('dead:beef:0:3:2:1:cafe:babe');
produces output
dead:beef::3:2:1:202.254.186.190
(This example is included as to-string-ipv4.pl
<https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/to-
string-ipv4.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 in the IPv4 format detailed by "RFC1884" et al.
Notes
When used as a subroutine, invalid input will generate an exception.
From version "0.95", this allows any IPv6 address to be produced, not
just the restricted forms allowed previously.
to_string_ipv4_compressed
use Net::IPv6Addr ':all';
print to_string_ipv4_compressed ('dead:beef:0:3:2:1:cafe:babe');
produces output
dead:beef::3:2:1:202.254.186.190
(This example is included as to-string-ipv4-comp.pl
<https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.02/examples/to-
string-ipv4-comp.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 in the compressed IPv4 format detailed by "RFC1884" et
al.
Notes
When used as a subroutine, invalid input will generate an exception.
From version "0.95", this allows any IPv6 address to be produced, not
just the restricted forms allowed previously.
to_string_preferred
use Net::IPv6Addr 'to_string_preferred';
print 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://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/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" et al).
Notes
Invalid input will generate an exception.
EXPORTS
As of version 1.02, "from_bigint", "in_network", "in_network_of_size",
"ipv6_chkip", "ipv6_parse", "is_ipv6", "to_array", "to_bigint",
"to_intarray", "to_string_base85", "to_string_compressed",
"to_string_ip6_int", "to_string_ipv4", "to_string_ipv4_compressed",
"to_string_preferred" may be exported on demand. All the exported
functions may be exported using
use Net::IPv6Addr ':all';
DEPENDENCIES
Math::BigInt
This is used by "to_bigint" and "from_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.
Addressing Architecture series
These are all the same standard, with updates. The most recent one is
the active one.
RFC1884 <https://www.rfc-editor.org/rfc/rfc1884.txt>
IPv6 Addressing Architecture - December 1995
RFC2373 <https://www.rfc-editor.org/rfc/rfc2373.txt>
IP Version 6 Addressing Architecture - July 1998
RFC3513 <https://www.rfc-editor.org/rfc/rfc3513.txt>
Internet Protocol Version 6 (IPv6) Addressing Architecture - April
2003
RFC4291 <https://www.rfc-editor.org/rfc/rfc4291.txt>
IP Version 6 Addressing Architecture - February 2006
Other
RFC1886 <https://www.rfc-editor.org/rfc/rfc1886.txt>
DNS Extensions to support IP version 6 - December 1995
RFC1924 <https://www.rfc-editor.org/rfc/rfc1924.txt>
A Compact Representation of IPv6 Addresses - 1 April 1996
This was an April Fool's joke.
RFC5952 <https://www.rfc-editor.org/rfc/rfc5952.txt>
A Recommendation for IPv6 Address Text Representation - August 2010
This contains a "recommendation for a canonical text representation
format of IPv6 addresses" which corresponds to the output of
"to_string_compressed" in this module.
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::Validate::IP
This module uses Socket to validate IP addresses. It offers a
number of facilities for special-purpose sub networks, like
"is_discard_ipv6", which are not offered in Net::IPv6Addr.
IPv6::Address
Its description says "A pure Perl IPv6 address manipulation
library. Emphasis on manipulation of prefixes and addresses."
It insists on having a prefix with the IP address, so
my $ipv6 = IPv6::Address->new ('2001:0:0:1:0:0:0:1');
actually fails, you have to use
my $ipv6 = IPv6::Address->new ('2001:0:0:1:0:0:0:1/64');
Net::IP
Features binary IPs (strings like '101001'), etc.
Net::IP::Minimal
It's a simplified version of "Net::IP".
Net::IPAddress::Util
It's a "Version-agnostic representation of an IP address". I have
not tried this module.
Net::IPv6Address
This module is broken and strongly not recommended.
NetAddr::IP
NetAddr::IP::Lite
These are two things in the same distribution. The documentation is
quite offputting, but there are a lot of users of the module and
stars on metacpan.
Regexp::IPv6
This module consists of a regex for validating IPv6s. Because this
module had a lot more and better tests than Net::IPv6Addr, I
included the tests and one regex from "Regexp::IPv6" in this
module. (See t/Regexp-IPv6.t
<https://fastapi.metacpan.org/source/BKB/Net-
IPv6Addr-1.02/t/Regexp-IPv6.t>) Unlike "Net::IPv6Addr",
"Regexp::IPv6" disallows "::", "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". Significant changes to the module since
then include the following:
1.02
Net::IPv4Addr dependence removed. This module suffered from the
"octal bug". This module had only been used to validate ipv4
addresses and was easy to remove.
Math::Base85 dependence removed. This module is only needed to
support the April Fool's joke method of IPv6 addresses, so if the
user doesn't already have Math::Base85, the module now disables
support for the April Fool addresses.
1.0 Checking of base 85 addresses and prefixes was made stricter in
response to user complaints.
0.95
The "from_bigint" method was added and the documentation updated to
reflect the current internet standards.
The restriction on mixed address inputs removed in "0.92" was also
removed in the output routines "to_string_ipv4" and
"to_string_ipv4_compressed".
0.92
The valid format consisting of a compressed-but-non-zero six-
element IPv6 followed by an IPv4, such as
"fe80::204:61ff:254.157.241.86", is accepted by the module.
0.9 "in_network" and "in_network_of_size" were fixed to allow more
kinds of previxes.
0.8 Exporting of some functions was added. Prior to this, everything
had to be done fully-qualified, as in
"Net::IPv6Addr::to_string_compressed".
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
<https://metacpan.org/author/NEILB>).
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.
perl v5.32.1 2021-09-21 Net::IPv6Addr(3pm)
Generated by dwww version 1.15 on Wed Jun 26 05:39:56 CEST 2024.