Net::IP(3pm)

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

NAME

6       Net::IP - Perl extension for manipulating IPv4/IPv6 addresses
7

SYNOPSIS

9         use Net::IP;
10
11         my $ip = new Net::IP ('193.0.1/24') or die (Net::IP::Error());
12         print ("IP  : ".$ip->ip()."\n");
13         print ("Sho : ".$ip->short()."\n");
14         print ("Bin : ".$ip->binip()."\n");
15         print ("Int : ".$ip->intip()."\n");
16         print ("Mask: ".$ip->mask()."\n");
17         print ("Last: ".$ip->last_ip()."\n");
18         print ("Len : ".$ip->prefixlen()."\n");
19         print ("Size: ".$ip->size()."\n");
20         print ("Type: ".$ip->iptype()."\n");
21         print ("Rev:  ".$ip->reverse_ip()."\n");
22

DESCRIPTION

24       This module provides functions to deal with IPv4/IPv6 addresses. The
25       module can be used as a class, allowing the user to instantiate IP
26       objects, which can be single IP addresses, prefixes, or ranges of
27       addresses. There is also a procedural way of accessing most of the
28       functions. Most subroutines can take either IPv4 or IPv6 addresses
29       transparently.
30

OBJECT-ORIENTED INTERFACE

32       Object Creation
33
34       A Net::IP object can be created from a single IP address:
35
36         $ip = new Net::IP ('193.0.1.46') ⎪⎪ die ...
37
38       Or from a Classless Prefix (a /24 prefix is equivalent to a C class):
39
40         $ip = new Net::IP ('195.114.80/24') ⎪⎪ die ...
41
42       Or from a range of addresses:
43
44         $ip = new Net::IP ('20.34.101.207 - 201.3.9.99') ⎪⎪ die ...
45
46       Or from a address plus a number:
47
48         $ip = new Net::IP ('20.34.10.0 + 255') ⎪⎪ die ...
49
50       The new() function accepts IPv4 and IPv6 addresses:
51
52         $ip = new Net::IP ('dead:beef::/32') ⎪⎪ die ...
53
54       Optionnaly, the function can be passed the version of the IP. Other‐
55       wise, it tries to guess what the version is (see _is_ipv4() and
56       _is_ipv6()).
57
58         $ip = new Net::IP ('195/8',4); # Class A
59

OBJECT METHODS

61       Most of these methods are front-ends for the real functions, which use
62       a procedural interface. Most functions return undef on failure, and a
63       true value on success. A detailed description of the procedural inter‐
64       face is provided below.
65
66       set
67
68       Set an IP address in an existing IP object. This method has the same
69       functionality as the new() method, except that it reuses an existing
70       object to store the new IP.
71
72       "$ip->set('130.23.1/24',4);"
73
74       Like new(), set() takes two arguments - a string used to build an IP
75       address, prefix, or range, and optionally, the IP version of the con‐
76       sidered address.
77
78       It returns an IP object on success, and undef on failure.
79
80       error
81
82       Return the current object error string. The error string is set when‐
83       ever one of the methods produces an error. Also, a global, class-wide
84       Error() function is avaliable.
85
86       "warn ($ip->error());"
87
88       errno
89
90       Return the current object error number. The error number is set when‐
91       ever one of the methods produces an error. Also, a global $ERRNO vari‐
92       able is set when an error is produced.
93
94       "warn ($ip->errno());"
95
96       ip
97
98       Return the IP address (or first IP of the prefix or range) in quad for‐
99       mat, as a string.
100
101       "print ($ip->ip());"
102
103       binip
104
105       Return the IP address as a binary string of 0s and 1s.
106
107       "print ($ip->binip());"
108
109       prefixlen
110
111       Return the length in bits of the current prefix.
112
113       "print ($ip->prefixlen());"
114
115       version
116
117       Return the version of the current IP object (4 or 6).
118
119       "print ($ip->version());"
120
121       size
122
123       Return the number of IP addresses in the current prefix or range.  Use
124       of this function requires Math::BigInt.
125
126       "print ($ip->size());"
127
128       binmask
129
130       Return the binary mask of the current prefix, if applicable.
131
132       "print ($ip->binmask());"
133
134       mask
135
136       Return the mask in quad format of the current prefix.
137
138       "print ($ip->mask());"
139
140       prefix
141
142       Return the full prefix (ip+prefix length) in quad (standard) format.
143
144       "print ($ip->prefix());"
145
146       print
147
148       Print the IP object (IP/Prefix or First - Last)
149
150       "print ($ip->print());"
151
152       intip
153
154       Convert the IP in integer format and return it as a Math::BigInt
155       object.
156
157       "print ($ip->intip());"
158
159       hexip
160
161       Return the IP in hex format
162
163       "print ($ip->hexip());"
164
165       hexmask
166
167       Return the mask in hex format
168
169       "print ($ip->hexmask());"
170
171       short
172
173       Return the IP in short format:      IPv4 addresses: 194.5/16      IPv6
174       addresses: ab32:f000::
175
176       "print ($ip->short());"
177
178       iptype
179
180       Return the IP Type - this describes the type of an IP (Public, Private,
181       Reserved, etc.)
182
183       "print ($ip->iptype());"
184
185       reverse_ip
186
187       Return the reverse IP for a given IP address (in.addr. format).
188
189       "print ($ip->reserve_ip());"
190
191       last_ip
192
193       Return the last IP of a prefix/range in quad format.
194
195       "print ($ip->last_ip());"
196
197       last_bin
198
199       Return the last IP of a prefix/range in binary format.
200
201       "print ($ip->last_bin());"
202
203       last_int
204
205       Return the last IP of a prefix/range in integer format.
206
207       "print ($ip->last_int());"
208
209       find_prefixes
210
211       This function finds all the prefixes that can be found between the two
212       addresses of a range. The function returns a list of prefixes.
213
214       "@list = $ip->find_prefixes($other_ip));"
215
216       bincomp
217
218       Binary comparaison of two IP objects. The function takes an operation
219       and an IP object as arguments. It returns a boolean value.
220
221       The operation can be one of: lt: less than (smaller than) le: smaller
222       or equal to gt: greater than ge: greater or equal to
223
224       "if ($ip->bincomp('lt',$ip2) {...}"
225
226       binadd
227
228       Binary addition of two IP objects. The value returned is an IP object.
229
230       "my $sum = $ip->binadd($ip2);"
231
232       aggregate
233
234       Aggregate 2 IPs - Append one range/prefix of IPs to another. The last
235       address of the first range must be the one immediately preceding the
236       first address of the second range. A new IP object is returned.
237
238       "my $total = $ip->aggregate($ip2);"
239
240       overlaps
241
242       Check if two IP ranges/prefixes overlap each other. The value returned
243       by the function should be one of:      $IP_PARTIAL_OVERLAP (ranges
244       overlap)      $IP_NO_OVERLAP      (no overlap)      $IP_A_IN_B_OVERLAP
245       (range2 contains range1)      $IP_B_IN_A_OVERLAP  (range1 contains
246       range2)      $IP_IDENTICAL       (ranges are identical)      undef
247       (problem)
248
249       "if ($ip->overlaps($ip2)==$IP_A_IN_B_OVERLAP) {...};"
250
251       looping
252
253       The "+" operator is overloaded in order to allow looping though a whole
254       range of IP addresses:
255
256         my $ip = new Net::IP ('195.45.6.7 - 195.45.6.19') ⎪⎪ die;
257         # Loop
258         do {
259             print $ip->ip(), "\n";
260         } while (++$ip);
261
262       The ++ operator returns undef when the last address of the range is
263       reached.
264
265       auth
266
267       Return IP authority information from the IP::Authority module
268
269       "$auth = ip-"auth ();>
270
271       Note: IPv4 only
272

PROCEDURAL INTERFACE

274       These functions do the real work in the module. Like the OO methods,
275       most of these return undef on failure. In order to access error codes
276       and strings, instead of using $ip->error() and $ip->errno(), use the
277       global functions "Error()" and "Errno()".
278
279       The functions of the procedural interface are not exported by default.
280       In order to import these functions, you need to modify the use state‐
281       ment for the module:
282
283       "use Net::IP qw(:PROC);"
284
285       Error
286
287       Returns the error string corresponding to the last error generated in
288       the module. This is also useful for the OO interface, as if the new()
289       function fails, we cannot call $ip->error() and so we have to use
290       Error().
291
292       warn Error();
293
294       Errno
295
296       Returns a numeric error code corresponding to the error string returned
297       by Error.
298
299       ip_iptobin
300
301       Transform an IP address into a bit string.
302
303           Params  : IP address, IP version
304           Returns : binary IP string on success, undef otherwise
305
306       "$binip = ip_iptobin ($ip,6);"
307
308       ip_bintoip
309
310       Transform a bit string into an IP address
311
312           Params  : binary IP, IP version
313           Returns : IP address on success, undef otherwise
314
315       "$ip = ip_bintoip ($binip,6);"
316
317       ip_bintoint
318
319       Transform a bit string into a BigInt.
320
321           Params  : binary IP
322           Returns : BigInt
323
324       "$bigint = new Math::BigInt (ip_bintoint($binip));"
325
326       ip_inttobin
327
328       Transform a BigInt into a bit string.  Warning: sets warnings ("-w")
329       off. This is necessary because Math::BigInt is not compliant.
330
331           Params  : BigInt, IP version
332           Returns : binary IP
333
334       "$binip = ip_inttobin ($bigint);"
335
336       ip_get_version
337
338       Try to guess the IP version of an IP address.
339
340           Params  : IP address
341           Returns : 4, 6, undef(unable to determine)
342
343       "$version = ip_get_version ($ip)"
344
345       ip_is_ipv4
346
347       Check if an IP address is of type 4.
348
349           Params  : IP address
350           Returns : 1 (yes) or 0 (no)
351
352       "ip_is_ipv4($ip) and print "$ip is IPv4";"
353
354       ip_is_ipv6
355
356       Check if an IP address is of type 6.
357
358           Params            : IP address
359           Returns           : 1 (yes) or 0 (no)
360
361       "ip_is_ipv6($ip) and print "$ip is IPv6";"
362
363       ip_expand_address
364
365       Expand an IP address from compact notation.
366
367           Params  : IP address, IP version
368           Returns : expanded IP address or undef on failure
369
370       "$ip = ip_expand_address ($ip,4);"
371
372       ip_get_mask
373
374       Get IP mask from prefix length.
375
376           Params  : Prefix length, IP version
377           Returns : Binary Mask
378
379       "$mask = ip_get_mask ($len,6);"
380
381       ip_last_address_bin
382
383       Return the last binary address of a prefix.
384
385           Params  : First binary IP, prefix length, IP version
386           Returns : Binary IP
387
388       "$lastbin = ip_last_address_bin ($ip,$len,6);"
389
390       ip_splitprefix
391
392       Split a prefix into IP and prefix length.  If it was passed a simple
393       IP, it just returns it.
394
395           Params  : Prefix
396           Returns : IP, optionnaly length of prefix
397
398       "($ip,$len) = ip_splitprefix ($prefix)"
399
400       ip_prefix_to_range
401
402       Get a range of IPs from a prefix.
403
404           Params  : Prefix, IP version
405           Returns : First IP, last IP
406
407       "($ip1,$ip2) = ip_prefix_to_range ($prefix,6);"
408
409       ip_bincomp
410
411       Compare binary Ips with <, >, <=, >=.
412        Operators are lt(<), le(<=), gt(>), and ge(>=)
413
414           Params  : First binary IP, operator, Last binary IP
415           Returns : 1 (yes), 0 (no), or undef (problem)
416
417       "ip_bincomp ($ip1,'lt',$ip2) == 1 or do {}"
418
419       ip_binadd
420
421       Add two binary IPs.
422
423           Params  : First binary IP, Last binary IP
424           Returns : Binary sum or undef (problem)
425
426       "$binip = ip_binadd ($bin1,$bin2);"
427
428       ip_get_prefix_length
429
430       Get the prefix length for a given range of 2 IPs.
431
432           Params  : First binary IP, Last binary IP
433           Returns : Length of prefix or undef (problem)
434
435       "$len = ip_get_prefix_length ($ip1,$ip2);"
436
437       ip_range_to_prefix
438
439       Return all prefixes between two IPs.
440
441           Params  : First IP, Last IP, IP version
442           Returns : List of Prefixes or undef (problem)
443
444       The prefixes returned have the form q.q.q.q/nn.
445
446       "@prefix = ip_range_to_prefix ($ip1,$ip2,6);"
447
448       ip_compress_v4_prefix
449
450       Compress an IPv4 Prefix.
451
452           Params  : IP, Prefix length
453           Returns : Compressed Prefix
454
455       "$ip = ip_compress_v4_prefix ($ip, $len);"
456
457       ip_compress_address
458
459       Compress an IPv6 address. Just returns the IP if it is an IPv4.
460
461           Params  : IP, IP version
462           Returns : Compressed IP or undef (problem)
463
464       "$ip = ip_compress_adress ($ip, $version);"
465
466       ip_is_overlap
467
468       Check if two ranges of IPs overlap.
469
470           Params  : Four binary IPs (begin of range 1,end1,begin2,end2), IP version
471               $IP_PARTIAL_OVERLAP (ranges overlap)
472               $IP_NO_OVERLAP      (no overlap)
473               $IP_A_IN_B_OVERLAP  (range2 contains range1)
474               $IP_B_IN_A_OVERLAP  (range1 contains range2)
475               $IP_IDENTICAL       (ranges are identical)
476               undef               (problem)
477
478       "(ip_is_overlap($rb1,$re1,$rb2,$re2,4) eq $IP_A_IN_B_OVERLAP) and do
479       {};"
480
481       ip_get_embedded_ipv4
482
483       Get an IPv4 embedded in an IPv6 address
484
485           Params  : IPv6
486           Returns : IPv4 string or undef (not found)
487
488       "$ip4 = ip_get_embedded($ip6);"
489
490       ip_check_mask
491
492       Check the validity of a binary IP mask
493
494           Params  : Mask
495           Returns : 1 or undef (invalid)
496
497       "ip_check_mask($binmask) or do {};"
498
499       Checks if mask has only 1s followed by 0s.
500
501       ip_aggregate
502
503       Aggregate 2 ranges of binary IPs
504
505           Params  : 1st range (1st IP, Last IP), last range (1st IP, last IP), IP version
506           Returns : prefix or undef (invalid)
507
508       "$prefix = ip_aggregate ($bip1,$eip1,$bip2,$eip2) ⎪⎪ die ..."
509
510       ip_iptype
511
512       Return the type of an IP (Public, Private, Reserved)
513
514           Params  : IP to test, IP version
515           Returns : type or undef (invalid)
516
517       "$type = ip_iptype ($ip);"
518
519       ip_check_prefix
520
521       Check the validity of a prefix
522
523           Params  : binary IP, length of prefix, IP version
524           Returns : 1 or undef (invalid)
525
526       Checks if the variant part of a prefix only has 0s, and the length is
527       correct.
528
529       "ip_check_prefix ($ip,$len,$ipv) or do {};"
530
531       ip_reverse
532
533       Get a reverse name from a prefix
534
535           Params  : IP, length of prefix, IP version
536           Returns : Reverse name or undef (error)
537
538       "$reverse = ip_reverse ($ip);"
539
540       ip_normalize
541
542       Normalize data to a range/prefix of IP addresses
543
544           Params  : Data String (Single IP, Range, Prefix)
545           Returns : ip1, ip2 (if range/prefix) or undef (error)
546
547       "($ip1,$ip2) = ip_normalize ($data);"
548
549       ip_auth
550
551       Return IP authority information from the IP::Authority module
552
553           Params  : IP, version
554           Returns : Auth info (RI for RIPE, AR for ARIN, etc)
555
556       "$auth = ip_auth ($ip,4);"
557
558       Note: IPv4 only
559

BUGS

561       The Math::BigInt library is needed for functions that use integers.
562       These are ip_inttobin, ip_bintoint, and the size method. In a next ver‐
563       sion, Math::BigInt will become optionnal.
564

AUTHORS

566       Manuel Valente <manuel.valente@gmail.com>.
567
568       Original IPv4 code by Monica Cortes Sack <mcortes@ripe.net>.
569
570       Original IPv6 code by Lee Wilmot <lee@ripe.net>.
571

BASED ON

573       ipv4pack.pm, iplib.pm, iplibncc.pm.
574