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")) ...
28 if ($block->cmpblocks("network block")) ...
29 for $ip ($block->enumerate([$bitstep])) { }
31 for $zone ($block->inaddr()) { }
33 my $table = {};
35 $block->storeNetblock([$table])
36 $block->deleteNetblock([$table])
37 @missingblocks = $block->cidrs2inverse(@blocks)
38 $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 @blocks = range2cidrlist($beginip, $endip);
47 @blocks = cidrs2cidrs(@blocks_with_dups)
48 @listofblocks = cidrs2contiglists(@blocks);
50 @blocks = sort @blocks
52 @blocks = sort_network_blocks(@blocks)
53 @sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)
55
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 There are methods that provide the nearly all bits of information about
62 a network block that you might want.
63 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 There is a function for sorting by text IP address.
71
73 Net::Netmask objects are created with an IP address and optionally a
74 mask. There are many forms that are recognized:
75 '216.240.32.0/24' The preferred form.
77 '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 '216.240.32' Always a /24 block.
86 '216.240' Always a /16 block.
88 '140' Always a /8 block.
90 '216.240.32/24'
92 '216.240/16'
93 'default' 0.0.0.0/0 (the default route)
94 '216.240.32.0#0.0.31.255' A hostmask (as used by Cisco
96 access-lists).
97 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 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
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 ->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 ->mask() Returns the netmask as a string. Eg:
118 255.255.255.0.
119 ->hostmask() Returns the host mask which is the opposite of
121 the netmask. Eg: 0.0.0.255.
122 ->bits() Returns the netmask as a number of bits in the
124 network portion of the address for this block.
125 Eg: 24.
126 ->size() Returns the number of IP addresses in a block.
128 Eg: 256.
129 ->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 ->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 ->first() & ->last() Synonyms for ->base() and ->broadcast()
139 ->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 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 $ip should be a dotted-quad (eg:
153 "192.168.66.3")
154 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 $pos = $block->match($ip) or die;
163 $pos += 0;
164 ->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 ->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 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 ->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 ->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 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 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 ->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 ->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 ->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 ->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 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 ->deleteNetblock([$t]) Deletes the current block from a table of net‐
242 work blocks.
243 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 ->checkNetblock([$t]) Returns true of the netblock is already in the
251 network table.
252 ->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
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 The return value is either a Net::Netmask
270 object or undef.
271 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 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 The return value is a list of Net::Netmask
285 objects.
286
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 "" Strinification is overloaded to be the
293 ->desc() method.
294 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
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 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 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 The return value is either a Net::Netmask
324 object or undef.
325 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 The return value is a list of Net::Netmask
335 objects.
336 dumpNetworkTable([$t]) Returns a list of the networks in a network
338 table (as created by ->storeNetblock()).
339 range2cidrlist($startip, $endip)
341 Given a range of IP addresses, return a list
342 of blocks that span that range.
343 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 216.240.32.128/25
349 216.240.33.0/24
350 216.240.34.0/23
351 216.240.36.0/25
352 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 For example, given a list of Net::Netmask
360 objects corresponding to the following blocks:
361 216.240.32.128/25
363 216.240.33.0/24
364 216.240.36.0/25
365 "cidrs2contiglists" will return a list with
367 two sublists:
368 216.240.32.128/25 216.240.33.0/24
370 216.240.36.0/25
372 Overlapping blocks will be placed in the same
374 sublist.
375 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
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.
387perl v5.8.8 2005-01-04 Netmask(3)