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