1IP(3)                 User Contributed Perl Documentation                IP(3)
2
3
4
5Net::IP - Perl extension for manipulating IPv4/IPv6 addresses
6

SYNOPSIS

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

DESCRIPTION

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

OBJECT-ORIENTED INTERFACE

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

OBJECT METHODS

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

PROCEDURAL INTERFACE

244       These functions do the real work in the module. Like the OO methods,
245       most of these return undef on failure. In order to access error codes
246       and strings, instead of using $ip->error() and $ip->errno(), use the
247       global functions Error() and Errno().
248
249       The functions of the procedural interface are not exported by default.
250       In order to import these functions, you need to modify the use
251       statement for the module:
252
253       "use Net::IP qw(:PROC);"
254
255   Error
256       Returns the error string corresponding to the last error generated in
257       the module. This is also useful for the OO interface, as if the new()
258       function fails, we cannot call $ip->error() and so we have to use
259       Error().
260
261       warn Error();
262
263   Errno
264       Returns a numeric error code corresponding to the error string returned
265       by Error.
266
267   ip_iptobin
268       Transform an IP address into a bit string.
269
270           Params  : IP address, IP version
271           Returns : binary IP string on success, undef otherwise
272
273       "$binip = ip_iptobin ($ip,6);"
274
275   ip_bintoip
276       Transform a bit string into an IP address
277
278           Params  : binary IP, IP version
279           Returns : IP address on success, undef otherwise
280
281       "$ip = ip_bintoip ($binip,6);"
282
283   ip_bintoint
284       Transform a bit string into a BigInt.
285
286           Params  : binary IP
287           Returns : BigInt
288
289       "$bigint = new Math::BigInt (ip_bintoint($binip));"
290
291   ip_inttobin
292       Transform a BigInt into a bit string.  Warning: sets warnings ("-w")
293       off. This is necessary because Math::BigInt is not compliant.
294
295           Params  : BigInt, IP version
296           Returns : binary IP
297
298       "$binip = ip_inttobin ($bigint);"
299
300   ip_get_version
301       Try to guess the IP version of an IP address.
302
303           Params  : IP address
304           Returns : 4, 6, undef(unable to determine)
305
306       "$version = ip_get_version ($ip)"
307
308   ip_is_ipv4
309       Check if an IP address is of type 4.
310
311           Params  : IP address
312           Returns : 1 (yes) or 0 (no)
313
314       "ip_is_ipv4($ip) and print "$ip is IPv4";"
315
316   ip_is_ipv6
317       Check if an IP address is of type 6.
318
319           Params            : IP address
320           Returns           : 1 (yes) or 0 (no)
321
322       "ip_is_ipv6($ip) and print "$ip is IPv6";"
323
324   ip_expand_address
325       Expand an IP address from compact notation.
326
327           Params  : IP address, IP version
328           Returns : expanded IP address or undef on failure
329
330       "$ip = ip_expand_address ($ip,4);"
331
332   ip_get_mask
333       Get IP mask from prefix length.
334
335           Params  : Prefix length, IP version
336           Returns : Binary Mask
337
338       "$mask = ip_get_mask ($len,6);"
339
340   ip_last_address_bin
341       Return the last binary address of a prefix.
342
343           Params  : First binary IP, prefix length, IP version
344           Returns : Binary IP
345
346       "$lastbin = ip_last_address_bin ($ip,$len,6);"
347
348   ip_splitprefix
349       Split a prefix into IP and prefix length.  If it was passed a simple
350       IP, it just returns it.
351
352           Params  : Prefix
353           Returns : IP, optionnaly length of prefix
354
355       "($ip,$len) = ip_splitprefix ($prefix)"
356
357   ip_prefix_to_range
358       Get a range of IPs from a prefix.
359
360           Params  : Prefix, IP version
361           Returns : First IP, last IP
362
363       "($ip1,$ip2) = ip_prefix_to_range ($prefix,6);"
364
365   ip_bincomp
366       Compare binary Ips with <, >, <=, >=.
367        Operators are lt(<), le(<=), gt(>), and ge(>=)
368
369           Params  : First binary IP, operator, Last binary IP
370           Returns : 1 (yes), 0 (no), or undef (problem)
371
372       "ip_bincomp ($ip1,'lt',$ip2) == 1 or do {}"
373
374   ip_binadd
375       Add two binary IPs.
376
377           Params  : First binary IP, Last binary IP
378           Returns : Binary sum or undef (problem)
379
380       "$binip = ip_binadd ($bin1,$bin2);"
381
382   ip_get_prefix_length
383       Get the prefix length for a given range of 2 IPs.
384
385           Params  : First binary IP, Last binary IP
386           Returns : Length of prefix or undef (problem)
387
388       "$len = ip_get_prefix_length ($ip1,$ip2);"
389
390   ip_range_to_prefix
391       Return all prefixes between two IPs.
392
393           Params  : First IP (binary format), Last IP (binary format), IP version
394           Returns : List of Prefixes or undef (problem)
395
396       The prefixes returned have the form q.q.q.q/nn.
397
398       "@prefix = ip_range_to_prefix ($ip1,$ip2,6);"
399
400   ip_compress_v4_prefix
401       Compress an IPv4 Prefix.
402
403           Params  : IP, Prefix length
404           Returns : Compressed Prefix
405
406       "$ip = ip_compress_v4_prefix ($ip, $len);"
407
408   ip_compress_address
409       Compress an IPv6 address. Just returns the IP if it is an IPv4.
410
411           Params  : IP, IP version
412           Returns : Compressed IP or undef (problem)
413
414       "$ip = ip_compress_adress ($ip, $version);"
415
416   ip_is_overlap
417       Check if two ranges of IPs overlap.
418
419           Params  : Four binary IPs (begin of range 1,end1,begin2,end2), IP version
420               $IP_PARTIAL_OVERLAP (ranges overlap)
421               $IP_NO_OVERLAP      (no overlap)
422               $IP_A_IN_B_OVERLAP  (range2 contains range1)
423               $IP_B_IN_A_OVERLAP  (range1 contains range2)
424               $IP_IDENTICAL       (ranges are identical)
425               undef               (problem)
426
427       "(ip_is_overlap($rb1,$re1,$rb2,$re2,4) eq $IP_A_IN_B_OVERLAP) and do
428       {};"
429
430   ip_get_embedded_ipv4
431       Get an IPv4 embedded in an IPv6 address
432
433           Params  : IPv6
434           Returns : IPv4 string or undef (not found)
435
436       "$ip4 = ip_get_embedded($ip6);"
437
438   ip_check_mask
439       Check the validity of a binary IP mask
440
441           Params  : Mask
442           Returns : 1 or undef (invalid)
443
444       "ip_check_mask($binmask) or do {};"
445
446       Checks if mask has only 1s followed by 0s.
447
448   ip_aggregate
449       Aggregate 2 ranges of binary IPs
450
451           Params  : 1st range (1st IP, Last IP), last range (1st IP, last IP), IP version
452           Returns : prefix or undef (invalid)
453
454       "$prefix = ip_aggregate ($bip1,$eip1,$bip2,$eip2) || die ..."
455
456   ip_iptypev4
457       Return the type of an IPv4 address.
458
459           Params:  binary IP
460           Returns: type as of the following table or undef (invalid ip)
461
462       See RFC 5735 and RFC 6598
463
464       Address Block       Present Use                Reference
465       -------------------------------------------------------------------
466       0.0.0.0/8           "This" Network             RFC 1122 PRIVATE
467       10.0.0.0/8          Private-Use Networks       RFC 1918 PRIVATE
468       100.64.0.0/10       CGN Shared Address Space   RFC 6598 SHARED
469       127.0.0.0/8         Loopback                   RFC 1122 LOOPBACK
470       169.254.0.0/16      Link Local                 RFC 3927 LINK-LOCAL
471       172.16.0.0/12       Private-Use Networks       RFC 1918 PRIVATE
472       192.0.0.0/24        IETF Protocol Assignments  RFC 5736 RESERVED
473       192.0.2.0/24        TEST-NET-1                 RFC 5737 TEST-NET
474       192.88.99.0/24      6to4 Relay Anycast         RFC 3068 6TO4-RELAY
475       192.168.0.0/16      Private-Use Networks       RFC 1918 PRIVATE
476       198.18.0.0/15       Network Interconnect
477                           Device Benchmark Testing   RFC 2544 RESERVED
478       198.51.100.0/24     TEST-NET-2                 RFC 5737 TEST-NET
479       203.0.113.0/24      TEST-NET-3                 RFC 5737 TEST-NET
480       224.0.0.0/4         Multicast                  RFC 3171 MULTICAST
481       240.0.0.0/4         Reserved for Future Use    RFC 1112 RESERVED
482       255.255.255.255/32  Limited Broadcast          RFC 919  BROADCAST
483                                                      RFC 922
484
485   ip_iptypev6
486       Return the type of an IPv6 address.
487
488           Params:  binary ip
489           Returns: type as of the following table or undef (invalid)
490
491       See IANA Internet Protocol Version 6 Address Space
492       <http://www.iana.org/assignments/ipv6-address-space/ipv6-address-
493       space.txt>  and IANA IPv6 Special Purpose Address Registry
494       <http://www.iana.org/assignments/iana-ipv6-special-registry/iana-
495       ipv6-special-registry.txt>
496
497       Prefix      Allocation           Reference
498       -------------------------------------------------------------
499       0000::/8    Reserved by IETF     [RFC4291] RESERVED
500       0100::/8    Reserved by IETF     [RFC4291] RESERVED
501       0200::/7    Reserved by IETF     [RFC4048] RESERVED
502       0400::/6    Reserved by IETF     [RFC4291] RESERVED
503       0800::/5    Reserved by IETF     [RFC4291] RESERVED
504       1000::/4    Reserved by IETF     [RFC4291] RESERVED
505       2000::/3    Global Unicast       [RFC4291] GLOBAL-UNICAST
506       4000::/3    Reserved by IETF     [RFC4291] RESERVED
507       6000::/3    Reserved by IETF     [RFC4291] RESERVED
508       8000::/3    Reserved by IETF     [RFC4291] RESERVED
509       A000::/3    Reserved by IETF     [RFC4291] RESERVED
510       C000::/3    Reserved by IETF     [RFC4291] RESERVED
511       E000::/4    Reserved by IETF     [RFC4291] RESERVED
512       F000::/5    Reserved by IETF     [RFC4291] RESERVED
513       F800::/6    Reserved by IETF     [RFC4291] RESERVED
514       FC00::/7    Unique Local Unicast [RFC4193] UNIQUE-LOCAL-UNICAST
515       FE00::/9    Reserved by IETF     [RFC4291] RESERVED
516       FE80::/10   Link Local Unicast   [RFC4291] LINK-LOCAL-UNICAST
517       FEC0::/10   Reserved by IETF     [RFC3879] RESERVED
518       FF00::/8    Multicast            [RFC4291] MULTICAST
519
520       Prefix          Assignment            Reference
521       ---------------------------------------------------------------------
522       ::1/128         Loopback Address      [RFC4291] UNSPECIFIED
523       ::/128          Unspecified Address   [RFC4291] LOOPBACK
524       ::FFFF:0:0/96   IPv4-mapped Address   [RFC4291] IPV4MAP
525       0100::/64       Discard-Only Prefix   [RFC6666] DISCARD
526       2001:0000::/32  TEREDO                [RFC4380] TEREDO
527       2001:0002::/48  BMWG                  [RFC5180] BMWG
528       2001:db8::/32   Documentation Prefix  [RFC3849] DOCUMENTATION
529       2001:10::/28    ORCHID                [RFC4843] ORCHID
530       2002::/16       6to4                  [RFC3056] 6TO4
531       FC00::/7        Unique-Local          [RFC4193] UNIQUE-LOCAL-UNICAST
532       FE80::/10       Linked-Scoped Unicast [RFC4291] LINK-LOCAL-UNICAST
533       FF00::/8        Multicast             [RFC4291] MULTICAST
534
535   ip_iptype
536       Return the type of an IP (Public, Private, Reserved)
537
538           Params  : Binary IP to test, IP version (defaults to 6)
539           Returns : type (see ip_iptypev4 and ip_iptypev6 for details) or undef (invalid)
540
541       "$type = ip_iptype ($ip);"
542
543   ip_check_prefix
544       Check the validity of a prefix
545
546           Params  : binary IP, length of prefix, IP version
547           Returns : 1 or undef (invalid)
548
549       Checks if the variant part of a prefix only has 0s, and the length is
550       correct.
551
552       "ip_check_prefix ($ip,$len,$ipv) or do {};"
553
554   ip_reverse
555       Get a reverse name from a prefix
556
557           Params  : IP, length of prefix, IP version
558           Returns : Reverse name or undef (error)
559
560       "$reverse = ip_reverse ($ip);"
561
562   ip_normalize
563       Normalize data to a range/prefix of IP addresses
564
565           Params  : Data String (Single IP, Range, Prefix)
566           Returns : ip1, ip2 (if range/prefix) or undef (error)
567
568       "($ip1,$ip2) = ip_normalize ($data);"
569
570   ip_auth
571       Return IP authority information from the IP::Authority module
572
573           Params  : IP, version
574           Returns : Auth info (RI for RIPE, AR for ARIN, etc)
575
576       "$auth = ip_auth ($ip,4);"
577
578       Note: IPv4 only
579

BUGS

581       The Math::BigInt library is needed for functions that use integers.
582       These are ip_inttobin, ip_bintoint, and the size method. In a next
583       version, Math::BigInt will become optionnal.
584

AUTHORS

586       Manuel Valente <manuel.valente@gmail.com>.
587
588       Original IPv4 code by Monica Cortes Sack <mcortes@ripe.net>.
589
590       Original IPv6 code by Lee Wilmot <lee@ripe.net>.
591

BASED ON

593       ipv4pack.pm, iplib.pm, iplibncc.pm.
594

SEE ALSO

596       perl(1), IP::Authority
597
598
599
600perl v5.38.0                      2023-07-21                             IP(3)
Impressum