1Net::Netmask(3) User Contributed Perl Documentation Net::Netmask(3)
2
6 Net::Netmask - parse, manipulate and lookup IP network blocks
7
9 use Net::Netmask;
10 $block = Net::Netmask->new(network block)
12 $block = Net::Netmask->new(network block, netmask)
13 $block = Net::Netmask->new2(network block)
14 $block = Net::Netmask->new2(network block, netmask)
15 print $block; # a.b.c.d/bits or 1:2:3::4/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 print $block->protocol();
28 if ($block->sameblock("network block")) ...
30 if ($block->cmpblocks("network block")) ...
31 $newblock = $block->nextblock([count]);
33 for $ip ($block->enumerate([$bitstep])) { }
35 for $zone ($block->inaddr()) { }
37 my $table = {};
39 $block->storeNetblock([$table])
40 $block->deleteNetblock([$table])
41 @missingblocks = $block->cidrs2inverse(@blocks)
42 $block = findNetblock(ip, [$table])
44 $block = findOuterNetblock(ip, [$table])
45 @blocks = findAllNetblock(ip, [$table])
46 if ($block->checkNetblock([$table]) ...
47 $block2 = $block1->findOuterNetblock([$table])
48 @blocks = dumpNetworkTable([$table])
49 @blocks = range2cidrlist($beginip, $endip);
51 @blocks = cidrs2cidrs(@blocks_with_dups)
52 @listofblocks = cidrs2contiglists(@blocks);
54 @blocks = sort @blocks
56 @blocks = sort_network_blocks(@blocks)
57 @sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)
59
61 Net::Netmask parses and understands IPv4 and IPv6 CIDR blocks (see
62 <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing> for more
63 information on CIDR blocks). It's built with an object-oriented
64 interface, with functions being methods that operate on a Net::Netmask
65 object.
66 These methods provide nearly all types of information about a network
68 block that you might want.
69 There are also functions to insert a network block into a table and
71 then later lookup network blocks by IP address using that table. There
72 are functions to turn a IP address range into a list of CIDR blocks.
73 There are functions to turn a list of CIDR blocks into a list of IP
74 addresses.
75 There is a function for sorting by text IP address.
77 All functions understand both IPv4 and IPv6. Matches, finds, etc, will
79 always return false when an IPv4 address is matched against an IPv6
80 address.
81 IPv6 support was added in 1.9104.
83
85 Net::Netmask objects are created with an IP address and optionally a
86 mask. There are many forms that are recognized:
87 '216.240.32.0/24' The preferred IPv6 form.
89 '216.240.32.0:255.255.255.0'
91 '216.240.32.0-255.255.255.0'
92 '216.240.32.0', '255.255.255.0'
93 '216.240.32.0', '0xffffff00'
94 '216.240.32.0 - 216.240.32.255'
95 '216.240.32.4' A /32 block.
96 '216.240.32' Always a /24 block.
98 '216.240' Always a /16 block.
100 '140' Always a /8 block.
102 '216.240.32/24'
104 '216.240/16'
105 'default' or 'any' 0.0.0.0/0 (the default route)
106 '216.240.32.0#0.0.31.255' A hostmask (as used by Cisco access-
108 lists - that is, the hostmask is the
109 bitwise inverse of a netmask).
110 '2001:db8:1234:5678::/64' The preferred IPv6 form.
112 '2001:db8:1234:5678::9876' A /128 block.
114 'default6' or 'any6' ::/0 (the default route)
116 There are two constructor methods: "new" and "new2". "new2" differs
118 from "new" in that it will return undef for invalid netmasks, while
119 "new" will return a netmask object even if the constructor could not
120 figure out what the network block should be.
121 With "new", the error string can be found as $block->{'ERROR'}. With
123 "new2" the error can be found as Net::Netmask::errstr or
124 $Net::Netmask::error.
125
127 ->desc() Returns a description of the network block.
128 Eg: "216.240.32.0/19" or "2001:db8:1234::/48".
129 This is also available as overloaded
130 stringification.
131 ->base() Returns base address of the network block as a
133 string. Eg: "216.240.32.0". or
134 "2001:db8:1234::/48". Base does not give an
135 indication of the size of the network block.
136 ->mask() Returns the netmask as a string. Eg:
138 "255.255.255.0" or "ffff:ffff:ffff:ffff::"
139 ->hostmask() Returns the host mask which is the opposite of
141 the netmask. Eg: "0.0.0.255" or
142 "::ffff:ffff:ffff:ffff".
143 ->bits() Returns the netmask as a number of bits in the
145 network portion of the address for this block.
146 Eg: 24.
147 ->size() Returns the number of IP addresses in a block.
149 Eg: 256. For IPv6 addresses, this will be a
150 Math::BigInt object.
151 ->broadcast() The blocks broadcast address. (The last IP
153 address inside the block.) Eg: 192.168.1.0/24
154 => 192.168.1.255 or 2001:db8::/64 =>
155 2001:db8::ffff:ffff:ffff:ffff
156 ->next() The first IP address following the block. (The
158 IP address following the broadcast address.)
159 Eg: 192.168.1.0/24 => 192.168.2.0 or
160 2001:db8:0:1::/64 => 2001:db8:0:2::/64
161 ->first() & ->last() Synonyms for ->base() and ->broadcast()
163 ->protocol() Added in version 1.9102.
165 Returns the address family/protocol
167 represented by the block. Either 'IPv4' or
168 'IPv6'.
169 ->match($ip) Returns a true if the IP number $ip matches
171 the given network. That is, a true value is
172 returned if $ip is between base() and
173 broadcast(). For example, if we have the
174 network 192.168.1.0/24, then
175 192.168.0.255 => 0
177 192.168.1.0 => "0 "
178 192.168.1.1 => 1
179 ...
180 192.168.1.255 => 255
181 $ip should be a dotted-quad (eg:
183 "192.168.66.3") or an IPv6 address in standard
184 notation (eg: "2001:db8::1").
185 It just happens that the return value is the
187 position within the block. Since zero is a
188 legal position, the true string "0 " is
189 returned in it's place. "0 " is numerically
190 zero though. When wanting to know the
191 position inside the block, a good idiom is:
192 $pos = $block->match($ip) or die;
194 $pos += 0;
195 ->maxblock() Much of the time, it is not possible to
197 determine the size of a network block just
198 from it's base address. For example, with the
199 network block '216.240.32.0/27', if you only
200 had the '216.240.32.0' portion you wouldn't be
201 able to tell for certain the size of the
202 block. '216.240.32.0' could be anything from
203 a '/23' to a '/32'. The maxblock() method
204 gives the size of the largest block that the
205 current block's address would allow it to be.
206 The size is given in bits. Eg: 23.
207 ->enumerate([$bitstep) Returns a list of all the IP addresses in the
209 block. Be very careful not to use this
210 function of large blocks. The IP addresses
211 are returned as strings. Eg: '216.240.32.0',
212 '216.240.32.1', ... '216.240.32.255'.
213 If the optional argument is given, step
215 through the block in increments of a given
216 network size. To step by 4, use a bitstep of
217 30 (as in a /30 network).
218 Note that for IPv6, this will return failure
220 if more than 1,000,000,000 addresses would be
221 returned.
222 ->nth($index, [$bitstep])
224 Returns the nth element of the array that
225 enumerate would return if it were called. So,
226 to get the first usable address in a block,
227 use nth(1). To get the broadcast address, use
228 nth(-1). To get the last usable address, use
229 nth(-2).
230 ->inaddr() Returns an inline list of tuples.
232 For IPv4:
234 There is a tuple for each DNS zone name (at
236 the /24 level) in the block. If the block is
237 smaller than a /24, then the zone of the
238 enclosing /24 is returned.
239 Each tuple contains: the DNS zone name, the
241 last component of the first IP address in the
242 block in that zone, the last component of the
243 last IP address in the block in that zone.
244 Examples: the list returned for the block
246 '216.240.32.0/23' would be:
247 '32.240.216.in-addr.arpa', 0, 255,
248 '33.240.216.in-addr.arpa', 0, 255. The list
249 returned for the block '216.240.32.64/27'
250 would be: '32.240.216.in-addr.arpa', 64, 95.
251 For IPv6:
253 A list is returned with each DNS zone name at
255 the shortest-prefix length possible. This is
256 not returned as a tuple, but just a list of
257 strings.
258 Examples: the list returned for the block
260 '2002::/16' would be a one element list,
261 containing just 2.0.0.2.ip6.arpa'. The list
262 for '2002::/17' would return a two element
263 list containing '0.2.0.0.2.ip6.arpa' and
264 '1.2.0.0.2.ip6.arpa'.
265 ->nextblock([$count]) Without a $count, return the next block of the
267 same size after the current one. With a
268 count, return the Nth block after the current
269 one. A count of -1 returns the previous
270 block. Undef will be returned if out of legal
271 address space.
272 ->sameblock($block) Compares two blocks. The second block will be
274 auto-converted from a string if it isn't
275 already a Net::Netmask object. Returns 1 if
276 they are identical.
277 ->cmpblocks($block) Compares two blocks. The second block will be
279 auto-converted from a string if it isn't
280 already a Net::Netmask object. Returns -1, 0,
281 or 1 depending on which one has the lower base
282 address or which one is larger if they have
283 the same base address.
284 ->contains($block) Compares two blocks. The second block will be
286 auto-converted from a string if it isn't
287 already a Net::Netmask object. Returns 1 if
288 the second block fits inside the first block.
289 Returns 0 otherwise.
290 ->storeNetblock([$t]) Adds the current block to an table of network
292 blocks. The table can be used to query which
293 network block a given IP address is in.
294 The optional argument allows there to be more
296 than one table. By default, an internal table
297 is used. If more than one table is needed,
298 then supply a reference to a HASH to store the
299 data in.
300 ->deleteNetblock([$t]) Deletes the current block from a table of
302 network blocks.
303 The optional argument allows there to be more
305 than one table. By default, an internal table
306 is used. If more than one table is needed,
307 then supply a reference to a HASH to store the
308 data in.
309 ->checkNetblock([$t]) Returns true of the netblock is already in the
311 network table.
312 ->tag($name [, $value]) Tag network blocks with your own data. The
314 first argument is the name of your tag (hash
315 key) and the second argument (if present) is
316 the new value. The old value is returned.
317 ->split($parts) Splits a netmask into a number of sub
319 netblocks. This number must be a base 2 number
320 (2,4,8,16,etc.) and the number must not exceed
321 the number of IPs within this netmask.
322 For instance,
324 Net::Netmask->new( '10.0.0.0/24' )->split(2)
326 is equivilent to
328 ( Net::Netmask( '10.0.0.0/25'), Net::Netmask( '10.0.0.128/25' ) )
330
332 findOuterNetblock(ip, [$t])
333 Search the table of network blocks (created
334 with storeNetBlock) to find if any of them
335 contain the given IP address. The IP address
336 can either be a string or a Net::Netmask
337 object (method invocation). If more than one
338 block in the table contains the IP address or
339 block, the largest network block will be the
340 one returned.
341 The return value is either a Net::Netmask
343 object or undef.
344 cidrs2inverse(block, @listOfBlocks)
346 Given a block and a list of blocks,
347 cidrs2inverse() will return a list of blocks
348 representing the IP addresses that are in the
349 block but not in the list of blocks. It finds
350 the gaps.
351 The block will be auto-converted from a string
353 if it isn't already a Net::Netmask object.
354 The list of blocks should be Net::Netmask
355 objects.
356 The return value is a list of Net::Netmask
358 objects.
359
361 "" Strinification is overloaded to be the
362 ->desc() method.
363 cmp Numerical and string comparisons have been
365 overloaded to the ->cmpblocks() method. This
366 allows blocks to be sorted without specifying
367 a sort function.
368
370 sort_by_ip_address This function is included in "Net::Netmask"
371 simply because there doesn't seem to be a
372 better place to put it on CPAN. It turns out
373 that there is one method for sorting dotted-
374 quads ("a.b.c.d") that is faster than all the
375 rest. This is that way. Use it as
376 "sort_by_ip_address(@list_of_ips)". That was
377 the theory anyway. Someone sent a faster
378 version ...
379 This method also will sort IPv6 addresses, but
381 is not performance optimized. It is correct,
382 however.
383 sort_network_blocks This function is a function to sort
385 Net::Netmask objects. It's faster than the
386 simpler "sort @blocks" that also works.
387 findNetblock(ip, [$t]) Search the table of network blocks (created
389 with storeNetBlock) to find if any of them
390 contain the given IP address. The IP address
391 is expected to be a string. If more than one
392 block in the table contains the IP address,
393 the smallest network block will be the one
394 returned.
395 The return value is either a Net::Netmask
397 object or undef.
398 findAllNetblock(ip, [$t])
400 Search the table of network blocks (created
401 with storeNetBlock) to find if any of them
402 contain the given IP address. The IP address
403 is expected to be a string. All network
404 blocks in the table that contain the IP
405 address will be returned.
406 The return value is a list of Net::Netmask
408 objects.
409 dumpNetworkTable([$t]) Returns a list of the networks in a network
411 table (as created by ->storeNetblock()).
412 range2cidrlist($startip, $endip)
414 Given a range of IP addresses, return a list
415 of blocks that span that range.
416 For example, range2cidrlist('216.240.32.128',
418 '216.240.36.127'), will return a list of
419 Net::Netmask objects that correspond to:
420 216.240.32.128/25
422 216.240.33.0/24
423 216.240.34.0/23
424 216.240.36.0/25
425 cidrs2contiglists(@listOfBlocks)
427 "cidrs2contiglists" will rearrange a list of
428 Net::Netmask objects such that contiguous sets
429 are in sublists and each sublist is
430 discontiguous with the next.
431 For example, given a list of Net::Netmask
433 objects corresponding to the following blocks:
434 216.240.32.128/25
436 216.240.33.0/24
437 216.240.36.0/25
438 "cidrs2contiglists" will return a list with
440 two sublists:
441 216.240.32.128/25 216.240.33.0/24
443 216.240.36.0/25
445 Overlapping blocks will be placed in the same
447 sublist.
448 cidrs2cidrs(@listOfBlocks)
450 "cidrs2cidrs" will collapse a list of
451 Net::Netmask objects by combining adjacent
452 blocks into larger blocks. It returns a list
453 of blocks that covers exactly the same IP
454 space. Overlapping blocks will be collapsed.
455
457 Joelle Maslak <jmaslak@antelope.net> (current maintainer)
458 David Muir Sharnoff (original creator/author)
460
462 Copyright (C) 1998-2006 David Muir Sharnoff.
463 Copyright (C) 2011-2013 Google, Inc.
465 Copyright (C) 2018 Joelle Maslak
467 This module may be used, modified and redistributed under the same
469 terms as Perl itself.
470perl v5.30.1 2020-01-30 Net::Netmask(3)