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
11 :old_nth
12 );
13
14 my $ip = new NetAddr::IP::Lite '127.0.0.1';
15
16 print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;
17
18 if ($ip->within(new NetAddr::IP::Lite "127.0.0.0", "255.0.0.0")) {
19 print "Is a loopback address\n";
20 }
21
22 # This prints 127.0.0.1/32
23 print "You can also say $ip...\n";
24
25 The following four functions return ipV6 representations of:
26
27 :: = Zeros();
28 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF: = Ones();
29 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask();
30 ::FFFF:FFFF = V4net();
31
32INSTALLATION
33 Un-tar the distribution in an appropriate directory and type:
34
35 perl Makefile.PL
36 make
37 make test
38 make install
39
40 NetAddr::IP::Lite depends on NetAddr::IP::Util which installs by default
41 with its primary functions compiled using Perl's XS extensions to build
42 a 'C' library. If you do not have a 'C' complier available or would like
43 the slower Pure Perl version for some other reason, then type:
44
45 perl Makefile.PL -noxs
46 make
47 make test
48 make install
49
50DESCRIPTION
51 This module provides an object-oriented abstraction on top of IP
52 addresses or IP subnets, that allows for easy manipulations. Most of the
53 operations of NetAddr::IP are supported. This module will work older
54 versions of Perl and does not use Math::BigInt.
55
56 The internal representation of all IP objects is in 128 bit IPv6
57 notation. IPv4 and IPv6 objects may be freely mixed.
58
59 The supported operations are described below:
60
61 Overloaded Operators
62
63 Assignment ("=")
64 Has been optimized to copy one NetAddr::IP::Lite object to another
65 very quickly.
66
67 "->copy()"
68 The assignment ("=") operation is only put in to operation when the
69 copied object is further mutated by another overloaded operation.
70 See the overload manpage SPECIAL SYMBOLS FOR "use overload" for
71 details.
72
73 "->copy()" actually creates a new object when called.
74
75 Stringification
76 An object can be used just as a string. For instance, the following
77 code
78
79 my $ip = new NetAddr::IP::Lite '192.168.1.123';
80 print "$ip\n";
81
82 Will print the string 192.168.1.123/32.
83
84 my $ip = new6 NetAddr::IP::Lite '192.168.1.123';
85 print "$ip\n";
86
87 Will print the string
88
89 Equality
90 You can test for equality with either "eq" or "==". "eq" allows the
91 comparison with arbitrary strings as well as NetAddr::IP::Lite
92 objects. The following example:
93
94 if (NetAddr::IP::Lite->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')
95 { print "Yes\n"; }
96
97 Will print out "Yes".
98
99 Comparison with "==" requires both operands to be NetAddr::IP::Lite
100 objects.
101
102 In both cases, a true value is returned if the CIDR representation
103 of the operands is equal.
104
105 Comparison via >, <, >=, <=, <=> and "cmp"
106 Internally, all network objects are represented in 128 bit format.
107 The numeric representation of the network is compared through the
108 corresponding operation. Comparisons are tried first on the address
109 portion of the object and if that is equal then the cidr portion of
110 the masks are compared.
111
112 Addition of a constant
113 Adding a constant to a NetAddr::IP::Lite object changes its address
114 part to point to the one so many hosts above the start address. For
115 instance, this code:
116
117 print NetAddr::IP::Lite->new('127.0.0.1') + 5;
118
119 will output 127.0.0.6/8. The address will wrap around at the
120 broadcast back to the network address. This code:
121
122 print NetAddr::IP::Lite->new('10.0.0.1/24') + 255;
123
124 outputs 10.0.0.0/24.
125
126 Substraction of a constant
127 The complement of the addition of a constant.
128
129 Auto-increment
130 Auto-incrementing a NetAddr::IP::Lite object causes the address part
131 to be adjusted to the next host address within the subnet. It will
132 wrap at the broadcast address and start again from the network
133 address.
134
135 Auto-decrement
136 Auto-decrementing a NetAddr::IP::Lite object performs exactly the
137 opposite of auto-incrementing it, as you would expect.
138
139 Methods
140
141 "->new([$addr, [ $mask|IPv6 ]])"
142 "->new6([$addr, [ $mask]])"
143 These methods creates a new address with the supplied address in
144 "$addr" and an optional netmask "$mask", which can be omitted to get
145 a /32 or /128 netmask for IPv4 / IPv6 addresses respectively
146
147 "->new6" marks the address as being in ipV6 address space even if
148 the format would suggest otherwise.
149
150 i.e. ->new6('1.2.3.4') will result in ::102:304
151
152 addresses submitted to ->new in ipV6 notation will
153 remain in that notation permanently. i.e.
154 ->new('::1.2.3.4') will result in ::102:304
155 whereas new('1.2.3.4') would print out as 1.2.3.4
156
157 See "STRINGIFICATION" below.
158
159 "$addr" can be almost anything that can be resolved to an IP address
160 in all the notations I have seen over time. It can optionally
161 contain the mask in CIDR notation.
162
163 prefix notation is understood, with the limitation that the range
164 speficied by the prefix must match with a valid subnet.
165
166 Addresses in the same format returned by "inet_aton" or
167 "gethostbyname" can also be understood, although no mask can be
168 specified for them. The default is to not attempt to recognize this
169 format, as it seems to be seldom used.
170
171 To accept addresses in that format, invoke the module as in
172
173 use NetAddr::IP::Lite ':aton'
174
175 If called with no arguments, 'default' is assumed.
176
177 "$addr" can be any of the following and possibly more...
178
179 n.n
180 n.n/mm
181 n.n.n
182 n.n.n/mm
183 n.n.n.n
184 n.n.n.n/mm 32 bit cidr notation
185 n.n.n.n/m.m.m.m
186 loopback, localhost, broadcast, any, default
187 x.x.x.x/host
188 0xABCDEF, 0b111111000101011110, (a bcd number)
189 a netaddr as returned by 'inet_aton'
190
191 Any RFC1884 notation
192
193 ::n.n.n.n
194 ::n.n.n.n/mmm 128 bit cidr notation
195 ::n.n.n.n/::m.m.m.m
196 ::x:x
197 ::x:x/mmm
198 x:x:x:x:x:x:x:x
199 x:x:x:x:x:x:x:x/mmm
200 x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation
201 loopback, localhost, unspecified, any, default
202 ::x:x/host
203 0xABCDEF, 0b111111000101011110 within the limits
204 of perl's number resolution
205 123456789012 a 'big' bcd number i.e. Math::BigInt
206
207 If called with no arguments, 'default' is assumed.
208
209 "->broadcast()"
210 Returns a new object refering to the broadcast address of a given
211 subnet. The broadcast address has all ones in all the bit positions
212 where the netmask has zero bits. This is normally used to address
213 all the hosts in a given subnet.
214
215 "->network()"
216 Returns a new object refering to the network address of a given
217 subnet. A network address has all zero bits where the bits of the
218 netmask are zero. Normally this is used to refer to a subnet.
219
220 "->addr()"
221 Returns a scalar with the address part of the object as an IPv4 or
222 IPv6 text string as appropriate. This is useful for printing or for
223 passing the address part of the NetAddr::IP::Lite object to other
224 components that expect an IP address. If the object is an ipV6
225 address or was created using ->new6($ip) it will be reported in ipV6
226 hex format otherwise it will be reported in dot quad format only if
227 it resides in ipV4 address space.
228
229 "->mask()"
230 Returns a scalar with the mask as an IPv4 or IPv6 text string as
231 described above.
232
233 "->masklen()"
234 Returns a scalar the number of one bits in the mask.
235
236 "->bits()"
237 Returns the width of the address in bits. Normally 32 for v4 and 128
238 for v6.
239
240 "->version()"
241 Returns the version of the address or subnet. Currently this can be
242 either 4 or 6.
243
244 "->cidr()"
245 Returns a scalar with the address and mask in CIDR notation. A
246 NetAddr::IP::Lite object *stringifies* to the result of this
247 function. (see comments about ->new6() and ->addr() for output
248 formats)
249
250 "->aton()"
251 Returns the address part of the NetAddr::IP::Lite object in the same
252 format as the "inet_aton()" or "ipv6_aton" function respectively. If
253 the object was created using ->new6($ip), the address returned will
254 always be in ipV6 format, even for addresses in ipV4 address space.
255
256 "->range()"
257 Returns a scalar with the base address and the broadcast address
258 separated by a dash and spaces. This is called range notation.
259
260 "->numeric()"
261 When called in a scalar context, will return a numeric
262 representation of the address part of the IP address. When called in
263 an array contest, it returns a list of two elements. The first
264 element is as described, the second element is the numeric
265 representation of the netmask.
266
267 This method is essential for serializing the representation of a
268 subnet.
269
270 "$me->contains($other)"
271 Returns true when "$me" completely contains "$other". False is
272 returned otherwise and "undef" is returned if "$me" and "$other" are
273 not both "NetAddr::IP::Lite" objects.
274
275 "$me->within($other)"
276 The complement of "->contains()". Returns true when "$me" is
277 completely contained within "$other", undef if "$me" and "$other"
278 are not both "NetAddr::IP::Lite" objects.
279
280 "->first()"
281 Returns a new object representing the first usable IP address within
282 the subnet (ie, the first host address).
283
284 "->last()"
285 Returns a new object representing the last usable IP address within
286 the subnet (ie, one less than the broadcast address).
287
288 "->nth($index)"
289 Returns a new object representing the *n*-th usable IP address
290 within the subnet (ie, the *n*-th host address). If no address is
291 available (for example, when the network is too small for "$index"
292 hosts), "undef" is returned.
293
294 Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
295 implements "->nth($index)" and "->num()" exactly as the
296 documentation states. Previous versions behaved slightly differently
297 and not in a consistent manner.
298
299 To use the old behavior for "->nth($index)" and "->num()":
300
301 use NetAddr::IP::Lite qw(:old_nth);
302
303 old behavior:
304 NetAddr::IP->new('10/32')->nth(0) == undef
305 NetAddr::IP->new('10/32')->nth(1) == undef
306 NetAddr::IP->new('10/31')->nth(0) == undef
307 NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31
308 NetAddr::IP->new('10/30')->nth(0) == undef
309 NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30
310 NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30
311 NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30
312
313 Note that in each case, the broadcast address is represented in the
314 output set and that the 'zero'th index is alway undef.
315
316 new behavior:
317 NetAddr::IP->new('10/32')->nth(0) == 10.0.0.0/32
318 NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32
319 NetAddr::IP->new('10/31')->nth(0) == undef
320 NetAddr::IP->new('10/31')->nth(1) == undef
321 NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30
322 NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30
323 NetAddr::IP->new('10/30')->nth(2) == undef
324
325 Note that a /32 net always has 1 usable address while a /31 has none
326 since it has a network and broadcast address, but no host addresses.
327 The first index (0) returns the address immediately following the
328 network address.
329
330 "->num()"
331 Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
332 Returns the number of usable addresses IP addresses within the
333 subnet, not counting the broadcast or network address. Previous
334 versions returned th number of IP addresses not counting the
335 broadcast address.
336
337 To use the old behavior for "->nth($index)" and "->num()":
338
339 use NetAddr::IP::Lite qw(:old_nth);
340
341EXPORT_OK
342 Zero
343 Ones
344 V4mask
345 V4net
346 :aton
347 :old_nth
348
349AUTHOR
350 Luis E. Mu�oz <luismunoz@cpan.org> Michael Robinton
351 <michael@bizsystems.com>
352
353WARRANTY
354 This software comes with the same warranty as perl itself (ie, none), so
355 by using it you accept any and all the liability.
356
357LICENSE
358 This software is (c) Luis E. Mu�oz, 1999 - 2005, and (c) Michael
359 Robinton, 2006. It can be used under the terms of the perl artistic
360 license provided that proper credit for the work of the author is
361 preserved in the form of this copyright notice and license for this
362 module.
363
364SEE ALSO
365 perl(1), NetAddr::IP(3), NetAddr::IP::Util(3)
366
367