1IP(3) User Contributed Perl Documentation IP(3)
2
6 NetAddr::IP - Manages IPv4 and IPv6 addresses and subnets
7
9 use NetAddr::IP qw(
10 Compact
11 Coalesce
12 Zeros
13 Ones
14 V4mask
15 V4net
16 netlimit
17 :aton DEPRECATED
18 :lower
19 :upper
20 :old_storable
21 :old_nth
22 );
23 NOTE: NetAddr::IP::Util has a full complement of network address
25 utilites to convert back and from from binary to text.
26 inet_aton, inet_ntoa, ipv6_aton, ipv6_n2x, ipv6_n2d
28 inet_any2d, inet_n2dx, inet_n2ad, inetanyto6, ipv6to4
29 See NetAddr::IP::Util
31 my $ip = new NetAddr::IP::Lite '127.0.0.1';
33 or from a packed IPv4 address
34 my $ip = new_from_aton NetAddr::IP::Lite (inet_aton('127.0.0.1'));
35 or from an octal filtered IPv4 address
36 my $ip = new_no NetAddr::IP::Lite '127.012.0.0';
37 print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;
39 if ($ip->within(new NetAddr::IP "127.0.0.0", "255.0.0.0")) {
41 print "Is a loopback address\n";
42 }
43 # This prints 127.0.0.1/32
45 print "You can also say $ip...\n";
46 * The following four functions return ipV6 representations of:
48 :: = Zeros();
50 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones();
51 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask();
52 ::FFFF:FFFF = V4net();
53 ###### DEPRECATED, will be remove in version 5 ############
55 * To accept addresses in the format as returned by
57 inet_aton, invoke the module as:
58 use NetAddr::IP qw(:aton);
60 ###### USE new_from_aton instead ##########################
62 * To enable usage of legacy data files containing NetAddr::IP objects
64 stored using the Storable module.
65 use NetAddr::IP qw(:old_storable);
67 * To compact many smaller subnets (see:
69 "$me->compact($addr1,$addr2,...)"
70 @compacted_object_list = Compact(@object_list)
72 * Return a reference to list of "NetAddr::IP" subnets of $masklen mask
74 length, when $number or more addresses from @list_of_subnets are found
75 to be contained in said subnet.
76 $arrayref = Coalesce($masklen, $number, @list_of_subnets)
78 * By default NetAddr::IP functions and methods return string IPv6
80 addresses in uppercase. To change that to lowercase:
81 use NetAddr::IP qw(:lower);
83 * To ensure the current IPv6 string case behavior even if the default
85 changes:
86 use NetAddr::IP qw(:upper);
88 * To set a limit on the size of nets processed or returned by
90 NetAddr::IP. Set the maximum number of nets beyond which NetAddr::IP
91 will return and error as a power of 2 (default 16 or 65536 nets). Each
92 2**16 consumes approximately 4 megs of memory. A 2**20 consumes 64 megs
93 of memory, A 2**24 consumes 1 gigabyte of memory.
94 use NetAddr::IP qw(netlimit);
96 netlimit 20;
97 The maximum netlimit allowed is a 2**24. Attempts to set limits below
99 the default of 16 or above the maximum of 24 are ignored.
100 Returns true on success otherwise undef.
102
104 Un-tar the distribution in an appropriate directory and type:
105 perl Makefile.PL
107 make
108 make test
109 make install
110 NetAddr::IP depends on NetAddr::IP::Util which installs by default with
112 its primary functions compiled using Perl's XS extensions to build a
113 'C' library. If you do not have a 'C' complier available or would like
114 the slower Pure Perl version for some other reason, then type:
115 perl Makefile.PL -noxs
117 make
118 make test
119 make install
120
122 This module provides an object-oriented abstraction on top of IP
123 addresses or IP subnets, that allows for easy manipulations. Version
124 4.xx of NetAdder::IP will will work older versions of Perl and does not
125 use Math::BigInt as in previous versions.
126 The internal representation of all IP objects is in 128 bit IPv6
128 notation. IPv4 and IPv6 objects may be freely mixed.
129 Overloaded Operators
131 Many operators have been overloaded, as described below:
132 Assignment ("=")
134 Has been optimized to copy one NetAddr::IP object to another very
135 quickly.
136 "->copy()"
138 The assignment ("=") operation is only put in to operation when the
139 copied object is further mutated by another overloaded operation.
140 See overload SPECIAL SYMBOLS FOR "use overload" for details.
141 "->copy()" actually creates a new object when called.
143 Stringification
145 An object can be used just as a string. For instance, the following
146 code
147 my $ip = new NetAddr::IP '192.168.1.123';
149 print "$ip\n";
150 Will print the string 192.168.1.123/32.
152 Equality
154 You can test for equality with either "eq" or "==". "eq" allows the
155 comparison with arbitrary strings as well as NetAddr::IP objects.
156 The following example:
157 if (NetAddr::IP->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')
159 { print "Yes\n"; }
160 Will print out "Yes".
162 Comparison with "==" requires both operands to be NetAddr::IP
164 objects.
165 In both cases, a true value is returned if the CIDR representation
167 of the operands is equal.
168 Comparison via >, <, >=, <=, <=> and "cmp"
170 Internally, all network objects are represented in 128 bit format.
171 The numeric representation of the network is compared through the
172 corresponding operation. Comparisons are tried first on the address
173 portion of the object and if that is equal then the NUMERIC cidr
174 portion of the masks are compared. This leads to the
175 counterintuitive result that
176 /24 > /16
178 Comparison should not be done on netaddr objects with different
180 CIDR as this may produce indeterminate - unexpected results, rather
181 the determination of which netblock is larger or smaller should be
182 done by comparing
183 $ip1->masklen <=> $ip2->masklen
185 Addition of a constant ("+")
187 Add a 32 bit signed constant to the address part of a NetAddr
188 object. This operation changes the address part to point so many
189 hosts above the current objects start address. For instance, this
190 code:
191 print NetAddr::IP::Lite->new('127.0.0.1/8') + 5;
193 will output 127.0.0.6/8. The address will wrap around at the
195 broadcast back to the network address. This code:
196 print NetAddr::IP::Lite->new('10.0.0.1/24') + 255;
198 outputs 10.0.0.0/24.
200 Returns the the unchanged object when the constant is missing or
202 out of range.
203 2147483647 <= constant >= -2147483648
205 Subtraction of a constant ("-")
207 The complement of the addition of a constant.
208 Difference ("-")
210 Returns the difference between the address parts of two
211 NetAddr::IP::Lite objects address parts as a 32 bit signed number.
212 Returns undef if the difference is out of range.
214 (See range restrictions on Addition above)
216 Auto-increment
218 Auto-incrementing a NetAddr::IP object causes the address part to
219 be adjusted to the next host address within the subnet. It will
220 wrap at the broadcast address and start again from the network
221 address.
222 Auto-decrement
224 Auto-decrementing a NetAddr::IP object performs exactly the
225 opposite of auto-incrementing it, as you would expect.
226 Serializing and Deserializing
228 This module defines hooks to collaborate with Storable for serializing
229 "NetAddr::IP" objects, through compact and human readable strings. You
230 can revert to the old format by invoking this module as
231 use NetAddr::IP ':old_storable';
233 You must do this if you have legacy data files containing NetAddr::IP
235 objects stored using the Storable module.
236 Methods
238 "->new([$addr, [ $mask|IPv6 ]])"
239 "->new6([$addr, [ $mask]])"
240 "->new_no([$addr, [ $mask]])"
241 "->new_from_aton($netaddr)"
242 The first two methods create a new address with the supplied
243 address in $addr and an optional netmask $mask, which can be
244 omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses
245 respectively
246 new_from_aton takes a packed IPv4 address and assumes a /32 mask.
248 This function replaces the DEPRECATED :aton functionality which is
249 fundamentally broken.
250 The third method "new_no" is exclusively for IPv4 addresses and
252 filters improperly formatted dot quad strings for leading 0's that
253 would normally be interpreted as octal format by NetAddr per the
254 specifications for inet_aton.
255 "->new6" marks the address as being in ipV6 address space even if
257 the format would suggest otherwise.
258 i.e. ->new6('1.2.3.4') will result in ::102:304
260 addresses submitted to ->new in ipV6 notation will
262 remain in that notation permanently. i.e.
263 ->new('::1.2.3.4') will result in ::102:304
264 whereas new('1.2.3.4') would print out as 1.2.3.4
265 See "STRINGIFICATION" below.
267 $addr can be almost anything that can be resolved to an IP address
269 in all the notations I have seen over time. It can optionally
270 contain the mask in CIDR notation.
271 prefix notation is understood, with the limitation that the range
273 specified by the prefix must match with a valid subnet.
274 Addresses in the same format returned by "inet_aton" or
276 "gethostbyname" can also be understood, although no mask can be
277 specified for them. The default is to not attempt to recognize this
278 format, as it seems to be seldom used.
279 To accept addresses in that format, invoke the module as in
281 use NetAddr::IP ':aton'
283 If called with no arguments, 'default' is assumed.
285 $addr can be any of the following and possibly more...
287 n.n
289 n.n/mm
290 n.n.n
291 n.n.n/mm
292 n.n.n.n
293 n.n.n.n/mm 32 bit cidr notation
294 n.n.n.n/m.m.m.m
295 loopback, localhost, broadcast, any, default
296 x.x.x.x/host
297 0xABCDEF, 0b111111000101011110, (a bcd number)
298 a netaddr as returned by 'inet_aton'
299 Any RFC1884 notation
301 ::n.n.n.n
303 ::n.n.n.n/mmm 128 bit cidr notation
304 ::n.n.n.n/::m.m.m.m
305 ::x:x
306 ::x:x/mmm
307 x:x:x:x:x:x:x:x
308 x:x:x:x:x:x:x:x/mmm
309 x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation
310 loopback, localhost, unspecified, any, default
311 ::x:x/host
312 0xABCDEF, 0b111111000101011110 within the limits
313 of perl's number resolution
314 123456789012 a 'big' bcd number i.e. Math::BigInt
315 If called with no arguments, 'default' is assumed.
317 "->broadcast()"
319 Returns a new object referring to the broadcast address of a given
320 subnet. The broadcast address has all ones in all the bit positions
321 where the netmask has zero bits. This is normally used to address
322 all the hosts in a given subnet.
323 "->network()"
325 Returns a new object referring to the network address of a given
326 subnet. A network address has all zero bits where the bits of the
327 netmask are zero. Normally this is used to refer to a subnet.
328 "->addr()"
330 Returns a scalar with the address part of the object as an IPv4 or
331 IPv6 text string as appropriate. This is useful for printing or for
332 passing the address part of the NetAddr::IP object to other
333 components that expect an IP address. If the object is an ipV6
334 address or was created using ->new6($ip) it will be reported in
335 ipV6 hex format otherwise it will be reported in dot quad format
336 only if it resides in ipV4 address space.
337 "->mask()"
339 Returns a scalar with the mask as an IPv4 or IPv6 text string as
340 described above.
341 "->masklen()"
343 Returns a scalar the number of one bits in the mask.
344 "->bits()"
346 Returns the width of the address in bits. Normally 32 for v4 and
347 128 for v6.
348 "->version()"
350 Returns the version of the address or subnet. Currently this can be
351 either 4 or 6.
352 "->cidr()"
354 Returns a scalar with the address and mask in CIDR notation. A
355 NetAddr::IP object stringifies to the result of this function.
356 (see comments about ->new6() and ->addr() for output formats)
357 "->aton()"
359 Returns the address part of the NetAddr::IP object in the same
360 format as the "inet_aton()" or "ipv6_aton" function respectively.
361 If the object was created using ->new6($ip), the address returned
362 will always be in ipV6 format, even for addresses in ipV4 address
363 space.
364 "->range()"
366 Returns a scalar with the base address and the broadcast address
367 separated by a dash and spaces. This is called range notation.
368 "->prefix()"
370 Returns a scalar with the address and mask in ipV4 prefix
371 representation. This is useful for some programs, which expect its
372 input to be in this format. This method will include the broadcast
373 address in the encoding.
374 "->nprefix()"
376 Just as "->prefix()", but does not include the broadcast address.
377 "->numeric()"
379 When called in a scalar context, will return a numeric
380 representation of the address part of the IP address. When called
381 in an array contest, it returns a list of two elements. The first
382 element is as described, the second element is the numeric
383 representation of the netmask.
384 This method is essential for serializing the representation of a
386 subnet.
387 "->wildcard()"
389 When called in a scalar context, returns the wildcard bits
390 corresponding to the mask, in dotted-quad or ipV6 format as
391 applicable.
392 When called in an array context, returns a two-element array. The
394 first element, is the address part. The second element, is the
395 wildcard translation of the mask.
396 "->short()"
398 Returns the address part in a short or compact notation.
399 (ie, 127.0.0.1 becomes 127.1).
401 Works with both, V4 and V6.
403 "->full()"
405 Returns the address part in FULL notation for ipV4 and ipV6
406 respectively.
407 i.e. for ipV4
409 0000:0000:0000:0000:0000:0000:127.0.0.1
410 for ipV6
412 0000:0000:0000:0000:0000:0000:0000:0000
413 To force ipV4 addresses into full ipV6 format use:
415 "->full6()"
417 Returns the address part in FULL ipV6 notation
418 "$me->contains($other)"
420 Returns true when $me completely contains $other. False is returned
421 otherwise and "undef" is returned if $me and $other are not both
422 "NetAddr::IP" objects.
423 "$me->within($other)"
425 The complement of "->contains()". Returns true when $me is
426 completely contained within $other.
427 Note that $me and $other must be "NetAddr::IP" objects.
429 "->splitref($bits,[optional $bits1,$bits2,...])"
431 Returns a reference to a list of objects, representing subnets of
432 "bits" mask produced by splitting the original object, which is
433 left unchanged. Note that $bits must be longer than the original
434 mask in order for it to be splittable.
435 ERROR conditions:
437 ->splitref will DIE with the message 'netlimit exceeded'
439 if the number of return objects exceeds 'netlimit'.
440 See function 'netlimit' above (default 2**16 or 65536 nets).
441 ->splitref returns undef when C<bits> or the (bits list)
443 will not fit within the original object.
444 ->splitref returns undef if a supplied ipV4, ipV6, or NetAddr
446 mask in inappropriately formatted,
447 bits may be a CIDR mask, a dot quad or ipV6 string or a NetAddr::IP
449 object. If "bits" is missing, the object is split for into all
450 available addresses within the ipV4 or ipV6 object ( auto-mask of
451 CIDR 32, 128 respectively ).
452 With optional additional "bits" list, the original object is split
454 into parts sized based on the list. NOTE: a short list will
455 replicate the last item. If the last item is too large to for what
456 remains of the object after splitting off the first parts of the
457 list, a "best fits" list of remaining objects will be returned
458 based on an increasing sort of the CIDR values of the "bits" list.
459 i.e. my $ip = new NetAddr::IP('192.168.0.0');
461 my $objptr = $ip->split(28, 29, 28, 29, 26);
462 has split plan 28 29 28 29 26 26 26 28
464 and returns this list of objects
465 192.168.0.0/28
467 192.168.0.16/29
468 192.168.0.24/28
469 192.168.0.40/29
470 192.168.0.48/26
471 192.168.0.112/26
472 192.168.0.176/26
473 192.168.0.240/28
474 NOTE: that /26 replicates twice beyond the original request and /28
476 fills the remaining return object requirement.
477 "->rsplitref($bits,[optional $bits1,$bits2,...])"
479 "->rsplitref" is the same as "->splitref" above except that the
480 split plan is applied to the original object in reverse order.
481 i.e. my $ip = new NetAddr::IP('192.168.0.0');
483 my @objects = $ip->split(28, 29, 28, 29, 26);
484 has split plan 28 26 26 26 29 28 29 28
486 and returns this list of objects
487 192.168.0.0/28
489 192.168.0.16/26
490 192.168.0.80/26
491 192.168.0.144/26
492 192.168.0.208/29
493 192.168.0.216/28
494 192.168.0.232/29
495 192.168.0.240/28
496 "->split($bits,[optional $bits1,$bits2,...])"
498 Similar to "->splitref" above but returns the list rather than a
499 list reference. You may not want to use this if a large number of
500 objects is expected.
501 "->rsplit($bits,[optional $bits1,$bits2,...])"
503 Similar to "->rsplitref" above but returns the list rather than a
504 list reference. You may not want to use this if a large number of
505 objects is expected.
506 "->hostenum()"
508 Returns the list of hosts within a subnet.
509 ERROR conditions:
511 ->hostenum will DIE with the message 'netlimit exceeded'
513 if the number of return objects exceeds 'netlimit'.
514 See function 'netlimit' above (default 2**16 or 65536 nets).
515 "->hostenumref()"
517 Faster version of "->hostenum()", returning a reference to a list.
518 "$me->compact($addr1, $addr2, ...)"
520 "@compacted_object_list = Compact(@object_list)"
521 Given a list of objects (including $me), this method will compact
522 all the addresses and subnets into the largest (ie, least specific)
523 subnets possible that contain exactly all of the given objects.
524 Note that in versions prior to 3.02, if fed with the same IP
526 subnets multiple times, these subnets would be returned. From 3.02
527 on, a more "correct" approach has been adopted and only one address
528 would be returned.
529 Note that $me and all $addr's must be "NetAddr::IP" objects.
531 "$me->compactref(\@list)"
533 As usual, a faster version of =item "->compact()" that returns a
534 reference to a list. Note that this method takes a reference to a
535 list instead.
536 Note that $me must be a "NetAddr::IP" object.
538 "$me->coalesce($masklen, $number, @list_of_subnets)"
540 "$arrayref = Coalesce($masklen,$number,@list_of_subnets)"
541 Will return a reference to list of "NetAddr::IP" subnets of
542 $masklen mask length, when $number or more addresses from
543 @list_of_subnets are found to be contained in said subnet.
544 Subnets from @list_of_subnets with a mask shorter than $masklen are
546 passed "as is" to the return list.
547 Subnets from @list_of_subnets with a mask longer than $masklen will
549 be counted (actually, the number of IP addresses is counted)
550 towards $number.
551 Called as a method, the array will include $me.
553 WARNING: the list of subnet must be the same type. i.e ipV4 or ipV6
555 "->first()"
557 Returns a new object representing the first usable IP address
558 within the subnet (ie, the first host address).
559 "->last()"
561 Returns a new object representing the last usable IP address within
562 the subnet (ie, one less than the broadcast address).
563 "->nth($index)"
565 Returns a new object representing the n-th usable IP address within
566 the subnet (ie, the n-th host address). If no address is available
567 (for example, when the network is too small for $index hosts),
568 "undef" is returned.
569 Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
571 implements "->nth($index)" and "->num()" exactly as the
572 documentation states. Previous versions behaved slightly
573 differently and not in a consistent manner. See the README file for
574 details.
575 To use the old behavior for "->nth($index)" and "->num()":
577 use NetAddr::IP::Lite qw(:old_nth);
579 "->num()"
581 Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
582 Returns the number of usable addresses IP addresses within the
583 subnet, not counting the broadcast or network address. Previous
584 versions returned th number of IP addresses not counting the
585 broadcast address.
586 To use the old behavior for "->nth($index)" and "->num()":
588 use NetAddr::IP::Lite qw(:old_nth);
590 "->re()"
592 Returns a Perl regular expression that will match an IP address
593 within the given subnet. Defaults to ipV4 notation. Will return an
594 ipV6 regex if the address in not in ipV4 space.
595 "->re6()"
597 Returns a Perl regular expression that will match an IP address
598 within the given subnet. Always returns an ipV6 regex.
599
601 Compact
602 Coalesce
603 Zeros
604 Ones
605 V4mask
606 V4net
607 netlimit
608
610 NetAddr::IP only runs in Pure Perl mode on Windows boxes because I
611 don't have the resources or know how to get the "configure" stuff
612 working in the Windows environment. Volunteers WELCOME to port the "C"
613 portion of this module to Windows.
614
616 4.00
617 Dependence on Math::BigInt in earlier version is removed in this
618 release 4.00. NetAddr::IP now works with earlier versions of Perl.
619 The module was partitioned into three logical pieces as follows:
620 Util.pm Math and logic operation on bit strings and number
622 that represent IP addresses and masks. Conversions
623 between various number formats. Implemented in
624 C_XS for speed and PURE PERL of transportability.
625 Lite.pm Operations, simple conversions and comparisons of
627 IP addresses, notations and formats.
628 IP.pm Complex operations and conversions of IP address
630 notation, nets, subnets, and ranges.
631 The internal representation of addresses was changed to 128 bit
633 binary strings as returned by inet_pton (ipv6_aton in this module).
634 Both ipV4 and ipV6 notations can be freely mixed and matched.
635 Additional methods added to force operations into ipV6 space even
637 when ipV4 notation is used.
638 4.05
640 NetAddr::IP :aton DEPRECATED !
641 new method "new_from_aton"
642 THE FOLLOWING CHANGES MAY BREAK SOME CODE !
644 Inherited methods from Lite.pm updated as follows:
646 comparisons of the form <, >, <=, >=
648 10.0.0.0/24 {operator} 10.0.0.0/16
650 return now return the comparison of the cidr value
652 when the address portion is equal.
653 Thanks to Peter DeVries for spotting this bug.
654 ... and leading us to discover that this next fix is required
656 comparisons of the form <=>, cmp
658 now return the correct value 1, or -1
659 when the address portion is equal and the CIDR value is not
660 i.e. where /16 is > /24, etc...
661 This is the OPPOSITE of the previous return values for
663 comparison of the CIDR portion of the address object
664 4.08
666 added method ->new_from_aton to supplement broken
667 :aton functionality which is now DEPRECATED and
668 will eventually go away.
669 4.13
671 added 'no octal' method ->new_no
672 4.17
674 add support for PTHREADS in the event that perl is
675 built with <pthreads.h>. This must be invoked at build
676 time with the switch --with-threads
677 WARNING: --with-threads is not tested in a threads
679 environment. Reports welcome and solicited.
680 update _compV6 which runs faster and produces more
682 compact ipV6 addresses.
683 ....and
684 added minus (-) overloading to allow the subtraction
685 of two NetAddr::IP objects to get the difference between
686 the object->{addr}'s as a numeric value
687 Thanks to Rob Riepel <riepel@networking.Stanford.EDU> for
689 the _compV6 code and the inspiration for (-) overloading.
690 Extended the capability of 'splitref' to allow splitting of
692 objects into multiple pieces with differing CIDR masks.
693 Returned object list can be split from bottom to top
694 or from top to bottom depending on which routine is called
695 split, rsplit, splitref, rsplitref
697 Thanks to kashmish <kashmish@gmail.com> for the idea on
699 improving functionality of 'split'.
700 4.018
702 removed --with-threads, PTHREADS support, and all
703 the mutex locking - unlocking
704 updated Util.xs to be fully re-entrant and thus
706 fully thread safe.
707 4.020
709 Fixed core dump due to bug in perl 5.8.4 handling of
710 @_ in goto &sub operations. Unfortunately this version
711 of perl is standard on Solaris, 5.85 on RedHat and I'm
712 sure other distributions. -- all should be upgraded!
713 Similar behavior exists in perl versions 5.80 - 5.85
714 See perl bug [ 23429].
715 Included missing code to parse BCD numbers as argument
717 to sub new(bcdnum). Thanks to Carlos Vicente cvicente@cpan.org
718 for reporting this bug.
719
721 Luis E. MuA~XAXoz <luismunoz@cpan.org>, Michael Robinton
722 <michael@bizsystems.com>
723
725 This software comes with the same warranty as perl itself (ie, none),
726 so by using it you accept any and all the liability.
727
729 This software is (c) Luis E. MuA~XAXoz, 1999 - 2007, and (c) Michael
730 Robinton, 2006 - 2008. It can be used under the terms of the Perl
731 artistic license provided that proper credit for the work of the
732 authors is preserved in the form of this copyright notice and license
733 for this module.
734
736 perl(1),NetAddr::IP::Lite, NetAddr::IP::Util.
737perl v5.10.1 2011-10-04 IP(3)