1Netmask(3)            User Contributed Perl Documentation           Netmask(3)
2
3
4

NAME

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

SYNOPSIS

9               use Net::Netmask;
10
11               $block = new Net::Netmask (network block)
12               $block = new Net::Netmask (network block, netmask)
13               $block = new2 Net::Netmask (network block)
14               $block = new2 Net::Netmask (network block, netmask)
15
16               print $block;                   # a.b.c.d/bits
17               print $block->base()
18               print $block->mask()
19               print $block->hostmask()
20               print $block->bits()
21               print $block->size()
22               print $block->maxblock()
23               print $block->broadcast()
24               print $block->next()
25               print $block->match($ip);
26               print $block->nth(1, [$bitstep]);
27               if ($block->sameblock("network block")) ...
28               if ($block->cmpblocks("network block")) ...
29
30               for $ip ($block->enumerate([$bitstep])) { }
31
32               for $zone ($block->inaddr()) { }
33
34               my $table = {};
35               $block->storeNetblock([$table])
36               $block->deleteNetblock([$table])
37               @missingblocks = $block->cidrs2inverse(@blocks)
38
39               $block = findNetblock(ip, [$table])
40               $block = findOuterNetblock(ip, [$table])
41               @blocks = findAllNetblock(ip, [$table])
42               if ($block->checkNetblock([$table]) ...
43               $block2 = $block1->findOuterNetblock([$table])
44               @blocks = dumpNetworkTable([$table])
45
46               @blocks = range2cidrlist($beginip, $endip);
47               @blocks = cidrs2cidrs(@blocks_with_dups)
48
49               @listofblocks = cidrs2contiglists(@blocks);
50
51               @blocks = sort @blocks
52               @blocks = sort_network_blocks(@blocks)
53
54               @sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)
55

DESCRIPTION

57       Net::Netmask parses and understands IPv4 CIDR blocks.  It's built with
58       an object-oriented interface.  Nearly all functions are methods that
59       operate on a Net::Netmask object.
60
61       There are methods that provide the nearly all bits of information about
62       a network block that you might want.
63
64       There are also functions to put a network block into a table and then
65       later lookup network blocks by IP address in that table.  There are
66       functions to turn a IP address range into a list of CIDR blocks.  There
67       are functions to turn a list of CIDR blocks into a list of IP
68       addresses.
69
70       There is a function for sorting by text IP address.
71

CONSTRUCTING

73       Net::Netmask objects are created with an IP address and optionally a
74       mask.  There are many forms that are recognized:
75
76       '216.240.32.0/24'               The preferred form.
77
78       '216.240.32.0:255.255.255.0'
79       '216.240.32.0-255.255.255.0'
80       '216.240.32.0', '255.255.255.0'
81       '216.240.32.0', '0xffffff00'
82       '216.240.32.0 - 216.240.32.255'
83       '216.240.32.4'                  A /32 block.
84
85       '216.240.32'                    Always a /24 block.
86
87       '216.240'                       Always a /16 block.
88
89       '140'                           Always a /8 block.
90
91       '216.240.32/24'
92       '216.240/16'
93       'default'                       0.0.0.0/0 (the default route)
94
95       '216.240.32.0#0.0.31.255'       A hostmask (as used by Cisco
96                                       access-lists).
97
98       There are two constructor methods: "new" and "new2".  The difference is
99       that "new2" will return undef for invalid netmasks and "new" will
100       return a netmask object even if the constructor could not figure out
101       what the network block should be.
102
103       With "new", the error string can be found as $block->{'ERROR'}.  With
104       "new2" the error can be found as Net::Netmask::errstr or $Net::Net‐
105       mask::error.
106

METHODS

108       ->desc()                 Returns a description of the network block.
109                                Eg: 216.240.32.0/19.  This is also available
110                                as overloaded stringification.
111
112       ->base()                 Returns base address of the network block as a
113                                string.  Eg: 216.240.32.0.  Base does not give
114                                an indication of the size of the network
115                                block.
116
117       ->mask()                 Returns the netmask as a string. Eg:
118                                255.255.255.0.
119
120       ->hostmask()             Returns the host mask which is the opposite of
121                                the netmask.  Eg: 0.0.0.255.
122
123       ->bits()                 Returns the netmask as a number of bits in the
124                                network portion of the address for this block.
125                                Eg: 24.
126
127       ->size()                 Returns the number of IP addresses in a block.
128                                Eg: 256.
129
130       ->broadcast()            The blocks broadcast address. (The last IP
131                                address inside the block.) Eg: 192.168.1.0/24
132                                => 192.168.1.255
133
134       ->next()                 The first IP address following the block. (The
135                                IP address following the broadcast address.)
136                                Eg: 192.168.1.0/24 => 192.168.2.0
137
138       ->first() & ->last()     Synonyms for ->base() and ->broadcast()
139
140       ->match($ip)             Returns a true if the IP number $ip matches
141                                the given network. That is, a true value is
142                                returned if $ip is between base() amd broad‐
143                                cast().  For example, if we have the network
144                                192.168.1.0/24, then
145
146                                  192.168.0.255 => 0
147                                  192.168.1.0   => "0 "
148                                  192.168.1.1   => 1
149                                  ...
150                                  192.168.1.255 => 255
151
152                                $ip should be a dotted-quad (eg:
153                                "192.168.66.3")
154
155                                It just happens that the return value is the
156                                position within the block.  Since zero is a
157                                legal position, the true string "0 " is
158                                returned in it's place.  "0 " is numerically
159                                zero though.  When wanting to know the posi‐
160                                tion inside the block, a good idiom is:
161
162                                  $pos = $block->match($ip) or die;
163                                  $pos += 0;
164
165       ->maxblock()             Much of the time, it is not possible to deter‐
166                                mine the size of a network block just from
167                                it's base address.  For example, with the net‐
168                                work block '216.240.32.0/27', if you only had
169                                the '216.240.32.0' portion you wouldn't be
170                                able to tell for certain the size of the
171                                block.  '216.240.32.0' could be anything from
172                                a '/23' to a '/32'.  The maxblock() method
173                                gives the size of the largest block that the
174                                current block's address would allow it to be.
175                                The size is given in bits.  Eg: 23.
176
177       ->enumerate([$bitstep)   Returns a list of all the IP addresses in the
178                                block.  Be very careful not to use this func‐
179                                tion of large blocks.  The IP addresses are
180                                returned as strings.  Eg: '216.240.32.0',
181                                '216.240.32.1', ... '216.240.32.255'.
182
183                                If the optional argument is given, step
184                                through the block in increments of a given
185                                network size.  To step by 4, use a bitstep of
186                                30 (as in a /30 network).
187
188       ->nth($index, [$bitstep])
189                                Returns the nth element of the array that enu‐
190                                merate would return if it were called.  So, to
191                                get the first usable address in a block, use
192                                nth(1).  To get the broadcast address, use
193                                nth(-1).  To get the last usable adress, use
194                                nth(-2).
195
196       ->inaddr()               Returns an inline list of tuples.  There is a
197                                tuple for each DNS zone name in the block.  If
198                                the block is smaller than a /24, then the zone
199                                of the enclosing /24 is returned.
200
201                                Each tuple contains: the DNS zone name, the
202                                last component of the first IP address in the
203                                block in that zone, the last component of the
204                                last IP address in the block in that zone.
205
206                                Examples: the list returned for the block
207                                '216.240.32.0/23' would be:
208                                '32.240.216.in-addr.arpa', 0, 255,
209                                '33.240.216.in-addr.arpa', 0, 255.  The list
210                                returned for the block '216.240.32.64/27'
211                                would be: '32.240.216.in-addr.arpa', 64, 95.
212
213       ->sameblock($block)      Compares two blocks.  The second block will be
214                                auto-converted from a string if it isn't
215                                already a Net::Netmask object.  Returns 1 if
216                                they are identical.
217
218       ->cmpblocks($block)      Compares two blocks.  The second block will be
219                                auto-converted from a string if it isn't
220                                already a Net::Netmask object.  Returns -1, 0,
221                                or 1 depending on which one has the lower base
222                                address or which one is larger if they have
223                                the same base address.
224
225       ->contains($block)       Compares two blocks.  The second block will be
226                                auto-converted from a string if it isn't
227                                already a Net::Netmask object.  Returns 1 if
228                                the second block fits inside the first block.
229                                Returns 0 otherwise.
230
231       ->storeNetblock([$t])    Adds the current block to an table of network
232                                blocks.  The table can be used to query which
233                                network block a given IP address is in.
234
235                                The optional argument allows there to be more
236                                than one table.  By default, an internal table
237                                is used.   If more than one table is needed,
238                                then supply a reference to a HASH to store the
239                                data in.
240
241       ->deleteNetblock([$t])   Deletes the current block from a table of net‐
242                                work blocks.
243
244                                The optional argument allows there to be more
245                                than one table.  By default, an internal table
246                                is used.   If more than one table is needed,
247                                then supply a reference to a HASH to store the
248                                data in.
249
250       ->checkNetblock([$t])    Returns true of the netblock is already in the
251                                network table.
252
253       ->tag($name [, $value])  Tag network blocks with your own data.  The
254                                first argument is the name of your tag (hash
255                                key) and the second argument (if present) is
256                                the new value.  The old value is returned.
257

METHOD/FUNCTION COMBOS

259       findOuterNetblock(ip, [$t])
260                                Search the table of network blocks (created
261                                with storeNetBlock) to find if any of them
262                                contain the given IP address.  The IP address
263                                can either be a string or a Net::Netmask
264                                object (method invocation).  If more than one
265                                block in the table contains the IP address or
266                                block, the largest network block will be the
267                                one returned.
268
269                                The return value is either a Net::Netmask
270                                object or undef.
271
272       cidrs2inverse(block, @listOfBlocks)
273                                Given a block and a list of blocks,
274                                cidrs2inverse() will return a list of blocks
275                                representing the IP addresses that are in the
276                                block but not in the list of blocks.  It finds
277                                the gaps.
278
279                                The block will be auto-converted from a string
280                                if it isn't already a Net::Netmask object.
281                                The list of blocks should be Net::Netmask
282                                objects.
283
284                                The return value is a list of Net::Netmask
285                                objects.
286

OVERLOADING

288       Overloading doesn't seem to work completeley on perl before version
289       5.6.1.  The test suite doesn't test overloading before that.  At least
290       for sort.
291
292       ""                       Strinification is overloaded to be the
293                                ->desc() method.
294
295       cmp                      Numerical and string comparisions have been
296                                overloaded to the ->cmpblocks() method.  This
297                                allows blocks to be sorted without specifying
298                                a sort function.
299

FUNCTIONS

301       sort_by_ip_address       This function is included in "Net::Netmask"
302                                simply because there doesn't seem to be a bet‐
303                                ter place to put it on CPAN.  It turns out
304                                that there is one method for sorting dotted-
305                                quads ("a.b.c.d") that is faster than all the
306                                rest.  This is that way.  Use it as
307                                "sort_by_ip_address(@list_of_ips)".  That was
308                                the theory anyway.  Someone sent a faster ver‐
309                                sion ...
310
311       sort_network_blocks      This function is a function to sort Net::Net‐
312                                mask objects.  It's faster than the simpler
313                                "sort @blocks" that also works.
314
315       findNetblock(ip, [$t])   Search the table of network blocks (created
316                                with storeNetBlock) to find if any of them
317                                contain the given IP address.  The IP address
318                                is expected to be a string.  If more than one
319                                block in the table contains the IP address,
320                                the smallest network block will be the one
321                                returned.
322
323                                The return value is either a Net::Netmask
324                                object or undef.
325
326       findAllNetblock(ip, [$t])
327                                Search the table of network blocks (created
328                                with storeNetBlock) to find if any of them
329                                contain the given IP address.  The IP address
330                                is expected to be a string.   All network
331                                blocks in the table that contain the IP
332                                address will be returned.
333
334                                The return value is a list of Net::Netmask
335                                objects.
336
337       dumpNetworkTable([$t])   Returns a list of the networks in a network
338                                table (as created by ->storeNetblock()).
339
340       range2cidrlist($startip, $endip)
341                                Given a range of IP addresses, return a list
342                                of blocks that span that range.
343
344                                For example, range2cidrlist('216.240.32.128',
345                                '216.240.36.127'), will return a list of
346                                Net::Netmask objects that corrospond to:
347
348                                        216.240.32.128/25
349                                        216.240.33.0/24
350                                        216.240.34.0/23
351                                        216.240.36.0/25
352
353       cidrs2contiglists(@listOfBlocks)
354                                "cidrs2contiglists" will rearrange a list of
355                                Net::Netmask objects such that contiguous sets
356                                are in sublists and each sublist is disconti‐
357                                geous with the next.
358
359                                For example, given a list of Net::Netmask
360                                objects corresponding to the following blocks:
361
362                                        216.240.32.128/25
363                                        216.240.33.0/24
364                                        216.240.36.0/25
365
366                                "cidrs2contiglists" will return a list with
367                                two sublists:
368
369                                        216.240.32.128/25 216.240.33.0/24
370
371                                        216.240.36.0/25
372
373                                Overlapping blocks will be placed in the same
374                                sublist.
375
376       cidrs2cidrs(@listOfBlocks)
377                                "cidrs2cidrs" will collapse a list of
378                                Net::Netmask objects by combining adjacent
379                                blocks into larger blocks.   It returns a list
380                                of blocks that covers exactly the same IP
381                                space.  Overlapping blocks will be collapsed.
382

LICENSE

384       Copyright (C) 1998-2003 David Muir Sharnoff.  License hereby granted
385       for anyone to use, modify or redistribute this module at their own
386       risk.  Please feed useful changes back to muir@idiom.com.
387
388
389
390perl v5.8.8                       2005-01-04                        Netmask(3)
Impressum