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