1Netmask(3) User Contributed Perl Documentation Netmask(3)
2
3
4
6 Net::Netmask - parse, manipulate and lookup IP network blocks
7
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
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
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
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
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
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
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
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)