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

OBJECT METHODS

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

PROCEDURAL INTERFACE

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

BUGS

503       The Math::BigInt library is needed for functions that use integers.
504       These are ip_inttobin, ip_bintoint, and the size method. In a next
505       version, Math::BigInt will become optionnal.
506

AUTHORS

508       Manuel Valente <manuel.valente@gmail.com>.
509
510       Original IPv4 code by Monica Cortes Sack <mcortes@ripe.net>.
511
512       Original IPv6 code by Lee Wilmot <lee@ripe.net>.
513

BASED ON

515       ipv4pack.pm, iplib.pm, iplibncc.pm.
516