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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
	use Net::Netmask;

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

	print $block;			   # a.b.c.d/bits or 1:2:3::4/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]);
	print $block->protocol();

	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	and IPv6 CIDR blocks (see
       <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing> for more
       information on CIDR blocks).  It's built	with an	object-oriented
       interface, with functions being methods that operate on a Net::Netmask
       object.

       These methods provide nearly all	types of information about a network
       block that you might want.

       There are also functions	to insert a network block into a table and
       then later lookup network blocks	by IP address using 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.

       All functions understand	both IPv4 and IPv6.  Matches, finds, etc, will
       always return false when	an IPv4	address	is matched against an IPv6
       address.

       IPv6 support was	added in 1.9104.

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 IPv6 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 - that is,	the hostmask is	the
				       bitwise inverse of a netmask).

       '2001:db8:1234:5678::/64'       The preferred IPv6 form.

       '2001:db8:1234:5678::9876'      A /128 block.

       'default6' or 'any6'	       ::/0 (the default route)

       There are two constructor methods: "new"	and "new2".  "new2" differs
       from "new" in that it will return undef for invalid netmasks, while
       "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" or "2001:db8:1234::/48".
				This is	also available as overloaded
				stringification.

       ->base()			Returns	base address of	the network block as a
				string.	 Eg: "216.240.32.0".  or
				"2001:db8:1234::/48".  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"	or "ffff:ffff:ffff:ffff::"

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

       ->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.  For IPv6 addresses, this will	be a
				Math::BigInt object.

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

       ->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 or
				2001:db8:0:1::/64 => 2001:db8:0:2::/64

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

       ->protocol()		Added in version 1.9102.

				Returns	the address family/protocol
				represented by the block.  Either 'IPv4' or
				'IPv6'.

       ->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() and
				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")	or an IPv6 address in standard
				notation (eg: "2001:db8::1").

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

				Note that for IPv6, this will return failure
				if more	than 1,000,000,000 addresses would be
				returned.

       ->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 address, use
				nth(-2).

       ->inaddr()		Returns	an inline list of tuples.

				For IPv4:

				There is a tuple for each DNS zone name	(at
				the /24	level) 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.

				For IPv6:

				A list is returned with	each DNS zone name at
				the shortest-prefix length possible.  This is
				not returned as	a tuple, but just a list of
				strings.

				Examples: the list returned for	the block
				'2002::/16' would be a one element list,
				containing just	2.0.0.2.ip6.arpa'.  The	list
				for '2002::/17'	would return a two element
				list containing	'0.2.0.0.2.ip6.arpa' and
				'1.2.0.0.2.ip6.arpa'.

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

       ->split($parts)		Splits a netmask into a	number of sub
				netblocks. This	number must be a base 2	number
				(2,4,8,16,etc.)	and the	number must not	exceed
				the number of IPs within this netmask.

				For instance,

				  Net::Netmask->new( '10.0.0.0/24' )->split(2)

				is equivilent to

				  ( Net::Netmask( '10.0.0.0/25'), Net::Netmask(	'10.0.0.128/25'	) )

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
       ""			Strinification is overloaded to	be the
				->desc() method.

       cmp			Numerical and string comparisons 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	...

				This method also will sort IPv6	addresses, but
				is not performance optimized.  It is correct,
				however.

       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 correspond 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
				discontiguous 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.

AUTHORS
       Joelle Maslak <jmaslak@antelope.net> (current maintainer)

       David Muir Sharnoff (original creator/author)

LICENSE
       Copyright (C) 1998-2006 David Muir Sharnoff.

       Copyright (C) 2011-2013 Google, Inc.

       Copyright (C) 2018 Joelle Maslak

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

perl v5.32.1			  2018-07-27		       Net::Netmask(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTING | METHODS | METHOD/FUNCTION COMBOS | OVERLOADING | FUNCTIONS | AUTHORS | LICENSE

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

home | help