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.
407           If the object was created using ->new6($ip), the address returned
408           will always be in ipV6 format, even for addresses in ipV4 address
409           space.
410
411       "->range()"
412           Returns a scalar with the base address and the broadcast address
413           separated by a dash and spaces. This is called range notation.
414
415       "->prefix()"
416           Returns a scalar with the address and mask in ipV4 prefix
417           representation. This is useful for some programs, which expect its
418           input to be in this format. This method will include the broadcast
419           address in the encoding.
420
421       "->nprefix()"
422           Just as "->prefix()", but does not include the broadcast address.
423
424       "->numeric()"
425           When called in a scalar context, will return a numeric
426           representation of the address part of the IP address. When called
427           in an array contest, it returns a list of two elements. The first
428           element is as described, the second element is the numeric
429           representation of the netmask.
430
431           This method is essential for serializing the representation of a
432           subnet.
433
434       "->bigint()"
435           When called in scalar context, will return a Math::BigInt
436           representation of the address part of the IP address. When called
437           in an array context, it returns a list of two elements, The first
438           element is as described, the second element is the Math::BigInt
439           representation of the netmask.
440
441       "->wildcard()"
442           When called in a scalar context, returns the wildcard bits
443           corresponding to the mask, in dotted-quad or ipV6 format as
444           applicable.
445
446           When called in an array context, returns a two-element array. The
447           first element, is the address part. The second element, is the
448           wildcard translation of the mask.
449
450       "->short()"
451           Returns the address part in a short or compact notation.
452
453             (ie, 127.0.0.1 becomes 127.1).
454
455           Works with both, V4 and V6.
456
457       "->canon()"
458           Returns the address part in canonical notation as a string.  For
459           ipV4, this is dotted quad, and is the same as the return value from
460           "->addr()".  For ipV6 it is as per RFC5952, and is the same as the
461           LOWER CASE value returned by "->short()".
462
463       "->full()"
464           Returns the address part in FULL notation for ipV4 and ipV6
465           respectively.
466
467             i.e. for ipV4
468               0000:0000:0000:0000:0000:0000:127.0.0.1
469
470                  for ipV6
471               0000:0000:0000:0000:0000:0000:0000:0000
472
473           To force ipV4 addresses into full ipV6 format use:
474
475       "->full6()"
476           Returns the address part in FULL ipV6 notation
477
478       "->full6m()"
479           Returns the mask part in FULL ipV6 notation
480
481       "$me->contains($other)"
482           Returns true when $me completely contains $other. False is returned
483           otherwise and "undef" is returned if $me and $other are not both
484           "NetAddr::IP" objects.
485
486       "$me->within($other)"
487           The complement of "->contains()". Returns true when $me is
488           completely contained within $other.
489
490           Note that $me and $other must be "NetAddr::IP" objects.
491
492       C->is_rfc1918()>
493           Returns true when $me is an RFC 1918 address.
494
495             10.0.0.0      -   10.255.255.255  (10/8 prefix)
496             172.16.0.0    -   172.31.255.255  (172.16/12 prefix)
497             192.168.0.0   -   192.168.255.255 (192.168/16 prefix)
498
499       "->is_local()"
500           Returns true when $me is a local network address.
501
502                   i.e.    ipV4    127.0.0.0 - 127.255.255.255
503             or            ipV6    === ::1
504
505       "->splitref($bits,[optional $bits1,$bits2,...])"
506           Returns a reference to a list of objects, representing subnets of
507           "bits" mask produced by splitting the original object, which is
508           left unchanged. Note that $bits must be longer than the original
509           mask in order for it to be splittable.
510
511           ERROR conditions:
512
513             ->splitref will DIE with the message 'netlimit exceeded'
514               if the number of return objects exceeds 'netlimit'.
515               See function 'netlimit' above (default 2**16 or 65536 nets).
516
517             ->splitref returns undef when C<bits> or the (bits list)
518               will not fit within the original object.
519
520             ->splitref returns undef if a supplied ipV4, ipV6, or NetAddr
521               mask in inappropriately formatted,
522
523           bits may be a CIDR mask, a dot quad or ipV6 string or a NetAddr::IP
524           object.  If "bits" is missing, the object is split for into all
525           available addresses within the ipV4 or ipV6 object ( auto-mask of
526           CIDR 32, 128 respectively ).
527
528           With optional additional "bits" list, the original object is split
529           into parts sized based on the list. NOTE: a short list will
530           replicate the last item. If the last item is too large to for what
531           remains of the object after splitting off the first parts of the
532           list, a "best fits" list of remaining objects will be returned
533           based on an increasing sort of the CIDR values of the "bits" list.
534
535             i.e.  my $ip = new NetAddr::IP('192.168.0.0/24');
536                   my $objptr = $ip->split(28, 29, 28, 29, 26);
537
538              has split plan 28 29 28 29 26 26 26 28
539              and returns this list of objects
540
541                   192.168.0.0/28
542                   192.168.0.16/29
543                   192.168.0.24/28
544                   192.168.0.40/29
545                   192.168.0.48/26
546                   192.168.0.112/26
547                   192.168.0.176/26
548                   192.168.0.240/28
549
550           NOTE: that /26 replicates twice beyond the original request and /28
551           fills the remaining return object requirement.
552
553       "->rsplitref($bits,[optional $bits1,$bits2,...])"
554           "->rsplitref" is the same as "->splitref" above except that the
555           split plan is applied to the original object in reverse order.
556
557             i.e.  my $ip = new NetAddr::IP('192.168.0.0/24');
558                   my @objects = $ip->split(28, 29, 28, 29, 26);
559
560              has split plan 28 26 26 26 29 28 29 28
561              and returns this list of objects
562
563                   192.168.0.0/28
564                   192.168.0.16/26
565                   192.168.0.80/26
566                   192.168.0.144/26
567                   192.168.0.208/29
568                   192.168.0.216/28
569                   192.168.0.232/29
570                   192.168.0.240/28
571
572       "->split($bits,[optional $bits1,$bits2,...])"
573           Similar to "->splitref" above but returns the list rather than a
574           list reference. You may not want to use this if a large number of
575           objects is expected.
576
577       "->rsplit($bits,[optional $bits1,$bits2,...])"
578           Similar to "->rsplitref" above but returns the list rather than a
579           list reference. You may not want to use this if a large number of
580           objects is expected.
581
582       "->hostenum()"
583           Returns the list of hosts within a subnet.
584
585           ERROR conditions:
586
587             ->hostenum will DIE with the message 'netlimit exceeded'
588               if the number of return objects exceeds 'netlimit'.
589               See function 'netlimit' above (default 2**16 or 65536 nets).
590
591       "->hostenumref()"
592           Faster version of "->hostenum()", returning a reference to a list.
593
594           NOTE: hostenum and hostenumref report zero (0) useable hosts in a
595           /31 network. This is the behavior expected prior to RFC 3021. To
596           report 2 useable hosts for use in point-to-point networks, use
597           :rfc3021 tag.
598
599                   use NetAddr::IP qw(:rfc3021);
600
601           This will cause hostenum and hostenumref to return two (2) useable
602           hosts in a /31 network.
603
604       "$me->compact($addr1, $addr2, ...)"
605       "@compacted_object_list = Compact(@object_list)"
606           Given a list of objects (including $me), this method will compact
607           all the addresses and subnets into the largest (ie, least specific)
608           subnets possible that contain exactly all of the given objects.
609
610           Note that in versions prior to 3.02, if fed with the same IP
611           subnets multiple times, these subnets would be returned. From 3.02
612           on, a more "correct" approach has been adopted and only one address
613           would be returned.
614
615           Note that $me and all $addr's must be "NetAddr::IP" objects.
616
617       "$me->compactref(\@list)"
618       "$compacted_object_list = Compact(\@list)"
619           As usual, a faster version of "->compact()" that returns a
620           reference to a list. Note that this method takes a reference to a
621           list instead.
622
623           Note that $me must be a "NetAddr::IP" object.
624
625       "$me->coalesce($masklen, $number, @list_of_subnets)"
626       "$arrayref = Coalesce($masklen,$number,@list_of_subnets)"
627           Will return a reference to list of "NetAddr::IP" subnets of
628           $masklen mask length, when $number or more addresses from
629           @list_of_subnets are found to be contained in said subnet.
630
631           Subnets from @list_of_subnets with a mask shorter than $masklen are
632           passed "as is" to the return list.
633
634           Subnets from @list_of_subnets with a mask longer than $masklen will
635           be counted (actually, the number of IP addresses is counted)
636           towards $number.
637
638           Called as a method, the array will include $me.
639
640           WARNING: the list of subnet must be the same type. i.e ipV4 or ipV6
641
642       "->first()"
643           Returns a new object representing the first usable IP address
644           within the subnet (ie, the first host address).
645
646       "->last()"
647           Returns a new object representing the last usable IP address within
648           the subnet (ie, one less than the broadcast address).
649
650       "->nth($index)"
651           Returns a new object representing the n-th usable IP address within
652           the subnet (ie, the n-th host address).  If no address is available
653           (for example, when the network is too small for $index hosts),
654           "undef" is returned.
655
656           Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
657           implements "->nth($index)" and "->num()" exactly as the
658           documentation states.  Previous versions behaved slightly
659           differently and not in a consistent manner. See the README file for
660           details.
661
662           To use the old behavior for "->nth($index)" and "->num()":
663
664             use NetAddr::IP::Lite qw(:old_nth);
665
666             old behavior:
667             NetAddr::IP->new('10/32')->nth(0) == undef
668             NetAddr::IP->new('10/32')->nth(1) == undef
669             NetAddr::IP->new('10/31')->nth(0) == undef
670             NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31
671             NetAddr::IP->new('10/30')->nth(0) == undef
672             NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30
673             NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30
674             NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30
675
676           Note that in each case, the broadcast address is represented in the
677           output set and that the 'zero'th index is alway undef except for a
678           point-to-point /31 or /127 network where there are exactly two
679           addresses in the network.
680
681             new behavior:
682             NetAddr::IP->new('10/32')->nth(0)  == 10.0.0.0/32
683             NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32
684             NetAddr::IP->new('10/31')->nth(0)  == 10.0.0.0/31
685             NetAddr::IP->new('10/31')->nth(1)  == 10.0.0.1/31
686             NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30
687             NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30
688             NetAddr::IP->new('10/30')->nth(2) == undef
689
690           Note that a /32 net always has 1 usable address while a /31 has
691           exactly two usable addresses for point-to-point addressing. The
692           first index (0) returns the address immediately following the
693           network address except for a /31 or /127 when it return the network
694           address.
695
696       "->num()"
697           As of version 4.42 of NetAddr::IP and version 1.27 of
698           NetAddr::IP::Lite a /31 and /127 with return a net num value of 2
699           instead of 0 (zero) for point-to-point networks.
700
701           Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
702           return the number of usable IP addresses within the subnet, not
703           counting the broadcast or network address.
704
705           Previous versions worked only for ipV4 addresses, returned a
706           maximum span of 2**32 and returned the number of IP addresses not
707           counting the broadcast address.
708                   (one greater than the new behavior)
709
710           To use the old behavior for "->nth($index)" and "->num()":
711
712             use NetAddr::IP::Lite qw(:old_nth);
713
714           WARNING:
715
716           NetAddr::IP will calculate and return a numeric string for network
717           ranges as large as 2**128. These values are TEXT strings and perl
718           can treat them as integers for numeric calculations.
719
720           Perl on 32 bit platforms only handles integer numbers up to 2**32
721           and on 64 bit platforms to 2**64.
722
723           If you wish to manipulate numeric strings returned by NetAddr::IP
724           that are larger than 2**32 or 2**64, respectively,  you must load
725           additional modules such as Math::BigInt, bignum or some similar
726           package to do the integer math.
727
728       "->re()"
729           Returns a Perl regular expression that will match an IP address
730           within the given subnet. Defaults to ipV4 notation. Will return an
731           ipV6 regex if the address in not in ipV4 space.
732
733       "->re6()"
734           Returns a Perl regular expression that will match an IP address
735           within the given subnet. Always returns an ipV6 regex.
736

EXPORT_OK

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

NOTES / BUGS ... FEATURES

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

HISTORY

753           See the Changes file
754

AUTHORS

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

WARRANTY

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

SEE ALSO

800         perl(1) L<NetAddr::IP::Lite>, L<NetAddr::IP::Util>,
801       L<NetAddr::IP::InetBase>
802
803
804
805perl v5.34.0                      2022-01-21                             IP(3)
Impressum