Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::IPv6Addr(3)      User Contributed Perl Documentation     Net::IPv6Addr(3)

NAME
       Net::IPv6Addr - Check and manipulate IPv6 addresses

VERSION
       This documents version 1.01 of Net::IPv6Addr corresponding to git
       commit 9002d5c714a91a7dc53c157af7f9a86e06c8616d
       <https://github.com/benkasminbullock/net-
       ipv6addr/commit/9002d5c714a91a7dc53c157af7f9a86e06c8616d> released on
       Sat Jun 20 13:23:08 2020	+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.01/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.01/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.01/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.01/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.01/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.01/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.01/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.01/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.01/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.01/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.01/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.01/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.01/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.01, "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
       Net::IPv4Addr
	   This	is used	to parse IPv4 addresses.

       Math::Base85
	   This	is used	to parse "RFC1924" (April Fool's) addresses.

       Math::BigInt
	   This	is used	by the "RFC1924" (April	Fool's)	address	routines and
	   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.01/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.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.0			  2020-06-20		      Net::IPv6Addr(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS AND FUNCTIONS | EXPORTS | DEPENDENCIES | SEE ALSO | HISTORY | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::IPv6Addr&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help