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.

COPYRIGHT
    Copyright (C) 1998, 2001 David Muir Sharnoff. All rights reserved. License hereby
    granted for anyone to use this module at their own risk. Please feed useful changes
    back to muir@idiom.com.

