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

NAME

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

SYNOPSIS

9         use NetAddr::IP::Lite qw(
10               Zeros
11               Ones
12               V4mask
13               V4net
14               :aton           DEPRECATED !
15               :old_nth
16               :upper
17               :lower
18               :nofqdn
19         );
20
21         my $ip = new NetAddr::IP::Lite '127.0.0.1';
22               or if your prefer
23         my $ip = NetAddr::IP::Lite->new('127.0.0.1);
24               or from a packed IPv4 address
25         my $ip = new_from_aton NetAddr::IP::Lite (inet_aton('127.0.0.1'));
26               or from an octal filtered IPv4 address
27         my $ip = new_no NetAddr::IP::Lite '127.012.0.0';
28
29         print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;
30
31         if ($ip->within(new NetAddr::IP::Lite "127.0.0.0", "255.0.0.0")) {
32             print "Is a loopback address\n";
33         }
34
35                                       # This prints 127.0.0.1/32
36         print "You can also say $ip...\n";
37
38         The following four functions return ipV6 representations of:
39
40         ::                                       = Zeros();
41         FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF  = Ones();
42         FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::          = V4mask();
43         ::FFFF:FFFF                              = V4net();
44
45         Will also return an ipV4 or ipV6 representation of a
46         resolvable Fully Qualified Domanin Name (FQDN).
47

INSTALLATION

49       Un-tar the distribution in an appropriate directory and type:
50
51               perl Makefile.PL
52               make
53               make test
54               make install
55
56       NetAddr::IP::Lite depends on NetAddr::IP::Util which installs by
57       default with its primary functions compiled using Perl's XS extensions
58       to build a 'C' library. If you do not have a 'C' complier available or
59       would like the slower Pure Perl version for some other reason, then
60       type:
61
62               perl Makefile.PL -noxs
63               make
64               make test
65               make install
66

DESCRIPTION

68       This module provides an object-oriented abstraction on top of IP
69       addresses or IP subnets, that allows for easy manipulations. Most of
70       the operations of NetAddr::IP are supported. This module will work with
71       older versions of Perl and is compatible with Math::BigInt.
72
73       * By default NetAddr::IP functions and methods return string IPv6
74       addresses in uppercase.  To change that to lowercase:
75
76       NOTE: the AUGUST 2010 RFC5952 states:
77
78           4.3. Lowercase
79
80             The characters "a", "b", "c", "d", "e", and "f" in an IPv6
81             address MUST be represented in lowercase.
82
83       It is recommended that all NEW applications using NetAddr::IP::Lite be
84       invoked as shown on the next line.
85
86         use NetAddr::IP::Lite qw(:lower);
87
88       * To ensure the current IPv6 string case behavior even if the default
89       changes:
90
91         use NetAddr::IP::Lite qw(:upper);
92
93       The internal representation of all IP objects is in 128 bit IPv6
94       notation.  IPv4 and IPv6 objects may be freely mixed.
95
96       The supported operations are described below:
97
98   Overloaded Operators
99       Assignment ("=")
100           Has been optimized to copy one NetAddr::IP::Lite object to another
101           very quickly.
102
103       "->copy()"
104           The assignment ("=") operation is only put in to operation when the
105           copied object is further mutated by another overloaded operation.
106           See overload SPECIAL SYMBOLS FOR "use overload" for details.
107
108           "->copy()" actually creates a new object when called.
109
110       Stringification
111           An object can be used just as a string. For instance, the following
112           code
113
114                   my $ip = new NetAddr::IP::Lite '192.168.1.123';
115                   print "$ip\n";
116
117           Will print the string 192.168.1.123/32.
118
119                   my $ip = new6 NetAddr::IP::Lite '192.168.1.123';
120                   print "$ip\n";
121
122           Will print the string 0:0:0:0:0:0:C0A8:17B/128
123
124       Equality
125           You can test for equality with either "eq", "ne", "==" or "!=".
126           "eq", "ne" allows the comparison with arbitrary strings as well as
127           NetAddr::IP::Lite objects. The following example:
128
129               if (NetAddr::IP::Lite->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')
130                  { print "Yes\n"; }
131
132           Will print out "Yes".
133
134           Comparison with "==" and "!=" requires both operands to be
135           NetAddr::IP::Lite objects.
136
137       Comparison via >, <, >=, <=, <=> and "cmp"
138           Internally, all network objects are represented in 128 bit format.
139           The numeric representation of the network is compared through the
140           corresponding operation. Comparisons are tried first on the address
141           portion of the object and if that is equal then the NUMERIC cidr
142           portion of the masks are compared. This leads to the
143           counterintuitive result that
144
145                   /24 > /16
146
147           Comparison should not be done on netaddr objects with different
148           CIDR as this may produce indeterminate - unexpected results, rather
149           the determination of which netblock is larger or smaller should be
150           done by comparing
151
152                   $ip1->masklen <=> $ip2->masklen
153
154       Addition of a constant ("+")
155           Add a 32 bit signed constant to the address part of a NetAddr
156           object.  This operation changes the address part to point so many
157           hosts above the current objects start address. For instance, this
158           code:
159
160               print NetAddr::IP::Lite->new('127.0.0.1/8') + 5;
161
162           will output 127.0.0.6/8. The address will wrap around at the
163           broadcast back to the network address. This code:
164
165               print NetAddr::IP::Lite->new('10.0.0.1/24') + 255;
166
167           outputs 10.0.0.0/24.
168
169           Returns the the unchanged object when the constant is missing or
170           out of range.
171
172               2147483647 <= constant >= -2147483648
173
174       Subtraction of a constant ("-")
175           The complement of the addition of a constant.
176
177       Difference ("-")
178           Returns the difference between the address parts of two
179           NetAddr::IP::Lite objects address parts as a 32 bit signed number.
180
181           Returns undef if the difference is out of range.
182
183       Auto-increment
184           Auto-incrementing a NetAddr::IP::Lite object causes the address
185           part to be adjusted to the next host address within the subnet. It
186           will wrap at the broadcast address and start again from the network
187           address.
188
189       Auto-decrement
190           Auto-decrementing a NetAddr::IP::Lite object performs exactly the
191           opposite of auto-incrementing it, as you would expect.
192
193   Methods
194       "->new([$addr, [ $mask|IPv6 ]])"
195       "->new6([$addr, [ $mask]])"
196       "->new6FFFF([$addr, [ $mask]])"
197       "->new_no([$addr, [ $mask]])"
198       "->new_from_aton($netaddr)"
199       new_cis and new_cis6 are DEPRECATED
200       "->new_cis("$addr $mask)"
201       "->new_cis6("$addr $mask)"
202           The first three methods create a new address with the supplied
203           address in $addr and an optional netmask $mask, which can be
204           omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses
205           respectively.
206
207           new6FFFF specifically returns an IPv4 address in IPv6 format
208           according to RFC4291
209
210             new6               ::xxxx:xxxx
211             new6FFFF      ::FFFF:xxxx:xxxx
212
213           The third method "new_no" is exclusively for IPv4 addresses and
214           filters improperly formatted dot quad strings for leading 0's that
215           would normally be interpreted as octal format by NetAddr per the
216           specifications for inet_aton.
217
218           new_from_aton takes a packed IPv4 address and assumes a /32 mask.
219           This function replaces the DEPRECATED :aton functionality which is
220           fundamentally broken.
221
222           The last two methods new_cis and new_cis6 differ from new and new6
223           only in that they except the common Cisco address notation for
224           address/mask pairs with a space as a separator instead of a slash
225           (/)
226
227           These methods are DEPRECATED because the functionality is now
228           included in the other "new" methods
229
230             i.e.  ->new_cis('1.2.3.0 24')
231                   or
232                   ->new_cis6('::1.2.3.0 120')
233
234           "->new6" and "->new_cis6" mark the address as being in ipV6 address
235           space even if the format would suggest otherwise.
236
237             i.e.  ->new6('1.2.3.4') will result in ::102:304
238
239             addresses submitted to ->new in ipV6 notation will
240             remain in that notation permanently. i.e.
241                   ->new('::1.2.3.4') will result in ::102:304
242             whereas new('1.2.3.4') would print out as 1.2.3.4
243
244             See "STRINGIFICATION" below.
245
246           $addr can be almost anything that can be resolved to an IP address
247           in all the notations I have seen over time. It can optionally
248           contain the mask in CIDR notation. If the OPTIONAL perl module
249           Socket6 is available in the local library it will autoload and ipV6
250           host6 names will be resolved as well as ipV4 hostnames.
251
252           prefix notation is understood, with the limitation that the range
253           specified by the prefix must match with a valid subnet.
254
255           Addresses in the same format returned by "inet_aton" or
256           "gethostbyname" can also be understood, although no mask can be
257           specified for them. The default is to not attempt to recognize this
258           format, as it seems to be seldom used.
259
260           ###### DEPRECATED, will be remove in version 5 ############ To
261           accept addresses in that format, invoke the module as in
262
263             use NetAddr::IP::Lite ':aton'
264
265           ###### USE new_from_aton instead ##########################
266
267           If called with no arguments, 'default' is assumed.
268
269           If called with an empty string as the argument, returns 'undef'
270
271           $addr can be any of the following and possibly more...
272
273             n.n
274             n.n/mm
275             n.n mm
276             n.n.n
277             n.n.n/mm
278             n.n.n mm
279             n.n.n.n
280             n.n.n.n/mm            32 bit cidr notation
281             n.n.n.n mm
282             n.n.n.n/m.m.m.m
283             n.n.n.n m.m.m.m
284             loopback, localhost, broadcast, any, default
285             x.x.x.x/host
286             0xABCDEF, 0b111111000101011110, (or a bcd number)
287             a netaddr as returned by 'inet_aton'
288
289           Any RFC1884 notation
290
291             ::n.n.n.n
292             ::n.n.n.n/mmm         128 bit cidr notation
293             ::n.n.n.n/::m.m.m.m
294             ::x:x
295             ::x:x/mmm
296             x:x:x:x:x:x:x:x
297             x:x:x:x:x:x:x:x/mmm
298             x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation
299             loopback, localhost, unspecified, any, default
300             ::x:x/host
301             0xABCDEF, 0b111111000101011110 within the limits
302             of perl's number resolution
303             123456789012  a 'big' bcd number (bigger than perl likes)
304             and Math::BigInt
305
306           A Fully Qualified Domain Name which returns an ipV4 address or an
307           ipV6 address, embodied in that order. This previously undocumented
308           feature may be disabled with:
309
310                   use NetAddr::IP::Lite ':nofqdn';
311
312           If called with no arguments, 'default' is assumed.
313
314           If called with and empty string as the argument, 'undef' is
315           returned;
316
317       "->broadcast()"
318           Returns a new object referring to the broadcast address of a given
319           subnet. The broadcast address has all ones in all the bit positions
320           where the netmask has zero bits. This is normally used to address
321           all the hosts in a given subnet.
322
323       "->network()"
324           Returns a new object referring to the network address of a given
325           subnet. A network address has all zero bits where the bits of the
326           netmask are zero. Normally this is used to refer to a subnet.
327
328       "->addr()"
329           Returns a scalar with the address part of the object as an IPv4 or
330           IPv6 text string as appropriate. This is useful for printing or for
331           passing the address part of the NetAddr::IP::Lite object to other
332           components that expect an IP address. If the object is an ipV6
333           address or was created using ->new6($ip) it will be reported in
334           ipV6 hex format otherwise it will be reported in dot quad format
335           only if it resides in ipV4 address space.
336
337       "->mask()"
338           Returns a scalar with the mask as an IPv4 or IPv6 text string as
339           described above.
340
341       "->masklen()"
342           Returns a scalar the number of one bits in the mask.
343
344       "->bits()"
345           Returns the width of the address in bits. Normally 32 for v4 and
346           128 for v6.
347
348       "->version()"
349           Returns the version of the address or subnet. Currently this can be
350           either 4 or 6.
351
352       "->cidr()"
353           Returns a scalar with the address and mask in CIDR notation. A
354           NetAddr::IP::Lite object stringifies to the result of this
355           function.  (see comments about ->new6() and ->addr() for output
356           formats)
357
358       "->aton()"
359           Returns the address part of the NetAddr::IP::Lite object in the
360           same format as the "inet_aton()" or "ipv6_aton" function
361           respectively. If the object was created using ->new6($ip), the
362           address returned will always be in ipV6 format, even for addresses
363           in ipV4 address space.
364
365       "->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
369       "->numeric()"
370           When called in a scalar context, will return a numeric
371           representation of the address part of the IP address. When called
372           in an array context, it returns a list of two elements. The first
373           element is as described, the second element is the numeric
374           representation of the netmask.
375
376           This method is essential for serializing the representation of a
377           subnet.
378
379       "->bigint()"
380           When called in a scalar context, will return a Math::BigInt
381           representation of the address part of the IP address. When called
382           in an array contest, it returns a list of two elements. The first
383           element is as described, the second element is the Math::BigInt
384           representation of the netmask.
385
386       "$me->contains($other)"
387           Returns true when $me completely contains $other. False is returned
388           otherwise and "undef" is returned if $me and $other are not both
389           "NetAddr::IP::Lite" objects.
390
391       "$me->within($other)"
392           The complement of "->contains()". Returns true when $me is
393           completely contained within $other, undef if $me and $other are not
394           both "NetAddr::IP::Lite" objects.
395
396       C->is_rfc1918()>
397           Returns true when $me is an RFC 1918 address.
398
399                10.0.0.0        -   10.255.255.255  (10/8 prefix)
400                172.16.0.0      -   172.31.255.255  (172.16/12 prefix)
401                192.168.0.0     -   192.168.255.255 (192.168/16 prefix)
402
403       "->is_local()"
404           Returns true when $me is a local network address.
405
406                   i.e.    ipV4    127.0.0.0 - 127.255.255.255
407             or            ipV6    === ::1
408
409       "->first()"
410           Returns a new object representing the first usable IP address
411           within the subnet (ie, the first host address).
412
413       "->last()"
414           Returns a new object representing the last usable IP address within
415           the subnet (ie, one less than the broadcast address).
416
417       "->nth($index)"
418           Returns a new object representing the n-th usable IP address within
419           the subnet (ie, the n-th host address).  If no address is available
420           (for example, when the network is too small for $index hosts),
421           "undef" is returned.
422
423           Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
424           implements "->nth($index)" and "->num()" exactly as the
425           documentation states.  Previous versions behaved slightly
426           differently and not in a consistent manner.
427
428           To use the old behavior for "->nth($index)" and "->num()":
429
430             use NetAddr::IP::Lite qw(:old_nth);
431
432             old behavior:
433             NetAddr::IP->new('10/32')->nth(0) == undef
434             NetAddr::IP->new('10/32')->nth(1) == undef
435             NetAddr::IP->new('10/31')->nth(0) == undef
436             NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31
437             NetAddr::IP->new('10/30')->nth(0) == undef
438             NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30
439             NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30
440             NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30
441
442           Note that in each case, the broadcast address is represented in the
443           output set and that the 'zero'th index is alway undef except for a
444           point-to-point /31 or /127 network where there are exactly two
445           addresses in the network.
446
447             new behavior:
448             NetAddr::IP->new('10/32')->nth(0)  == 10.0.0.0/32
449             NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32
450             NetAddr::IP->new('10/31')->nth(0)  == 10.0.0.0/32
451             NetAddr::IP->new('10/31')->nth(1)  == 10.0.0.1/32
452             NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30
453             NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30
454             NetAddr::IP->new('10/30')->nth(2) == undef
455
456           Note that a /32 net always has 1 usable address while a /31 has
457           exactly two usable addresses for point-to-point addressing. The
458           first index (0) returns the address immediately following the
459           network address except for a /31 or /127 when it return the network
460           address.
461
462       "->num()"
463           As of version 4.42 of NetAddr::IP and version 1.27 of
464           NetAddr::IP::Lite a /31 and /127 with return a net num value of 2
465           instead of 0 (zero) for point-to-point networks.
466
467           Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
468           return the number of usable IP addresses within the subnet, not
469           counting the broadcast or network address.
470
471           Previous versions worked only for ipV4 addresses, returned a
472           maximum span of 2**32 and returned the number of IP addresses not
473           counting the broadcast address.       (one greater than the new
474           behavior)
475
476           To use the old behavior for "->nth($index)" and "->num()":
477
478             use NetAddr::IP::Lite qw(:old_nth);
479
480           WARNING:
481
482           NetAddr::IP will calculate and return a numeric string for network
483           ranges as large as 2**128. These values are TEXT strings and perl
484           can treat them as integers for numeric calculations.
485
486           Perl on 32 bit platforms only handles integer numbers up to 2**32
487           and on 64 bit platforms to 2**64.
488
489           If you wish to manipulate numeric strings returned by NetAddr::IP
490           that are larger than 2**32 or 2**64, respectively,  you must load
491           additional modules such as Math::BigInt, bignum or some similar
492           package to do the integer math.
493

EXPORT_OK

495               Zeros
496               Ones
497               V4mask
498               V4net
499               :aton           DEPRECATED
500               :old_nth
501               :upper
502               :lower
503               :nofqdn
504

AUTHORS

506       Luis E. Muñoz <luismunoz@cpan.org>, Michael Robinton
507       <michael@bizsystems.com>
508

WARRANTY

510       This software comes with the  same warranty as perl itself (ie, none),
511       so by using it you accept any and all the liability.
512
514        This software is (c) Luis E. Muñoz, 1999 - 2005
515        and (c) Michael Robinton, 2006 - 2014.
516
517       All rights reserved.
518
519       This program is free software; you can redistribute it and/or modify it
520       under the terms of either:
521
522         a) the GNU General Public License as published by the Free
523         Software Foundation; either version 2, or (at your option) any
524         later version, or
525
526         b) the "Artistic License" which comes with this distribution.
527
528       This program is distributed in the hope that it will be useful, but
529       WITHOUT ANY WARRANTY; without even the implied warranty of
530       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the
531       GNU General Public License or the Artistic License for more details.
532
533       You should have received a copy of the Artistic License with this
534       distribution, in the file named "Artistic".  If not, I'll be glad to
535       provide one.
536
537       You should also have received a copy of the GNU General Public License
538       along with this program in the file named "Copying". If not, write to
539       the
540
541               Free Software Foundation, Inc.,
542               51 Franklin Street, Fifth Floor
543               Boston, MA 02110-1301 USA
544
545       or visit their web page on the internet at:
546
547               http://www.gnu.org/copyleft/gpl.html.
548

SEE ALSO

550       NetAddr::IP(3), NetAddr::IP::Util(3), NetAddr::IP::InetBase(3)
551
552
553
554perl v5.36.0                      2022-07-22                           Lite(3)
Impressum