1IP(3)                 User Contributed Perl Documentation                IP(3)
2
3
4

NAME

6       NetAddr::IP - Manages IPv4 and IPv6 addresses and subnets
7

SYNOPSIS

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               :rfc3021
23               :nofqdn
24         );
25
26         NOTE: NetAddr::IP::Util has a full complement of network address
27               utilities to convert back and forth between binary and text.
28
29               inet_aton, inet_ntoa, ipv6_aton, ipv6_ntoa
30               ipv6_n2x, ipv6_n2d inet_any2d, inet_n2dx,
31               inet_n2ad, inetanyto6, ipv6to4
32
33       See NetAddr::IP::Util
34
35         my $ip = new NetAddr::IP '127.0.0.1';
36                or if you prefer
37         my $ip = NetAddr::IP->new('127.0.0.1);
38               or from a packed IPv4 address
39         my $ip = new_from_aton NetAddr::IP (inet_aton('127.0.0.1'));
40               or from an octal filtered IPv4 address
41         my $ip = new_no NetAddr::IP '127.012.0.0';
42
43         print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;
44
45         if ($ip->within(new NetAddr::IP "127.0.0.0", "255.0.0.0")) {
46             print "Is a loopback address\n";
47         }
48
49                                       # This prints 127.0.0.1/32
50         print "You can also say $ip...\n";
51
52       * The following four functions return ipV6 representations of:
53
54         ::                                       = Zeros();
55         FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF  = Ones();
56         FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::          = V4mask();
57         ::FFFF:FFFF                              = V4net();
58
59         Will also return an ipV4 or ipV6 representation of a
60         resolvable Fully Qualified Domanin Name (FQDN).
61
62       ###### DEPRECATED, will be remove in version 5 ############
63
64         * To accept addresses in the format as returned by
65         inet_aton, invoke the module as:
66
67         use NetAddr::IP qw(:aton);
68
69       ###### USE new_from_aton instead ##########################
70
71       * To enable usage of legacy data files containing NetAddr::IP objects
72       stored using the Storable module.
73
74         use NetAddr::IP qw(:old_storable);
75
76       * To compact many smaller subnets (see:
77       "$me->compact($addr1,$addr2,...)"
78
79         @compacted_object_list = Compact(@object_list)
80
81       * Return a reference to list of "NetAddr::IP" subnets of $masklen mask
82       length, when $number or more addresses from @list_of_subnets are found
83       to be contained in said subnet.
84
85         $arrayref = Coalesce($masklen, $number, @list_of_subnets)
86
87       * By default NetAddr::IP functions and methods return string IPv6
88       addresses in uppercase.  To change that to lowercase:
89
90       NOTE: the AUGUST 2010 RFC5952 states:
91
92           4.3. Lowercase
93
94             The characters "a", "b", "c", "d", "e", and "f" in an IPv6
95             address MUST be represented in lowercase.
96
97       It is recommended that all NEW applications using NetAddr::IP be
98       invoked as shown on the next line.
99
100         use NetAddr::IP qw(:lower);
101
102       * To ensure the current IPv6 string case behavior even if the default
103       changes:
104
105         use NetAddr::IP qw(:upper);
106
107       * To set a limit on the size of nets processed or returned by
108       NetAddr::IP.
109
110       Set the maximum number of nets beyond which NetAddr::IP will return an
111       error as a power of 2 (default 16 or 65536 nets). Each 2**16 consumes
112       approximately 4 megs of memory. A 2**20 consumes 64 megs of memory, A
113       2**24 consumes 1 gigabyte of memory.
114
115         use NetAddr::IP qw(netlimit);
116         netlimit 20;
117
118       The maximum netlimit allowed is 2**24. Attempts to set limits below the
119       default of 16 or above the maximum of 24 are ignored.
120
121       Returns true on success, otherwise "undef".
122

INSTALLATION

124       Un-tar the distribution in an appropriate directory and type:
125
126               perl Makefile.PL
127               make
128               make test
129               make install
130
131       NetAddr::IP depends on NetAddr::IP::Util which installs by default with
132       its primary functions compiled using Perl's XS extensions to build a C
133       library. If you do not have a C complier available or would like the
134       slower Pure Perl version for some other reason, then type:
135
136               perl Makefile.PL -noxs
137               make
138               make test
139               make install
140

DESCRIPTION

142       This module provides an object-oriented abstraction on top of IP
143       addresses or IP subnets that allows for easy manipulations.  Version
144       4.xx of NetAddr::IP will work with older versions of Perl and is
145       compatible with Math::BigInt.
146
147       The internal representation of all IP objects is in 128 bit IPv6
148       notation.  IPv4 and IPv6 objects may be freely mixed.
149
150   Overloaded Operators
151       Many operators have been overloaded, as described below:
152
153       Assignment ("=")
154           Has been optimized to copy one NetAddr::IP object to another very
155           quickly.
156
157       "->copy()"
158           The assignment ("=") operation is only put in to operation when the
159           copied object is further mutated by another overloaded operation.
160           See overload SPECIAL SYMBOLS FOR "use overload" for details.
161
162           "->copy()" actually creates a new object when called.
163
164       Stringification
165           An object can be used just as a string. For instance, the following
166           code
167
168                   my $ip = new NetAddr::IP '192.168.1.123';
169                   print "$ip\n";
170
171           Will print the string 192.168.1.123/32.
172
173       Equality
174           You can test for equality with either "eq" or "==". "eq" allows
175           comparison with arbitrary strings as well as NetAddr::IP objects.
176           The following example:
177
178               if (NetAddr::IP->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')
179                  { print "Yes\n"; }
180
181           will print out "Yes".
182
183           Comparison with "==" requires both operands to be NetAddr::IP
184           objects.
185
186           In both cases, a true value is returned if the CIDR representation
187           of the operands is equal.
188
189       Comparison via >, <, >=, <=, <=> and "cmp"
190           Internally, all network objects are represented in 128 bit format.
191           The numeric representation of the network is compared through the
192           corresponding operation. Comparisons are tried first on the address
193           portion of the object and if that is equal then the NUMERIC cidr
194           portion of the masks are compared. This leads to the
195           counterintuitive result that
196
197                   /24 > /16
198
199           Comparison should not be done on netaddr objects with different
200           CIDR as this may produce indeterminate - unexpected results, rather
201           the determination of which netblock is larger or smaller should be
202           done by comparing
203
204                   $ip1->masklen <=> $ip2->masklen
205
206       Addition of a constant ("+")
207           Add a 32 bit signed constant to the address part of a NetAddr
208           object.  This operation changes the address part to point so many
209           hosts above the current objects start address. For instance, this
210           code:
211
212               print NetAddr::IP->new('127.0.0.1/8') + 5;
213
214           will output 127.0.0.6/8. The address will wrap around at the
215           broadcast back to the network address. This code:
216
217               print NetAddr::IP->new('10.0.0.1/24') + 255;
218
219               outputs 10.0.0.0/24.
220
221           Returns the the unchanged object when the constant is missing or
222           out of range.
223
224               2147483647 <= constant >= -2147483648
225
226       Subtraction of a constant ("-")
227           The complement of the addition of a constant.
228
229       Difference ("-")
230           Returns the difference between the address parts of two NetAddr::IP
231           objects address parts as a 32 bit signed number.
232
233           Returns undef if the difference is out of range.
234
235           (See range restrictions on Addition above)
236
237       Auto-increment
238           Auto-incrementing a NetAddr::IP object causes the address part to
239           be adjusted to the next host address within the subnet. It will
240           wrap at the broadcast address and start again from the network
241           address.
242
243       Auto-decrement
244           Auto-decrementing a NetAddr::IP object performs exactly the
245           opposite of auto-incrementing it, as you would expect.
246
247   Serializing and Deserializing
248       This module defines hooks to collaborate with Storable for serializing
249       "NetAddr::IP" objects, through compact and human readable strings. You
250       can revert to the old format by invoking this module as
251
252         use NetAddr::IP ':old_storable';
253
254       You must do this if you have legacy data files containing NetAddr::IP
255       objects stored using the Storable module.
256
257   Methods
258       "->new([$addr, [ $mask|IPv6 ]])"
259       "->new6([$addr, [ $mask]])"
260       "->new_no([$addr, [ $mask]])"
261       "->new_from_aton($netaddr)"
262       new_cis and new_cis6 are DEPRECATED
263       "->new_cis("$addr $mask)"
264       "->new_cis6("$addr $mask)"
265           The first two methods create a new address with the supplied
266           address in $addr and an optional netmask $mask, which can be
267           omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses
268           respectively.
269
270           The third method "new_no" is exclusively for IPv4 addresses and
271           filters improperly formatted dot quad strings for leading 0's that
272           would normally be interpreted as octal format by NetAddr per the
273           specifications for inet_aton.
274
275           new_from_aton takes a packed IPv4 address and assumes a /32 mask.
276           This function replaces the DEPRECATED :aton functionality which is
277           fundamentally broken.
278
279           The last two methods new_cis and new_cis6 differ from new and new6
280           only in that they except the common Cisco address notation for
281           address/mask pairs with a space as a separator instead of a slash
282           (/)
283
284           These methods are DEPRECATED because the functionality is now
285           included in the other "new" methods
286
287             i.e.  ->new_cis('1.2.3.0 24')
288                   or
289                   ->new_cis6('::1.2.3.0 120')
290
291           "->new6" and "->new_cis6" mark the address as being in ipV6 address
292           space even if the format would suggest otherwise.
293
294             i.e.  ->new6('1.2.3.4') will result in ::102:304
295
296             addresses submitted to ->new in ipV6 notation will
297             remain in that notation permanently. i.e.
298                   ->new('::1.2.3.4') will result in ::102:304
299             whereas new('1.2.3.4') would print out as 1.2.3.4
300
301             See "STRINGIFICATION" below.
302
303           $addr can be almost anything that can be resolved to an IP address
304           in all the notations I have seen over time. It can optionally
305           contain the mask in CIDR notation.
306
307           prefix notation is understood, with the limitation that the range
308           specified by the prefix must match with a valid subnet.
309
310           Addresses in the same format returned by "inet_aton" or
311           "gethostbyname" can also be understood, although no mask can be
312           specified for them. The default is to not attempt to recognize this
313           format, as it seems to be seldom used.
314
315           To accept addresses in that format, invoke the module as in
316
317             use NetAddr::IP ':aton'
318
319           If called with no arguments, 'default' is assumed.
320
321           If called with an empty string as the argument, returns 'undef'
322
323           $addr can be any of the following and possibly more...
324
325             n.n
326             n.n/mm
327             n.n.n
328             n.n.n/mm
329             n.n.n.n
330             n.n.n.n/mm            32 bit cidr notation
331             n.n.n.n/m.m.m.m
332             loopback, localhost, broadcast, any, default
333             x.x.x.x/host
334             0xABCDEF, 0b111111000101011110, (a bcd number)
335             a netaddr as returned by 'inet_aton'
336
337           Any RFC1884 notation
338
339             ::n.n.n.n
340             ::n.n.n.n/mmm         128 bit cidr notation
341             ::n.n.n.n/::m.m.m.m
342             ::x:x
343             ::x:x/mmm
344             x:x:x:x:x:x:x:x
345             x:x:x:x:x:x:x:x/mmm
346             x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation
347             loopback, localhost, unspecified, any, default
348             ::x:x/host
349             0xABCDEF, 0b111111000101011110 within the limits
350             of perl's number resolution
351             123456789012  a 'big' bcd number (bigger than perl likes)
352             and Math::BigInt
353
354           A Fully Qualified Domain Name which returns an ipV4 address or an
355           ipV6 address, embodied in that order. This previously undocumented
356           feature may be disabled with:
357
358                   use NetAddr::IP::Lite ':nofqdn';
359
360           If called with no arguments, 'default' is assumed.
361
362           If called with an empty string as the argument, returns 'undef'
363
364       "->broadcast()"
365           Returns a new object referring to the broadcast address of a given
366           subnet. The broadcast address has all ones in all the bit positions
367           where the netmask has zero bits. This is normally used to address
368           all the hosts in a given subnet.
369
370       "->network()"
371           Returns a new object referring to the network address of a given
372           subnet. A network address has all zero bits where the bits of the
373           netmask are zero. Normally this is used to refer to a subnet.
374
375       "->addr()"
376           Returns a scalar with the address part of the object as an IPv4 or
377           IPv6 text string as appropriate. This is useful for printing or for
378           passing the address part of the NetAddr::IP object to other
379           components that expect an IP address. If the object is an ipV6
380           address or was created using ->new6($ip) it will be reported in
381           ipV6 hex format otherwise it will be reported in dot quad format
382           only if it resides in ipV4 address space.
383
384       "->mask()"
385           Returns a scalar with the mask as an IPv4 or IPv6 text string as
386           described above.
387
388       "->masklen()"
389           Returns a scalar the number of one bits in the mask.
390
391       "->bits()"
392           Returns the width of the address in bits. Normally 32 for v4 and
393           128 for v6.
394
395       "->version()"
396           Returns the version of the address or subnet. Currently this can be
397           either 4 or 6.
398
399       "->cidr()"
400           Returns a scalar with the address and mask in CIDR notation. A
401           NetAddr::IP object stringifies to the result of this function.
402           (see comments about ->new6() and ->addr() for output formats)
403
404       "->aton()"
405           Returns the address part of the NetAddr::IP object in the same
406           format as the inet_aton() or "ipv6_aton" function respectively. If
407           the object was created using ->new6($ip), the address returned will
408           always be in ipV6 format, even for addresses in ipV4 address space.
409
410       "->range()"
411           Returns a scalar with the base address and the broadcast address
412           separated by a dash and spaces. This is called range notation.
413
414       "->prefix()"
415           Returns a scalar with the address and mask in ipV4 prefix
416           representation. This is useful for some programs, which expect its
417           input to be in this format. This method will include the broadcast
418           address in the encoding.
419
420       "->nprefix()"
421           Just as "->prefix()", but does not include the broadcast address.
422
423       "->numeric()"
424           When called in a scalar context, will return a numeric
425           representation of the address part of the IP address. When called
426           in an array contest, it returns a list of two elements. The first
427           element is as described, the second element is the numeric
428           representation of the netmask.
429
430           This method is essential for serializing the representation of a
431           subnet.
432
433       "->bigint()"
434           When called in scalar context, will return a Math::BigInt
435           representation of the address part of the IP address. When called
436           in an array context, it returns a list of two elements, The first
437           element is as described, the second element is the Math::BigInt
438           representation of the netmask.
439
440       "->wildcard()"
441           When called in a scalar context, returns the wildcard bits
442           corresponding to the mask, in dotted-quad or ipV6 format as
443           applicable.
444
445           When called in an array context, returns a two-element array. The
446           first element, is the address part. The second element, is the
447           wildcard translation of the mask.
448
449       "->short()"
450           Returns the address part in a short or compact notation.
451
452             (ie, 127.0.0.1 becomes 127.1).
453
454           Works with both, V4 and V6.
455
456       "->canon()"
457           Returns the address part in canonical notation as a string.  For
458           ipV4, this is dotted quad, and is the same as the return value from
459           "->addr()".  For ipV6 it is as per RFC5952, and is the same as the
460           LOWER CASE value returned by "->short()".
461
462       "->full()"
463           Returns the address part in FULL notation for ipV4 and ipV6
464           respectively.
465
466             i.e. for ipV4
467               0000:0000:0000:0000:0000:0000:127.0.0.1
468
469                  for ipV6
470               0000:0000:0000:0000:0000:0000:0000:0000
471
472           To force ipV4 addresses into full ipV6 format use:
473
474       "->full6()"
475           Returns the address part in FULL ipV6 notation
476
477       "->full6m()"
478           Returns the mask part in FULL ipV6 notation
479
480       "$me->contains($other)"
481           Returns true when $me completely contains $other. False is returned
482           otherwise and "undef" is returned if $me and $other are not both
483           "NetAddr::IP" objects.
484
485       "$me->within($other)"
486           The complement of "->contains()". Returns true when $me is
487           completely contained within $other.
488
489           Note that $me and $other must be "NetAddr::IP" objects.
490
491       C->is_rfc1918()>
492           Returns true when $me is an RFC 1918 address.
493
494             10.0.0.0      -   10.255.255.255  (10/8 prefix)
495             172.16.0.0    -   172.31.255.255  (172.16/12 prefix)
496             192.168.0.0   -   192.168.255.255 (192.168/16 prefix)
497
498       "->is_local()"
499           Returns true when $me is a local network address.
500
501                   i.e.    ipV4    127.0.0.0 - 127.255.255.255
502             or            ipV6    === ::1
503
504       "->splitref($bits,[optional $bits1,$bits2,...])"
505           Returns a reference to a list of objects, representing subnets of
506           "bits" mask produced by splitting the original object, which is
507           left unchanged. Note that $bits must be longer than the original
508           mask in order for it to be splittable.
509
510           ERROR conditions:
511
512             ->splitref 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
516             ->splitref returns undef when C<bits> or the (bits list)
517               will not fit within the original object.
518
519             ->splitref returns undef if a supplied ipV4, ipV6, or NetAddr
520               mask in inappropriately formatted,
521
522           bits may be a CIDR mask, a dot quad or ipV6 string or a NetAddr::IP
523           object.  If "bits" is missing, the object is split for into all
524           available addresses within the ipV4 or ipV6 object ( auto-mask of
525           CIDR 32, 128 respectively ).
526
527           With optional additional "bits" list, the original object is split
528           into parts sized based on the list. NOTE: a short list will
529           replicate the last item. If the last item is too large to for what
530           remains of the object after splitting off the first parts of the
531           list, a "best fits" list of remaining objects will be returned
532           based on an increasing sort of the CIDR values of the "bits" list.
533
534             i.e.  my $ip = new NetAddr::IP('192.168.0.0/24');
535                   my $objptr = $ip->split(28, 29, 28, 29, 26);
536
537              has split plan 28 29 28 29 26 26 26 28
538              and returns this list of objects
539
540                   192.168.0.0/28
541                   192.168.0.16/29
542                   192.168.0.24/28
543                   192.168.0.40/29
544                   192.168.0.48/26
545                   192.168.0.112/26
546                   192.168.0.176/26
547                   192.168.0.240/28
548
549           NOTE: that /26 replicates twice beyond the original request and /28
550           fills the remaining return object requirement.
551
552       "->rsplitref($bits,[optional $bits1,$bits2,...])"
553           "->rsplitref" is the same as "->splitref" above except that the
554           split plan is applied to the original object in reverse order.
555
556             i.e.  my $ip = new NetAddr::IP('192.168.0.0/24');
557                   my @objects = $ip->split(28, 29, 28, 29, 26);
558
559              has split plan 28 26 26 26 29 28 29 28
560              and returns this list of objects
561
562                   192.168.0.0/28
563                   192.168.0.16/26
564                   192.168.0.80/26
565                   192.168.0.144/26
566                   192.168.0.208/29
567                   192.168.0.216/28
568                   192.168.0.232/29
569                   192.168.0.240/28
570
571       "->split($bits,[optional $bits1,$bits2,...])"
572           Similar to "->splitref" above but returns the list rather than a
573           list reference. You may not want to use this if a large number of
574           objects is expected.
575
576       "->rsplit($bits,[optional $bits1,$bits2,...])"
577           Similar to "->rsplitref" above but returns the list rather than a
578           list reference. You may not want to use this if a large number of
579           objects is expected.
580
581       "->hostenum()"
582           Returns the list of hosts within a subnet.
583
584           ERROR conditions:
585
586             ->hostenum will DIE with the message 'netlimit exceeded'
587               if the number of return objects exceeds 'netlimit'.
588               See function 'netlimit' above (default 2**16 or 65536 nets).
589
590       "->hostenumref()"
591           Faster version of "->hostenum()", returning a reference to a list.
592
593           NOTE: hostenum and hostenumref report zero (0) useable hosts in a
594           /31 network. This is the behavior expected prior to RFC 3021. To
595           report 2 useable hosts for use in point-to-point networks, use
596           :rfc3021 tag.
597
598                   use NetAddr::IP qw(:rfc3021);
599
600           This will cause hostenum and hostenumref to return two (2) useable
601           hosts in a /31 network.
602
603       "$me->compact($addr1, $addr2, ...)"
604       "@compacted_object_list = Compact(@object_list)"
605           Given a list of objects (including $me), this method will compact
606           all the addresses and subnets into the largest (ie, least specific)
607           subnets possible that contain exactly all of the given objects.
608
609           Note that in versions prior to 3.02, if fed with the same IP
610           subnets multiple times, these subnets would be returned. From 3.02
611           on, a more "correct" approach has been adopted and only one address
612           would be returned.
613
614           Note that $me and all $addr's must be "NetAddr::IP" objects.
615
616       "$me->compactref(\@list)"
617       "$compacted_object_list = Compact(\@list)"
618           As usual, a faster version of "->compact()" that returns a
619           reference to a list. Note that this method takes a reference to a
620           list instead.
621
622           Note that $me must be a "NetAddr::IP" object.
623
624       "$me->coalesce($masklen, $number, @list_of_subnets)"
625       "$arrayref = Coalesce($masklen,$number,@list_of_subnets)"
626           Will return a reference to list of "NetAddr::IP" subnets of
627           $masklen mask length, when $number or more addresses from
628           @list_of_subnets are found to be contained in said subnet.
629
630           Subnets from @list_of_subnets with a mask shorter than $masklen are
631           passed "as is" to the return list.
632
633           Subnets from @list_of_subnets with a mask longer than $masklen will
634           be counted (actually, the number of IP addresses is counted)
635           towards $number.
636
637           Called as a method, the array will include $me.
638
639           WARNING: the list of subnet must be the same type. i.e ipV4 or ipV6
640
641       "->first()"
642           Returns a new object representing the first usable IP address
643           within the subnet (ie, the first host address).
644
645       "->last()"
646           Returns a new object representing the last usable IP address within
647           the subnet (ie, one less than the broadcast address).
648
649       "->nth($index)"
650           Returns a new object representing the n-th usable IP address within
651           the subnet (ie, the n-th host address).  If no address is available
652           (for example, when the network is too small for $index hosts),
653           "undef" is returned.
654
655           Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
656           implements "->nth($index)" and "->num()" exactly as the
657           documentation states.  Previous versions behaved slightly
658           differently and not in a consistent manner. See the README file for
659           details.
660
661           To use the old behavior for "->nth($index)" and "->num()":
662
663             use NetAddr::IP::Lite qw(:old_nth);
664
665             old behavior:
666             NetAddr::IP->new('10/32')->nth(0) == undef
667             NetAddr::IP->new('10/32')->nth(1) == undef
668             NetAddr::IP->new('10/31')->nth(0) == undef
669             NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31
670             NetAddr::IP->new('10/30')->nth(0) == undef
671             NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30
672             NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30
673             NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30
674
675           Note that in each case, the broadcast address is represented in the
676           output set and that the 'zero'th index is alway undef except for a
677           point-to-point /31 or /127 network where there are exactly two
678           addresses in the network.
679
680             new behavior:
681             NetAddr::IP->new('10/32')->nth(0)  == 10.0.0.0/32
682             NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32
683             NetAddr::IP->new('10/31')->nth(0)  == 10.0.0.0/31
684             NetAddr::IP->new('10/31')->nth(1)  == 10.0.0.1/31
685             NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30
686             NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30
687             NetAddr::IP->new('10/30')->nth(2) == undef
688
689           Note that a /32 net always has 1 usable address while a /31 has
690           exactly two usable addresses for point-to-point addressing. The
691           first index (0) returns the address immediately following the
692           network address except for a /31 or /127 when it return the network
693           address.
694
695       "->num()"
696           As of version 4.42 of NetAddr::IP and version 1.27 of
697           NetAddr::IP::Lite a /31 and /127 with return a net num value of 2
698           instead of 0 (zero) for point-to-point networks.
699
700           Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
701           return the number of usable IP addresses within the subnet, not
702           counting the broadcast or network address.
703
704           Previous versions worked only for ipV4 addresses, returned a
705           maximum span of 2**32 and returned the number of IP addresses not
706           counting the broadcast address.
707                   (one greater than the new behavior)
708
709           To use the old behavior for "->nth($index)" and "->num()":
710
711             use NetAddr::IP::Lite qw(:old_nth);
712
713           WARNING:
714
715           NetAddr::IP will calculate and return a numeric string for network
716           ranges as large as 2**128. These values are TEXT strings and perl
717           can treat them as integers for numeric calculations.
718
719           Perl on 32 bit platforms only handles integer numbers up to 2**32
720           and on 64 bit platforms to 2**64.
721
722           If you wish to manipulate numeric strings returned by NetAddr::IP
723           that are larger than 2**32 or 2**64, respectively,  you must load
724           additional modules such as Math::BigInt, bignum or some similar
725           package to do the integer math.
726
727       "->re()"
728           Returns a Perl regular expression that will match an IP address
729           within the given subnet. Defaults to ipV4 notation. Will return an
730           ipV6 regex if the address in not in ipV4 space.
731
732       "->re6()"
733           Returns a Perl regular expression that will match an IP address
734           within the given subnet. Always returns an ipV6 regex.
735

EXPORT_OK

737               Compact
738               Coalesce
739               Zeros
740               Ones
741               V4mask
742               V4net
743               netlimit
744

NOTES / BUGS ... FEATURES

746       NetAddr::IP only runs in Pure Perl mode on Windows boxes because I
747       don't have the resources or know how to get the "configure" stuff
748       working in the Windows environment. Volunteers WELCOME to port the "C"
749       portion of this module to Windows.
750

HISTORY

752           See the Changes file
753

AUTHORS

755       Luis E. Muñoz <luismunoz@cpan.org>, Michael Robinton
756       <michael@bizsystems.com>
757

WARRANTY

759       This software comes with the same warranty as Perl itself (ie, none),
760       so by using it you accept any and all the liability.
761
763       This software is (c) Luis E. Muñoz, 1999 - 2007, and (c) Michael
764       Robinton, 2006 - 2014.
765
766       All rights reserved.
767
768       This program is free software; you can redistribute it and/or modify it
769       under the terms of either:
770
771         a) the GNU General Public License as published by the Free
772         Software Foundation; either version 2, or (at your option) any
773         later version, or
774
775         b) the "Artistic License" which comes with this distribution.
776
777       This program is distributed in the hope that it will be useful, but
778       WITHOUT ANY WARRANTY; without even the implied warranty of
779       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the
780       GNU General Public License or the Artistic License for more details.
781
782       You should have received a copy of the Artistic License with this
783       distribution, in the file named "Artistic".  If not, I'll be glad to
784       provide one.
785
786       You should also have received a copy of the GNU General Public License
787       along with this program in the file named "Copying". If not, write to
788       the
789
790               Free Software Foundation, Inc.
791               51 Franklin Street, Fifth Floor
792               Boston, MA 02110-1301 USA.
793
794       or visit their web page on the internet at:
795
796               http://www.gnu.org/copyleft/gpl.html.
797

SEE ALSO

799         perl(1) L<NetAddr::IP::Lite>, L<NetAddr::IP::Util>,
800       L<NetAddr::IP::InetBase>
801
802
803
804perl v5.36.0                      2023-01-20                             IP(3)
Impressum