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

FreeBSD Manual Pages

  
 
  

home | help
Lite(3)		      User Contributed Perl Documentation	       Lite(3)

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

SYNOPSIS
	 use NetAddr::IP::Lite qw(
	       Zeros
	       Ones
	       V4mask
	       V4net
	       :aton
	       :old_nth
	 );

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

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

	 if ($ip->within(new NetAddr::IP::Lite "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();

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

	       perl Makefile.PL
	       make
	       make test
	       make install

       NetAddr::IP::Lite depends on 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

DESCRIPTION
       This module provides an object-oriented abstraction on top of IP
       addresses or IP subnets,	that allows for	easy manipulations. Most of
       the operations of NetAddr::IP are supported. This module	will work
       older versions of Perl and does not use Math::BigInt.

       The internal representation of all IP objects is	in 128 bit IPv6
       notation.  IPv4 and IPv6	objects	may be freely mixed.

       The supported operations	are described below:

   Overloaded Operators
       Assignment ("=")
	   Has been optimized to copy one NetAddr::IP::Lite object to another
	   very	quickly.

       "->copy()"
	   The assignment ("=")	operation is only put in to operation when the
	   copied object is further mutated by another overloaded operation.
	   See overload	SPECIAL	SYMBOLS	FOR "use overload" for details.

	   "->copy()" actually creates a new object when called.

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

		   my $ip = new	NetAddr::IP::Lite '192.168.1.123';
		   print "$ip\n";

	   Will	print the string 192.168.1.123/32.

		   my $ip = new6 NetAddr::IP::Lite '192.168.1.123';
		   print "$ip\n";

	   Will	print the string

       Equality
	   You can test	for equality with either "eq" or "==". "eq" allows the
	   comparison with arbitrary strings as	well as	NetAddr::IP::Lite
	   objects. The	following example:

	       if (NetAddr::IP::Lite->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')
		  { print "Yes\n"; }

	   Will	print out "Yes".

	   Comparison with "=="	requires both operands to be NetAddr::IP::Lite
	   objects.

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

       Comparison via >, <, >=,	<=, <=>	and "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 cidr portion of
	   the masks are compared.

       Addition	of a constant
	   Adding a constant to	a NetAddr::IP::Lite object changes its address
	   part	to point to the	one so many hosts above	the start address. For
	   instance, this code:

	       print NetAddr::IP::Lite->new('127.0.0.1') + 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::Lite->new('10.0.0.1/24') + 255;

	   outputs 10.0.0.0/24.

       Substraction of a constant
	   The complement of the addition of a constant.

       Auto-increment
	   Auto-incrementing a NetAddr::IP::Lite 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.

       Auto-decrement
	   Auto-decrementing a NetAddr::IP::Lite object	performs exactly the
	   opposite of auto-incrementing it, as	you would expect.

   Methods
       "->new([$addr, [	$mask|IPv6 ]])"
       "->new6([$addr, [ $mask]])"
	   These methods creates a new address with the	supplied address in
	   $addr and an	optional netmask $mask,	which can be omitted to	get a
	   /32 or /128 netmask for IPv4	/ IPv6 addresses respectively

	   "->new6" marks 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.

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

	   prefix notation is understood, with the limitation that the range
	   speficied by	the prefix must	match with a valid subnet.

	   Addresses in	the same format	returned by "inet_aton"	or
	   "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::Lite ':aton'

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

	   $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 i.e. Math::BigInt

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

       "->broadcast()"
	   Returns a new object	refering 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.

       "->network()"
	   Returns a new object	refering 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.

       "->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::Lite 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.

       "->mask()"
	   Returns a scalar with the mask as an	IPv4 or	IPv6 text string as
	   described above.

       "->masklen()"
	   Returns a scalar the	number of one bits in the mask.

       "->bits()"
	   Returns the width of	the address in bits. Normally 32 for v4	and
	   128 for v6.

       "->version()"
	   Returns the version of the address or subnet. Currently this	can be
	   either 4 or 6.

       "->cidr()"
	   Returns a scalar with the address and mask in CIDR notation.	A
	   NetAddr::IP::Lite object stringifies	to the result of this
	   function.  (see comments about ->new6() and ->addr()	for output
	   formats)

       "->aton()"
	   Returns the address part of the NetAddr::IP::Lite object in the
	   same	format as the "inet_aton()" or "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.

       "->range()"
	   Returns a scalar with the base address and the broadcast address
	   separated by	a dash and spaces. This	is called range	notation.

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

       "$me->contains($other)"
	   Returns true	when $me completely contains $other. False is returned
	   otherwise and "undef" is returned if	$me and	$other are not both
	   "NetAddr::IP::Lite" objects.

       "$me->within($other)"
	   The complement of "->contains()". Returns true when $me is
	   completely contained	within $other, undef if	$me and	$other are not
	   both	"NetAddr::IP::Lite" objects.

       "->first()"
	   Returns a new object	representing the first usable IP address
	   within the subnet (ie, the first host address).

       "->last()"
	   Returns a new object	representing the last usable IP	address	within
	   the subnet (ie, one less than the broadcast address).

       "->nth($index)"
	   Returns a new object	representing the n-th usable IP	address	within
	   the subnet (ie, the n-th host address).  If no address is available
	   (for	example, when the network is too small for $index hosts),
	   "undef" is returned.

	   Version 4.00	of NetAddr::IP and version 1.00	of NetAddr::IP::Lite
	   implements "->nth($index)" and "->num()" exactly as the
	   documentation states.  Previous versions behaved slightly
	   differently and not in a consistent manner.

	   To use the old behavior for "->nth($index)" and "->num()":

	     use NetAddr::IP::Lite qw(:old_nth);

	     old behavior:
	     NetAddr::IP->new('10/32')->nth(0) == undef
	     NetAddr::IP->new('10/32')->nth(1) == undef
	     NetAddr::IP->new('10/31')->nth(0) == undef
	     NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31
	     NetAddr::IP->new('10/30')->nth(0) == undef
	     NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30
	     NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30
	     NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30

	   Note	that in	each case, the broadcast address is represented	in the
	   output set and that the 'zero'th index is alway undef.

	     new behavior:
	     NetAddr::IP->new('10/32')->nth(0)	== 10.0.0.0/32
	     NetAddr::IP->new('10.1/32'->nth(0)	== 10.0.0.1/32
	     NetAddr::IP->new('10/31')->nth(0)	== undef
	     NetAddr::IP->new('10/31')->nth(1)	== undef
	     NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30
	     NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30
	     NetAddr::IP->new('10/30')->nth(2) == undef

	   Note	that a /32 net always has 1 usable address while a /31 has
	   none	since it has a network and broadcast address, but no host
	   addresses. The first	index (0) returns the address immediately
	   following the network address.

       "->num()"
	   Version 4.00	of NetAddr::IP and version 1.00	of NetAddr::IP::Lite
	   Returns the number of usable	addresses IP addresses within the
	   subnet, not counting	the broadcast or network address. Previous
	   versions returned th	number of IP addresses not counting the
	   broadcast address.

	   To use the old behavior for "->nth($index)" and "->num()":

	     use NetAddr::IP::Lite qw(:old_nth);

EXPORT_OK
	       Zero
	       Ones
	       V4mask
	       V4net
	       :aton
	       :old_nth

AUTHOR
       Luis E. MuA+-oz <luismunoz@cpan.org> Michael Robinton
       <michael@bizsystems.com>

WARRANTY
       This software comes with	the  same warranty as perl itself (ie, none),
       so by using it you accept any and all the liability.

LICENSE
       This software is	(c) Luis E. MuA+-oz, 1999 - 2005, and (c) Michael
       Robinton, 2006.	It can be used under the terms of the perl artistic
       license provided	that proper credit for the work	of the author is
       preserved in the	form of	this copyright notice and license for this
       module.

SEE ALSO
       perl(1),	NetAddr::IP(3),	NetAddr::IP::Util(3)

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 1041:
	   Non-ASCII character seen before =encoding in	'MuA+-oz'. Assuming
	   CP1252

perl v5.24.1			  2006-07-06			       Lite(3)

NAME | SYNOPSIS | INSTALLATION | DESCRIPTION | EXPORT_OK | AUTHOR | WARRANTY | LICENSE | SEE ALSO | POD ERRORS

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

home | help