unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

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.  License hereby granted
       for anyone to use, modify or redistribute this module at their own
       risk.  Please feed useful changes back to <muirATidiom.com>.

       If you found this module useful, please thank me (the author) by giving
       me a chance to bid to provide your next high-speed Internet link.  I
       run multiple ISPs and can generally save you money and provide a top-
       notch service for your T1s, T3s, OC3s, etc.  Please send your request
       to <muirATidiom.com>.  Thank you.



perl v5.10.0                      2006-10-14                      Netmask(3pm)