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() 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")

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

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

                             e.g Net::Netmask->new( '10.0.0.0/24'
                             )->split(2) => ( 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
    Overloading doesn't seem to work completely 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 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 ...

    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.

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

    Copyright (C) 2011-2013 Google, Inc.

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

