Netmask(3pm)						User Contributed Perl Documentation					      Netmask(3pm)

NAME

	Net::Netmask - parse, manipulate and lookup IP network blocks

SYNOPSIS

       use Net::Netmask;

	$block = new Net::Netmask (network block)
	$block = new Net::Netmask (network block, netmask)
	$block = new2 Net::Netmask (network block)
	$block = new2 Net::Netmask (network block, netmask)

	print $block;		       # a.b.c.d/bits
	print $block->base()
	print $block->mask()
	print $block->hostmask()
	print $block->bits()
	print $block->size()
	print $block->maxblock()
	print $block->broadcast()
	print $block->next()
	print $block->match($ip);
	print $block->nth(1, [$bitstep]);

	if ($block->sameblock("network block")) ...
	if ($block->cmpblocks("network block")) ...

	$newblock = $block->nextblock([count]);

	for $ip ($block->enumerate([$bitstep])) { }

	for $zone ($block->inaddr()) { }

	my $table = {};
	$block->storeNetblock([$table])
	$block->deleteNetblock([$table])
	@missingblocks = $block->cidrs2inverse(@blocks)

	$block = findNetblock(ip, [$table])
	$block = findOuterNetblock(ip, [$table])
	@blocks = findAllNetblock(ip, [$table])
	if ($block->checkNetblock([$table]) ...
	$block2 = $block1->findOuterNetblock([$table])
	@blocks = dumpNetworkTable([$table])

	@blocks = range2cidrlist($beginip, $endip);
	@blocks = cidrs2cidrs(@blocks_with_dups)

	@listofblocks = cidrs2contiglists(@blocks);

	@blocks = sort @blocks
	@blocks = sort_network_blocks(@blocks)

	@sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)

DESCRIPTION

       Net::Netmask parses and understands IPv4 CIDR blocks.  It's built with an object-oriented interface.  Nearly all functions are methods that
       operate on a Net::Netmask object.

       There are methods that provide the nearly all bits of information about a network block that you might want.

       There are also functions to put a network block into a table and then later lookup network blocks by IP address in that table.  There are
       functions to turn a IP address range into a list of CIDR blocks.  There are functions to turn a list of CIDR blocks into a list of IP
       addresses.

       There is a function for sorting by text IP address.

CONSTRUCTING

       Net::Netmask objects are created with an IP address and optionally a mask.  There are many forms that are recognized:

       '216.240.32.0/24'	       The preferred form.

       '216.240.32.0:255.255.255.0'
       '216.240.32.0-255.255.255.0'
       '216.240.32.0', '255.255.255.0'
       '216.240.32.0', '0xffffff00'
       '216.240.32.0 - 216.240.32.255'
       '216.240.32.4'		       A /32 block.

       '216.240.32'		       Always a /24 block.

       '216.240'		       Always a /16 block.

       '140'			       Always a /8 block.

       '216.240.32/24'
       '216.240/16'
       'default' or 'any'	       0.0.0.0/0 (the default route)

       '216.240.32.0#0.0.31.255'       A hostmask (as used by Cisco access-lists).

       There are two constructor methods: "new" and "new2".  The difference is that "new2" will return undef for invalid netmasks and "new" will
       return a netmask object even if the constructor could not figure out what the network block should be.

       With "new", the error string can be found as $block->{'ERROR'}.	With "new2" the error can be found as Net::Netmask::errstr or
       $Net::Netmask::error.

METHODS

       ->desc() 		Returns a description of the network block.  Eg: 216.240.32.0/19.  This is also available as overloaded
				stringification.

       ->base() 		Returns base address of the network block as a string.	Eg: 216.240.32.0.  Base does not give an indication of the
				size of the network block.

       ->mask() 		Returns the netmask as a string. Eg: 255.255.255.0.

       ->hostmask()		Returns the host mask which is the opposite of the netmask.  Eg: 0.0.0.255.

       ->bits() 		Returns the netmask as a number of bits in the network portion of the address for this block.  Eg: 24.

       ->size() 		Returns the number of IP addresses in a block.	Eg: 256.

       ->broadcast()		The blocks broadcast address. (The last IP address inside the block.) Eg: 192.168.1.0/24 => 192.168.1.255

       ->next() 		The first IP address following the block. (The IP address following the broadcast address.) Eg: 192.168.1.0/24 =>
				192.168.2.0

       ->first() & ->last()	Synonyms for ->base() and ->broadcast()

       ->match($ip)		Returns a true if the IP number $ip matches the given network. That is, a true value is returned if $ip is between
				base() amd broadcast().  For example, if we have the network 192.168.1.0/24, then

				  192.168.0.255 => 0
				  192.168.1.0	=> "0 "
				  192.168.1.1	=> 1
				  ...
				  192.168.1.255 => 255

				$ip should be a dotted-quad (eg: "192.168.66.3")

				It just happens that the return value is the position within the block.  Since zero is a legal position, the true
				string "0 " is returned in it's place.	"0 " is numerically zero though.  When wanting to know the position inside
				the block, a good idiom is:

				  $pos = $block->match($ip) or die;
				  $pos += 0;

       ->maxblock()		Much of the time, it is not possible to determine the size of a network block just from it's base address.  For
				example, with the network block '216.240.32.0/27', if you only had the '216.240.32.0' portion you wouldn't be able
				to tell for certain the size of the block.  '216.240.32.0' could be anything from a '/23' to a '/32'.  The
				maxblock() method gives the size of the largest block that the current block's address would allow it to be.  The
				size is given in bits.	Eg: 23.

       ->enumerate([$bitstep)	Returns a list of all the IP addresses in the block.  Be very careful not to use this function of large blocks.
				The IP addresses are returned as strings.  Eg: '216.240.32.0', '216.240.32.1', ... '216.240.32.255'.

				If the optional argument is given, step through the block in increments of a given network size.  To step by 4,
				use a bitstep of 30 (as in a /30 network).

       ->nth($index, [$bitstep])
				Returns the nth element of the array that enumerate would return if it were called.  So, to get the first usable
				address in a block, use nth(1).  To get the broadcast address, use nth(-1).  To get the last usable adress, use
				nth(-2).

       ->inaddr()		Returns an inline list of tuples.  There is a tuple for each DNS zone name in the block.  If the block is smaller
				than a /24, then the zone of the enclosing /24 is returned.

				Each tuple contains: the DNS zone name, the last component of the first IP address in the block in that zone, the
				last component of the last IP address in the block in that zone.

				Examples: the list returned for the block '216.240.32.0/23' would be: '32.240.216.in-addr.arpa', 0, 255,
				'33.240.216.in-addr.arpa', 0, 255.  The list returned for the block '216.240.32.64/27' would be:
				'32.240.216.in-addr.arpa', 64, 95.

       ->nextblock([$count])	Without a $count, return the next block of the same size after the current one.  With a count, return the Nth
				block after the current one.  A count of -1 returns the previous block.  Undef will be returned if out of legal
				address space.

       ->sameblock($block)	Compares two blocks.  The second block will be auto-converted from a string if it isn't already a Net::Netmask
				object.  Returns 1 if they are identical.

       ->cmpblocks($block)	Compares two blocks.  The second block will be auto-converted from a string if it isn't already a Net::Netmask
				object.  Returns -1, 0, or 1 depending on which one has the lower base address or which one is larger if they have
				the same base address.

       ->contains($block)	Compares two blocks.  The second block will be auto-converted from a string if it isn't already a Net::Netmask
				object.  Returns 1 if the second block fits inside the first block.  Returns 0 otherwise.

       ->storeNetblock([$t])	Adds the current block to an table of network blocks.  The table can be used to query which network block a given
				IP address is in.

				The optional argument allows there to be more than one table.  By default, an internal table is used.	If more
				than one table is needed, then supply a reference to a HASH to store the data in.

       ->deleteNetblock([$t])	Deletes the current block from a table of network blocks.

				The optional argument allows there to be more than one table.  By default, an internal table is used.	If more
				than one table is needed, then supply a reference to a HASH to store the data in.

       ->checkNetblock([$t])	Returns true of the netblock is already in the network table.

       ->tag($name [, $value])	Tag network blocks with your own data.	The first argument is the name of your tag (hash key) and the second
				argument (if present) is the new value.  The old value is returned.

METHOD
/FUNCTION COMBOS
       findOuterNetblock(ip, [$t])
				Search the table of network blocks (created with storeNetBlock) to find if any of them contain the given IP
				address.  The IP address can either be a string or a Net::Netmask object (method invocation).  If more than one
				block in the table contains the IP address or block, the largest network block will be the one returned.

				The return value is either a Net::Netmask object or undef.

       cidrs2inverse(block, @listOfBlocks)
				Given a block and a list of blocks, cidrs2inverse() will return a list of blocks representing the IP addresses
				that are in the block but not in the list of blocks.  It finds the gaps.

				The block will be auto-converted from a string if it isn't already a Net::Netmask object.  The list of blocks
				should be Net::Netmask objects.

				The return value is a list of Net::Netmask objects.

OVERLOADING

       Overloading doesn't seem to work completeley on perl before version 5.6.1.  The test suite doesn't test overloading before that.  At least
       for sort.

       ""			Strinification is overloaded to be the ->desc() method.

       cmp			Numerical and string comparisions have been overloaded to the ->cmpblocks() method.  This allows blocks to be
				sorted without specifying a sort function.

FUNCTIONS

       sort_by_ip_address	This function is included in "Net::Netmask" simply because there doesn't seem to be a better place to put it on
				CPAN.  It turns out that there is one method for sorting dotted-quads ("a.b.c.d") that is faster than all the
				rest.  This is that way.  Use it as "sort_by_ip_address(@list_of_ips)".  That was the theory anyway.  Someone sent
				a faster version ...

       sort_network_blocks	This function is a function to sort Net::Netmask objects.  It's faster than the simpler "sort @blocks" that also
				works.

       findNetblock(ip, [$t])	Search the table of network blocks (created with storeNetBlock) to find if any of them contain the given IP
				address.  The IP address is expected to be a string.  If more than one block in the table contains the IP address,
				the smallest network block will be the one returned.

				The return value is either a Net::Netmask object or undef.

       findAllNetblock(ip, [$t])
				Search the table of network blocks (created with storeNetBlock) to find if any of them contain the given IP
				address.  The IP address is expected to be a string.   All network blocks in the table that contain the IP address
				will be returned.

				The return value is a list of Net::Netmask objects.

       dumpNetworkTable([$t])	Returns a list of the networks in a network table (as created by ->storeNetblock()).

       range2cidrlist($startip, $endip)
				Given a range of IP addresses, return a list of blocks that span that range.

				For example, range2cidrlist('216.240.32.128', '216.240.36.127'), will return a list of Net::Netmask objects that
				corrospond to:

					216.240.32.128/25
					216.240.33.0/24
					216.240.34.0/23
					216.240.36.0/25

       cidrs2contiglists(@listOfBlocks)
				"cidrs2contiglists" will rearrange a list of Net::Netmask objects such that contiguous sets are in sublists and
				each sublist is discontigeous with the next.

				For example, given a list of Net::Netmask objects corresponding to the following blocks:

					216.240.32.128/25
					216.240.33.0/24
					216.240.36.0/25

				"cidrs2contiglists" will return a list with two sublists:

					216.240.32.128/25 216.240.33.0/24

					216.240.36.0/25

				Overlapping blocks will be placed in the same sublist.

       cidrs2cidrs(@listOfBlocks)
				"cidrs2cidrs" will collapse a list of Net::Netmask objects by combining adjacent blocks into larger blocks.   It
				returns a list of blocks that covers exactly the same IP space.  Overlapping blocks will be collapsed.

LICENSE

       Copyright (C) 1998-2006 David Muir Sharnoff.

       Copyright (C) 2011 Google, Inc.

       This module may be used, modified and redistributed on the same terms as Perl itself.

perl v5.14.2							    2011-02-01							      Netmask(3pm)