#!/usr/bin/perl -w

package NetAddr::IP;

use strict;

#use diagnostics;

use Carp;

use NetAddr::IP::Lite 1.57 qw(Zero Zeros Ones V4mask V4net);

use NetAddr::IP::Util 1.53 qw(

	sub128

	inet_aton

	inet_any2n

	ipv6_aton

	isIPv4

	ipv4to6

	mask4to6

	shiftleft

	addconst

	hasbits

	notcontiguous

);

use AutoLoader qw(AUTOLOAD);

use vars qw(

	@EXPORT_OK

	@EXPORT_FAIL

	@ISA

	$VERSION

	$_netlimit

	$rfc3021

);

require Exporter;

@EXPORT_OK = qw(Compact Coalesce Zero Zeros Ones V4mask V4net netlimit);

@EXPORT_FAIL = qw($_netlimit);

@ISA = qw(Exporter NetAddr::IP::Lite);

$VERSION = do { sprintf " %d.%03d", (q$Revision: 4.79 $ =~ /\d+/g) };

$rfc3021 = 0;

=pod

=encoding UTF-8

=head1 NAME

NetAddr::IP - Manages IPv4 and IPv6 addresses and subnets

=head1 SYNOPSIS

  use NetAddr::IP qw(

	Compact

	Coalesce

	Zeros

	Ones

	V4mask

	V4net

	netlimit

	:aton		DEPRECATED

	:lower

	:upper

	:old_storable

	:old_nth

	:rfc3021

	:nofqdn

  );

  NOTE: NetAddr::IP::Util has a full complement of network address

	utilities to convert back and forth between binary and text.

	inet_aton, inet_ntoa, ipv6_aton, ipv6_ntoa 

	ipv6_n2x, ipv6_n2d inet_any2d, inet_n2dx, 

	inet_n2ad, inetanyto6, ipv6to4

See L<NetAddr::IP::Util>

  my $ip = new NetAddr::IP '127.0.0.1';

	 or if you prefer

  my $ip = NetAddr::IP->new('127.0.0.1);

	or from a packed IPv4 address

  my $ip = new_from_aton NetAddr::IP (inet_aton('127.0.0.1'));

	or from an octal filtered IPv4 address

  my $ip = new_no NetAddr::IP '127.012.0.0';

  print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;

  if ($ip->within(new NetAddr::IP "127.0.0.0", "255.0.0.0")) {

      print "Is a loopback address\n";

  }

				# This prints 127.0.0.1/32

  print "You can also say $ip...\n";

* The following four functions return ipV6 representations of:

  ::                                       = Zeros();

  FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF  = Ones();

  FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::          = V4mask();

  ::FFFF:FFFF                              = V4net();

  Will also return an ipV4 or ipV6 representation of a

  resolvable Fully Qualified Domanin Name (FQDN).

###### DEPRECATED, will be remove in version 5 ############

  * To accept addresses in the format as returned by

  inet_aton, invoke the module as:

  use NetAddr::IP qw(:aton);

###### USE new_from_aton instead ##########################

* To enable usage of legacy data files containing NetAddr::IP

objects stored using the L<Storable> module.

  use NetAddr::IP qw(:old_storable);

* To compact many smaller subnets (see: C<$me-E<gt>compact($addr1,$addr2,...)>

  @compacted_object_list = Compact(@object_list)

* Return a reference to list of C<NetAddr::IP> subnets of

C<$masklen> mask length, when C<$number> or more addresses from

C<@list_of_subnets> are found to be contained in said subnet.

  $arrayref = Coalesce($masklen, $number, @list_of_subnets)

* By default B<NetAddr::IP> functions and methods return string IPv6

addresses in uppercase.  To change that to lowercase:

NOTE: the AUGUST 2010 RFC5952 states:

    4.3. Lowercase

      The characters "a", "b", "c", "d", "e", and "f" in an IPv6

      address MUST be represented in lowercase.

It is recommended that all NEW applications using NetAddr::IP be

invoked as shown on the next line.

  use NetAddr::IP qw(:lower);

* To ensure the current IPv6 string case behavior even if the default changes:

  use NetAddr::IP qw(:upper);

* To set a limit on the size of B<nets> processed or returned by NetAddr::IP.

Set the maximum number of nets beyond which NetAddr::IP will return

an error as a power of 2 (default 16 or 65536 nets). Each 2**16

consumes approximately 4 megs of memory. A 2**20 consumes 64 megs of

memory, A 2**24 consumes 1 gigabyte of memory.

  use NetAddr::IP qw(netlimit);

  netlimit 20;

The maximum B<netlimit> allowed is 2**24. Attempts to set limits below

the default of 16 or above the maximum of 24 are ignored.

Returns true on success, otherwise C<undef>.

=cut

$_netlimit = 2 ** 16;			# default

sub netlimit($) {

  return undef unless $_[0];

  return undef if $_[0] =~ /\D/;

  return undef if $_[0] < 16;

  return undef if $_[0] > 24;

  $_netlimit = 2 ** $_[0];

};

=head1 INSTALLATION

Un-tar the distribution in an appropriate directory and type:

	perl Makefile.PL

	make

	make test

	make install

B<NetAddr::IP> depends on B<NetAddr::IP::Util> which installs by

default with its primary functions compiled using Perl's XS extensions

to build a C library. If you do not have a C complier available or

would like the slower Pure Perl version for some other reason, then

type:

	perl Makefile.PL -noxs

	make

	make test

	make install

=head1 DESCRIPTION

This module provides an object-oriented abstraction on top of IP

addresses or IP subnets that allows for easy manipulations.  Version

4.xx of NetAddr::IP will work with older versions of Perl and is

compatible with Math::BigInt.

The internal representation of all IP objects is in 128 bit IPv6 notation.

IPv4 and IPv6 objects may be freely mixed.

=head2 Overloaded Operators

Many operators have been overloaded, as described below:

=cut

				#############################################

				# These are the overload methods, placed here

				# for convenience.

				#############################################

use overload

    '@{}'	=> sub {

	return [ $_[0]->hostenum ];

    };

=pod

=over

=item B<Assignment (C<=>)>

Has been optimized to copy one NetAddr::IP object to another very quickly.

=item B<C<-E<gt>copy()>>

The B<assignment (C<=>)> operation is only put in to operation when the

copied object is further mutated by another overloaded operation. See

L<overload> B<SPECIAL SYMBOLS FOR "use overload"> for details.

B<C<-E<gt>copy()>> actually creates a new object when called.

=item B<Stringification>

An object can be used just as a string. For instance, the following code

	my $ip = new NetAddr::IP '192.168.1.123';

	print "$ip\n";

Will print the string 192.168.1.123/32.

=item B<Equality>

You can test for equality with either C<eq> or C<==>. C<eq> allows

comparison with arbitrary strings as well as NetAddr::IP objects. The

following example:

    if (NetAddr::IP->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')

       { print "Yes\n"; }

will print out "Yes".

Comparison with C<==> requires both operands to be NetAddr::IP objects.

In both cases, a true value is returned if the CIDR representation of

the operands is equal.

=item B<Comparison via E<gt>, E<lt>, E<gt>=, E<lt>=, E<lt>=E<gt> and C<cmp>>

Internally, all network objects are represented in 128 bit format.

The numeric representation of the network is compared through the

corresponding operation. Comparisons are tried first on the address portion

of the object and if that is equal then the NUMERIC cidr portion of the

masks are compared. This leads to the counterintuitive result that

	/24 > /16

Comparison should not be done on netaddr objects with different CIDR as

this may produce indeterminate - unexpected results,

rather the determination of which netblock is larger or smaller should be

done by comparing

	$ip1->masklen <=> $ip2->masklen

=item B<Addition of a constant (C<+>)>

Add a 32 bit signed constant to the address part of a NetAddr object.

This operation changes the address part to point so many hosts above the

current objects start address. For instance, this code:

    print NetAddr::IP->new('127.0.0.1/8') + 5;

will output 127.0.0.6/8. The address will wrap around at the broadcast

back to the network address. This code:

    print NetAddr::IP->new('10.0.0.1/24') + 255;

    outputs 10.0.0.0/24.

Returns the the unchanged object when the constant is missing or out of

range.

    2147483647 <= constant >= -2147483648

=item B<Subtraction of a constant (C<->)>

The complement of the addition of a constant.

=item B<Difference (C<->)>

Returns the difference between the address parts of two NetAddr::IP

objects address parts as a 32 bit signed number.

Returns B<undef> if the difference is out of range.

(See range restrictions on Addition above)

=item B<Auto-increment>

Auto-incrementing a NetAddr::IP object causes the address part to be

adjusted to the next host address within the subnet. It will wrap at

the broadcast address and start again from the network address.

=item B<Auto-decrement>

Auto-decrementing a NetAddr::IP object performs exactly the opposite

of auto-incrementing it, as you would expect.

=cut

				#############################################

				# End of the overload methods.

				#############################################

# Preloaded methods go here.

=pod

=back

=head2 Serializing and Deserializing

This module defines hooks to collaborate with L<Storable> for

serializing C<NetAddr::IP> objects, through compact and human readable

strings. You can revert to the old format by invoking this module as

  use NetAddr::IP ':old_storable';

You must do this if you have legacy data files containing NetAddr::IP

objects stored using the L<Storable> module.

=cut

my $full_format = "%04X:%04X:%04X:%04X:%04X:%04X:%D.%D.%D.%D";

my $full6_format = "%04X:%04X:%04X:%04X:%04X:%04X:%04X:%04X";

sub import

{

    if (grep { $_ eq ':old_storable' } @_) {

	@_ = grep { $_ ne ':old_storable' } @_;

    } else {

	*{STORABLE_freeze} = sub

	{

	    my $self = shift;

	    return $self->cidr();	# use stringification

	};

	*{STORABLE_thaw} = sub

	{

	    my $self	= shift;

	    my $cloning	= shift;	# Not used

	    my $serial	= shift;

	    my $ip = new NetAddr::IP $serial;

	    $self->{addr} = $ip->{addr};

	    $self->{mask} = $ip->{mask};

	    $self->{isv6} = $ip->{isv6};

	    return;

	};

    }

    if (grep { $_ eq ':aton' } @_)

    {

	$NetAddr::IP::Lite::Accept_Binary_IP = 1;

	@_ = grep { $_ ne ':aton' } @_;

    }

    if (grep { $_ eq ':old_nth' } @_)

    {

	$NetAddr::IP::Lite::Old_nth = 1;

	@_ = grep { $_ ne ':old_nth' } @_;

    }

    if (grep { $_ eq ':nofqdn'} @_)

    {

	$NetAddr::IP::NetAddr::IP::Lite::NoFQDN = 1;

	@_ = grep { $_ ne ':nofqdn' } @_;

    }

    if (grep { $_ eq ':lower' } @_)

    {

        $full_format = lc($full_format);

        $full6_format = lc($full6_format);

        NetAddr::IP::Util::lower();

	@_ = grep { $_ ne ':lower' } @_;

    }

    if (grep { $_ eq ':upper' } @_)

    {

        $full_format = uc($full_format);

        $full6_format = uc($full6_format);

        NetAddr::IP::Util::upper();

	@_ = grep { $_ ne ':upper' } @_;

    }

    if (grep { $_ eq ':rfc3021' } @_)

    {

	$rfc3021 = 1;

        @_ = grep { $_ ne ':rfc3021' } @_;

    }

    NetAddr::IP->export_to_level(1, @_);

}

sub compact {

    return (ref $_[0] eq 'ARRAY')

	? compactref($_[0])	# Compact(\@list)

	: @{compactref(\@_)};	# Compact(@list)  or ->compact(@list)

}

*Compact = \&compact;

sub Coalesce {

  return &coalesce;

}

sub hostenumref($) {

  my $r = _splitref(0,$_[0]);

  unless ((notcontiguous($_[0]->{mask}))[1] == 128 ||

	  ($rfc3021 && $_[0]->masklen == 31) ) {

    splice(@$r, 0, 1);

    splice(@$r, scalar @$r - 1, 1);

  }

  return $r;

}

sub splitref {

  unshift @_, 0;	# mark as no reverse

# perl 5.8.4 fails with this operation. see perl bug [ 23429]

#  goto &_splitref;

  &_splitref;

}

sub rsplitref {

  unshift @_, 1;	# mark as reversed

# perl 5.8.4 fails with this operation. see perl bug [ 23429]

#  goto &_splitref;

  &_splitref;

}

sub split {

  unshift @_, 0;	# mark as no reverse

  my $rv = &_splitref;

  return $rv ? @$rv : ();

}

sub rsplit {

  unshift @_, 1;	# mark as reversed

  my $rv = &_splitref;

  return $rv ? @$rv : ();

}

sub full($) {

  if (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) {

    my @hex = (unpack("n8",$_[0]->{addr}));

    $hex[9] = $hex[7] & 0xff;

    $hex[8] = $hex[7] >> 8;

    $hex[7] = $hex[6] & 0xff;

    $hex[6] >>= 8;

    return sprintf($full_format,@hex);

  } else {

    &full6;

  }

}

sub full6($) {

  my @hex = (unpack("n8",$_[0]->{addr}));

  return sprintf($full6_format,@hex);

}

sub full6m($) {

  my @hex = (unpack("n8",$_[0]->{mask}));

  return sprintf($full6_format,@hex);

}

sub DESTROY {};

1;

__END__

sub do_prefix ($$$) {

    my $mask	= shift;

    my $faddr	= shift;

    my $laddr	= shift;

    if ($mask > 24) {

	return "$faddr->[0].$faddr->[1].$faddr->[2].$faddr->[3]-$laddr->[3]";

    }

    elsif ($mask == 24) {

	return "$faddr->[0].$faddr->[1].$faddr->[2].";

    }

    elsif ($mask > 16) {

	return "$faddr->[0].$faddr->[1].$faddr->[2]-$laddr->[2].";

    }

    elsif ($mask == 16) {

	return "$faddr->[0].$faddr->[1].";

    }

    elsif ($mask > 8) {

	return "$faddr->[0].$faddr->[1]-$laddr->[1].";

    }

    elsif ($mask == 8) {

	return "$faddr->[0].";

    }

    else {

	return "$faddr->[0]-$laddr->[0]";

    }

}

=pod

=head2 Methods

=over

=item C<-E<gt>new([$addr, [ $mask|IPv6 ]])>

=item C<-E<gt>new6([$addr, [ $mask]])>

=item C<-E<gt>new_no([$addr, [ $mask]])>

=item C<-E<gt>new_from_aton($netaddr)>

=item new_cis and new_cis6 are DEPRECATED 

=item C<-E<gt>new_cis("$addr $mask)>

=item C<-E<gt>new_cis6("$addr $mask)>

The first two methods create a new address with the supplied address in

C<$addr> and an optional netmask C<$mask>, which can be omitted to get 

a /32 or /128 netmask for IPv4 / IPv6 addresses respectively.

The third method C<new_no> is exclusively for IPv4 addresses and filters

improperly formatted

dot quad strings for leading 0's that would normally be interpreted as octal

format by NetAddr per the specifications for inet_aton.

B<new_from_aton> takes a packed IPv4 address and assumes a /32 mask. This

function replaces the DEPRECATED :aton functionality which is fundamentally

broken.

The last two methods B<new_cis> and B<new_cis6> differ from B<new> and

B<new6> only in that they except the common Cisco address notation for

address/mask pairs with a B<space> as a separator instead of a slash (/)

These methods are DEPRECATED because the functionality is now included

in the other "new" methods

  i.e.  ->new_cis('1.2.3.0 24')

        or

        ->new_cis6('::1.2.3.0 120')

C<-E<gt>new6> and

C<-E<gt>new_cis6> mark the address as being in ipV6 address space even

if the format would suggest otherwise.

  i.e.  ->new6('1.2.3.4') will result in ::102:304

  addresses submitted to ->new in ipV6 notation will

  remain in that notation permanently. i.e.

        ->new('::1.2.3.4') will result in ::102:304

  whereas new('1.2.3.4') would print out as 1.2.3.4

  See "STRINGIFICATION" below.

C<$addr> can be almost anything that can be resolved to an IP address

in all the notations I have seen over time. It can optionally contain

the mask in CIDR notation.

B<prefix> notation is understood, with the limitation that the range

specified by the prefix must match with a valid subnet.

Addresses in the same format returned by C<inet_aton> or

C<gethostbyname> can also be understood, although no mask can be

specified for them. The default is to not attempt to recognize this

format, as it seems to be seldom used.

To accept addresses in that format, invoke the module as in

  use NetAddr::IP ':aton'

If called with no arguments, 'default' is assumed.

If called with an empty string as the argument, returns 'undef'

C<$addr> can be any of the following and possibly more...

  n.n

  n.n/mm

  n.n.n

  n.n.n/mm

  n.n.n.n

  n.n.n.n/mm		32 bit cidr notation

  n.n.n.n/m.m.m.m

  loopback, localhost, broadcast, any, default

  x.x.x.x/host

  0xABCDEF, 0b111111000101011110, (a bcd number)

  a netaddr as returned by 'inet_aton'

Any RFC1884 notation

  ::n.n.n.n

  ::n.n.n.n/mmm		128 bit cidr notation

  ::n.n.n.n/::m.m.m.m

  ::x:x

  ::x:x/mmm

  x:x:x:x:x:x:x:x

  x:x:x:x:x:x:x:x/mmm

  x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation

  loopback, localhost, unspecified, any, default

  ::x:x/host

  0xABCDEF, 0b111111000101011110 within the limits

  of perl's number resolution

  123456789012  a 'big' bcd number (bigger than perl likes)

  and Math::BigInt

A Fully Qualified Domain Name which returns an ipV4 address or an ipV6

address, embodied in that order. This previously undocumented feature

may be disabled with:

	use NetAddr::IP::Lite ':nofqdn';

If called with no arguments, 'default' is assumed.

If called with an empty string as the argument, returns 'undef'

=item C<-E<gt>broadcast()>

Returns a new object referring to the broadcast address of a given

subnet. The broadcast address has all ones in all the bit positions

where the netmask has zero bits. This is normally used to address all

the hosts in a given subnet.

=item C<-E<gt>network()>

Returns a new object referring to the network address of a given

subnet. A network address has all zero bits where the bits of the

netmask are zero. Normally this is used to refer to a subnet.

=item C<-E<gt>addr()>

Returns a scalar with the address part of the object as an IPv4 or IPv6 text

string as appropriate. This is useful for printing or for passing the

address part of the NetAddr::IP object to other components that expect an IP

address. If the object is an ipV6 address or was created using ->new6($ip)

it will be reported in ipV6 hex format otherwise it will be reported in dot

quad format only if it resides in ipV4 address space.

=item C<-E<gt>mask()>

Returns a scalar with the mask as an IPv4 or IPv6 text string as

described above.

=item C<-E<gt>masklen()>

Returns a scalar the number of one bits in the mask.

=item C<-E<gt>bits()>

Returns the width of the address in bits. Normally 32 for v4 and 128 for v6.

=item C<-E<gt>version()>

Returns the version of the address or subnet. Currently this can be

either 4 or 6.

=item C<-E<gt>cidr()>

Returns a scalar with the address and mask in CIDR notation. A

NetAddr::IP object I<stringifies> to the result of this function.

(see comments about ->new6() and ->addr() for output formats)

=item C<-E<gt>aton()>

Returns the address part of the NetAddr::IP object in the same format

as the C<inet_aton()> or C<ipv6_aton> function respectively. If the object

was created using ->new6($ip), the address returned will always be in ipV6

format, even for addresses in ipV4 address space.

=item C<-E<gt>range()>

Returns a scalar with the base address and the broadcast address

separated by a dash and spaces. This is called range notation.

=item C<-E<gt>prefix()>

Returns a scalar with the address and mask in ipV4 prefix

representation. This is useful for some programs, which expect its

input to be in this format. This method will include the broadcast

address in the encoding.

=cut

# only applicable to ipV4

sub prefix($) {

    return undef if $_[0]->{isv6};

    my $mask = (notcontiguous($_[0]->{mask}))[1];

    return $_[0]->addr if $mask == 128;

    $mask -= 96;

    my @faddr = split (/\./, $_[0]->first->addr);

    my @laddr = split (/\./, $_[0]->broadcast->addr);

    return do_prefix $mask, \@faddr, \@laddr;

}

=item C<-E<gt>nprefix()>

Just as C<-E<gt>prefix()>, but does not include the broadcast address.

=cut

# only applicable to ipV4

sub nprefix($) {

    return undef if $_[0]->{isv6};

    my $mask = (notcontiguous($_[0]->{mask}))[1];

    return $_[0]->addr if $mask == 128;

    $mask -= 96;

    my @faddr = split (/\./, $_[0]->first->addr);

    my @laddr = split (/\./, $_[0]->last->addr);

    return do_prefix $mask, \@faddr, \@laddr;

}

=pod

=item C<-E<gt>numeric()>

When called in a scalar context, will return a numeric representation

of the address part of the IP address. When called in an array

contest, it returns a list of two elements. The first element is as

described, the second element is the numeric representation of the

netmask.

This method is essential for serializing the representation of a

subnet.

=item C<-E<gt>bigint()>

When called in scalar context, will return a Math::BigInt

representation of the address part of the IP address. When called in

an array context, it returns a list of two elements, The first

element is as described, the second element is the Math::BigInt

representation of the netmask.

=item C<-E<gt>wildcard()>

When called in a scalar context, returns the wildcard bits

corresponding to the mask, in dotted-quad or ipV6 format as applicable.

When called in an array context, returns a two-element array. The

first element, is the address part. The second element, is the

wildcard translation of the mask.

=cut

sub wildcard($) {

  my $copy = $_[0]->copy;

  $copy->{addr} = ~ $copy->{mask};

  $copy->{addr} &= V4net unless $copy->{isv6};

  if (wantarray) {

    return ($_[0]->addr, $copy->addr);

  }

  return $copy->addr;

}

=pod

=item C<-E<gt>short()>

Returns the address part in a short or compact notation.

  (ie, 127.0.0.1 becomes 127.1).

Works with both, V4 and V6.

=cut

sub _compact_v6 ($) {

    my $addr = shift;

    my @o = split /:/, $addr;

    return $addr unless @o and grep { $_ =~ m/^0+$/ } @o;

    my @candidates	= ();

    my $start		= undef;

    for my $i (0 .. $#o)

    {

	if (defined $start)

	{

	    if ($o[$i] !~ m/^0+$/)

	    {

		push @candidates, [ $start, $i - $start ];

		$start = undef;

	    }

	}

	else

	{

	    $start = $i if $o[$i] =~ m/^0+$/;

	}

    }

    push @candidates, [$start, 8 - $start] if defined $start;

    my $l = (sort { $b->[1] <=> $a->[1] } @candidates)[0];

    return $addr unless defined $l;

    $addr = $l->[0] == 0 ? '' : join ':', @o[0 .. $l->[0] - 1];

    $addr .= '::';

    $addr .= join ':', @o[$l->[0] + $l->[1] .. $#o];

    $addr =~ s/(^|:)0{1,3}/$1/g;

    return $addr;

}

#sub _old_compV6 {

#  my @addr = split(':',shift);

#  my $found = 0;

#  my $v;

#  foreach(0..$#addr) {

#    ($v = $addr[$_]) =~ s/^0+//;

#    $addr[$_] = $v || 0;

#  }

#  @_ = reverse(1..$#addr);

#  foreach(@_) {

#    if ($addr[$_] || $addr[$_ -1]) {

#      last if $found;

#      next;

#    }

#    $addr[$_] = $addr[$_ -1] = '';

#    $found = '1';

#  }

#  (my $rv = join(':',@addr)) =~ s/:+:/::/;

#  return $rv;

#}

# thanks to Rob Riepel <riepel@networking.Stanford.EDU>

# for this faster and more compact solution 11-17-08

sub _compV6 ($) {

    my $ip = shift;

    return $ip unless my @candidates = $ip =~ /((?:^|:)0(?::0)+(?::|$))/g;

    my $longest = (sort { length($b) <=> length($a) } @candidates)[0];

    $ip =~ s/$longest/::/;

    return $ip;

}

sub short($) {

  my $addr = $_[0]->addr;

  if (! $_[0]->{isv6} && isIPv4($_[0]->{addr})) {

    my @o = split(/\./, $addr, 4);

    splice(@o, 1, 2) if $o[1] == 0 and $o[2] == 0;

    return join '.', @o;

  }

  return _compV6($addr);

}

=item C<-E<gt>canon()>

Returns the address part in canonical notation as a string.  For

ipV4, this is dotted quad, and is the same as the return value from 

"->addr()".  For ipV6 it is as per RFC5952, and is the same as the LOWER CASE value

returned by "->short()".

=cut

sub canon($) {

  my $addr = $_[0]->addr;