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->desc() # 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]);
for $ip ($block->enumerate([$bitstep])) { }
for $zone ($block->inaddr()) { }
my $table = {};
$block->storeNetblock([$table])
$block->deleteNetblock([$table])
$block = findNetblock(ip, [$table])
$block = findOuterNetblock(ip, [$table])
@blocks = findAllNetblock(ip, [$table])
@blocks = range2cidrlist($beginip, $endip);
@listofblocks = cidrs2contiglists(@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' 0.0.0.0/0 (the default route)
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
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 oposite 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 broadcase address.) Eg:
192.168.1.0/24 => 192.168.2.0
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) || 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 larges 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: '82.174.140.in-
addr.arpa', 0, 255, '83.174.140.in-addr.arpa',
0, 255. The list returned for the block
'216.240.32.64/27' would be: '82.174.140.in-
addr.arpa', 64, 95.
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.
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)'.
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.
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 is
expected to be a string. If more than one block
in the table contains the IP address, the
largest 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.
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 rearange a list of
Net::Netmask objects such that contigueous sets
are in sublists and each sublist is
discontigeous with the next.
For example, given a list of Net::Netmask
objects corrosponding 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
The behavior for overlapping blocks is not
currently defined.
LICENSE
Copyright (C) 1998, 2001 David Muir Sharnoff. License hereby granted for
anyone to use, modify or redistribute this module at their own risk.
Please feed useful changes back to
[email protected].
