1Netmask(3) User Contributed Perl Documentation Netmask(3)
2
6 Net::Netmask - parse, manipulate and lookup IP network blocks
7
9 use Net::Netmask;
10 $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 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")) ...
29 if ($block->cmpblocks("network block")) ...
30 $newblock = $block->nextblock([count]);
32 for $ip ($block->enumerate([$bitstep])) { }
34 for $zone ($block->inaddr()) { }
36 my $table = {};
38 $block->storeNetblock([$table])
39 $block->deleteNetblock([$table])
40 @missingblocks = $block->cidrs2inverse(@blocks)
41 $block = findNetblock(ip, [$table])
43 $block = findOuterNetblock(ip, [$table])
44 @blocks = findAllNetblock(ip, [$table])
45 if ($block->checkNetblock([$table]) ...
46 $block2 = $block1->findOuterNetblock([$table])
47 @blocks = dumpNetworkTable([$table])
48 @blocks = range2cidrlist($beginip, $endip);
50 @blocks = cidrs2cidrs(@blocks_with_dups)
51 @listofblocks = cidrs2contiglists(@blocks);
53 @blocks = sort @blocks
55 @blocks = sort_network_blocks(@blocks)
56 @sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)
58
60 Net::Netmask parses and understands IPv4 CIDR blocks. It's built with
61 an object-oriented interface. Nearly all functions are methods that
62 operate on a Net::Netmask object.
63 There are methods that provide the nearly all bits of information about
65 a network block that you might want.
66 There are also functions to put a network block into a table and then
68 later lookup network blocks by IP address in that table. There are
69 functions to turn a IP address range into a list of CIDR blocks. There
70 are functions to turn a list of CIDR blocks into a list of IP
71 addresses.
72 There is a function for sorting by text IP address.
74
76 Net::Netmask objects are created with an IP address and optionally a
77 mask. There are many forms that are recognized:
78 '216.240.32.0/24' The preferred form.
80 '216.240.32.0:255.255.255.0'
82 '216.240.32.0-255.255.255.0'
83 '216.240.32.0', '255.255.255.0'
84 '216.240.32.0', '0xffffff00'
85 '216.240.32.0 - 216.240.32.255'
86 '216.240.32.4' A /32 block.
87 '216.240.32' Always a /24 block.
89 '216.240' Always a /16 block.
91 '140' Always a /8 block.
93 '216.240.32/24'
95 '216.240/16'
96 'default' or 'any' 0.0.0.0/0 (the default route)
97 '216.240.32.0#0.0.31.255' A hostmask (as used by Cisco access-
99 lists).
100 There are two constructor methods: "new" and "new2". The difference is
102 that "new2" will return undef for invalid netmasks and "new" will
103 return a netmask object even if the constructor could not figure out
104 what the network block should be.
105 With "new", the error string can be found as $block->{'ERROR'}. With
107 "new2" the error can be found as Net::Netmask::errstr or
108 $Net::Netmask::error.
109
111 ->desc() Returns a description of the network block.
112 Eg: 216.240.32.0/19. This is also available
113 as overloaded stringification.
114 ->base() Returns base address of the network block as a
116 string. Eg: 216.240.32.0. Base does not give
117 an indication of the size of the network
118 block.
119 ->mask() Returns the netmask as a string. Eg:
121 255.255.255.0.
122 ->hostmask() Returns the host mask which is the opposite of
124 the netmask. Eg: 0.0.0.255.
125 ->bits() Returns the netmask as a number of bits in the
127 network portion of the address for this block.
128 Eg: 24.
129 ->size() Returns the number of IP addresses in a block.
131 Eg: 256.
132 ->broadcast() The blocks broadcast address. (The last IP
134 address inside the block.) Eg: 192.168.1.0/24
135 => 192.168.1.255
136 ->next() The first IP address following the block. (The
138 IP address following the broadcast address.)
139 Eg: 192.168.1.0/24 => 192.168.2.0
140 ->first() & ->last() Synonyms for ->base() and ->broadcast()
142 ->match($ip) Returns a true if the IP number $ip matches
144 the given network. That is, a true value is
145 returned if $ip is between base() amd
146 broadcast(). For example, if we have the
147 network 192.168.1.0/24, then
148 192.168.0.255 => 0
150 192.168.1.0 => "0 "
151 192.168.1.1 => 1
152 ...
153 192.168.1.255 => 255
154 $ip should be a dotted-quad (eg:
156 "192.168.66.3")
157 It just happens that the return value is the
159 position within the block. Since zero is a
160 legal position, the true string "0 " is
161 returned in it's place. "0 " is numerically
162 zero though. When wanting to know the
163 position inside the block, a good idiom is:
164 $pos = $block->match($ip) or die;
166 $pos += 0;
167 ->maxblock() Much of the time, it is not possible to
169 determine the size of a network block just
170 from it's base address. For example, with the
171 network block '216.240.32.0/27', if you only
172 had the '216.240.32.0' portion you wouldn't be
173 able to tell for certain the size of the
174 block. '216.240.32.0' could be anything from
175 a '/23' to a '/32'. The maxblock() method
176 gives the size of the largest block that the
177 current block's address would allow it to be.
178 The size is given in bits. Eg: 23.
179 ->enumerate([$bitstep) Returns a list of all the IP addresses in the
181 block. Be very careful not to use this
182 function of large blocks. The IP addresses
183 are returned as strings. Eg: '216.240.32.0',
184 '216.240.32.1', ... '216.240.32.255'.
185 If the optional argument is given, step
187 through the block in increments of a given
188 network size. To step by 4, use a bitstep of
189 30 (as in a /30 network).
190 ->nth($index, [$bitstep])
192 Returns the nth element of the array that
193 enumerate would return if it were called. So,
194 to get the first usable address in a block,
195 use nth(1). To get the broadcast address, use
196 nth(-1). To get the last usable adress, use
197 nth(-2).
198 ->inaddr() Returns an inline list of tuples. There is a
200 tuple for each DNS zone name in the block. If
201 the block is smaller than a /24, then the zone
202 of the enclosing /24 is returned.
203 Each tuple contains: the DNS zone name, the
205 last component of the first IP address in the
206 block in that zone, the last component of the
207 last IP address in the block in that zone.
208 Examples: the list returned for the block
210 '216.240.32.0/23' would be:
211 '32.240.216.in-addr.arpa', 0, 255,
212 '33.240.216.in-addr.arpa', 0, 255. The list
213 returned for the block '216.240.32.64/27'
214 would be: '32.240.216.in-addr.arpa', 64, 95.
215 ->nextblock([$count]) Without a $count, return the next block of the
217 same size after the current one. With a
218 count, return the Nth block after the current
219 one. A count of -1 returns the previous
220 block. Undef will be returned if out of legal
221 address space.
222 ->sameblock($block) Compares two blocks. The second block will be
224 auto-converted from a string if it isn't
225 already a Net::Netmask object. Returns 1 if
226 they are identical.
227 ->cmpblocks($block) Compares two blocks. The second block will be
229 auto-converted from a string if it isn't
230 already a Net::Netmask object. Returns -1, 0,
231 or 1 depending on which one has the lower base
232 address or which one is larger if they have
233 the same base address.
234 ->contains($block) Compares two blocks. The second block will be
236 auto-converted from a string if it isn't
237 already a Net::Netmask object. Returns 1 if
238 the second block fits inside the first block.
239 Returns 0 otherwise.
240 ->storeNetblock([$t]) Adds the current block to an table of network
242 blocks. The table can be used to query which
243 network block a given IP address is in.
244 The optional argument allows there to be more
246 than one table. By default, an internal table
247 is used. If more than one table is needed,
248 then supply a reference to a HASH to store the
249 data in.
250 ->deleteNetblock([$t]) Deletes the current block from a table of
252 network blocks.
253 The optional argument allows there to be more
255 than one table. By default, an internal table
256 is used. If more than one table is needed,
257 then supply a reference to a HASH to store the
258 data in.
259 ->checkNetblock([$t]) Returns true of the netblock is already in the
261 network table.
262 ->tag($name [, $value]) Tag network blocks with your own data. The
264 first argument is the name of your tag (hash
265 key) and the second argument (if present) is
266 the new value. The old value is returned.
267
269 findOuterNetblock(ip, [$t])
270 Search the table of network blocks (created
271 with storeNetBlock) to find if any of them
272 contain the given IP address. The IP address
273 can either be a string or a Net::Netmask
274 object (method invocation). If more than one
275 block in the table contains the IP address or
276 block, the largest network block will be the
277 one returned.
278 The return value is either a Net::Netmask
280 object or undef.
281 cidrs2inverse(block, @listOfBlocks)
283 Given a block and a list of blocks,
284 cidrs2inverse() will return a list of blocks
285 representing the IP addresses that are in the
286 block but not in the list of blocks. It finds
287 the gaps.
288 The block will be auto-converted from a string
290 if it isn't already a Net::Netmask object.
291 The list of blocks should be Net::Netmask
292 objects.
293 The return value is a list of Net::Netmask
295 objects.
296
298 Overloading doesn't seem to work completeley on perl before version
299 5.6.1. The test suite doesn't test overloading before that. At least
300 for sort.
301 "" Strinification is overloaded to be the
303 ->desc() method.
304 cmp Numerical and string comparisions have been
306 overloaded to the ->cmpblocks() method. This
307 allows blocks to be sorted without specifying
308 a sort function.
309
311 sort_by_ip_address This function is included in "Net::Netmask"
312 simply because there doesn't seem to be a
313 better place to put it on CPAN. It turns out
314 that there is one method for sorting dotted-
315 quads ("a.b.c.d") that is faster than all the
316 rest. This is that way. Use it as
317 "sort_by_ip_address(@list_of_ips)". That was
318 the theory anyway. Someone sent a faster
319 version ...
320 sort_network_blocks This function is a function to sort
322 Net::Netmask objects. It's faster than the
323 simpler "sort @blocks" that also works.
324 findNetblock(ip, [$t]) Search the table of network blocks (created
326 with storeNetBlock) to find if any of them
327 contain the given IP address. The IP address
328 is expected to be a string. If more than one
329 block in the table contains the IP address,
330 the smallest network block will be the one
331 returned.
332 The return value is either a Net::Netmask
334 object or undef.
335 findAllNetblock(ip, [$t])
337 Search the table of network blocks (created
338 with storeNetBlock) to find if any of them
339 contain the given IP address. The IP address
340 is expected to be a string. All network
341 blocks in the table that contain the IP
342 address will be returned.
343 The return value is a list of Net::Netmask
345 objects.
346 dumpNetworkTable([$t]) Returns a list of the networks in a network
348 table (as created by ->storeNetblock()).
349 range2cidrlist($startip, $endip)
351 Given a range of IP addresses, return a list
352 of blocks that span that range.
353 For example, range2cidrlist('216.240.32.128',
355 '216.240.36.127'), will return a list of
356 Net::Netmask objects that corrospond to:
357 216.240.32.128/25
359 216.240.33.0/24
360 216.240.34.0/23
361 216.240.36.0/25
362 cidrs2contiglists(@listOfBlocks)
364 "cidrs2contiglists" will rearrange a list of
365 Net::Netmask objects such that contiguous sets
366 are in sublists and each sublist is
367 discontigeous with the next.
368 For example, given a list of Net::Netmask
370 objects corresponding to the following blocks:
371 216.240.32.128/25
373 216.240.33.0/24
374 216.240.36.0/25
375 "cidrs2contiglists" will return a list with
377 two sublists:
378 216.240.32.128/25 216.240.33.0/24
380 216.240.36.0/25
382 Overlapping blocks will be placed in the same
384 sublist.
385 cidrs2cidrs(@listOfBlocks)
387 "cidrs2cidrs" will collapse a list of
388 Net::Netmask objects by combining adjacent
389 blocks into larger blocks. It returns a list
390 of blocks that covers exactly the same IP
391 space. Overlapping blocks will be collapsed.
392
394 Copyright (C) 1998-2006 David Muir Sharnoff. License hereby granted
395 for anyone to use, modify or redistribute this module at their own
396 risk. Please feed useful changes back to <muir@idiom.com>.
397 If you found this module useful, please thank me (the author) by giving
399 me a chance to bid to provide your next high-speed Internet link. I
400 run multiple ISPs and can generally save you money and provide a top-
401 notch service for your T1s, T3s, OC3s, etc. Please send your request
402 to <muir@idiom.com>. Thank you.
403perl v5.12.0 2006-10-14 Netmask(3)