1IP(3) User Contributed Perl Documentation IP(3)
2Net::IP - Perl extension for manipulating IPv4/IPv6 addresses
6
8 use Net::IP;
9 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
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
31 Object Creation
32 A Net::IP object can be created from a single IP address:
33 $ip = new Net::IP ('193.0.1.46') || die ...
35 Or from a Classless Prefix (a /24 prefix is equivalent to a C class):
37 $ip = new Net::IP ('195.114.80/24') || die ...
39 Or from a range of addresses:
41 $ip = new Net::IP ('20.34.101.207 - 201.3.9.99') || die ...
43 Or from a address plus a number:
45 $ip = new Net::IP ('20.34.10.0 + 255') || die ...
47 The new() function accepts IPv4 and IPv6 addresses:
49 $ip = new Net::IP ('dead:beef::/32') || die ...
51 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 $ip = new Net::IP ('195/8',4); # Class A
57
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 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 "$ip->set('130.23.1/24',4);"
70 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 It returns an IP object on success, and undef on failure.
76 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 "warn ($ip->error());"
83 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 "warn ($ip->errno());"
90 ip
92 Return the IP address (or first IP of the prefix or range) in quad
93 format, as a string.
94 "print ($ip->ip());"
96 binip
98 Return the IP address as a binary string of 0s and 1s.
99 "print ($ip->binip());"
101 prefixlen
103 Return the length in bits of the current prefix.
104 "print ($ip->prefixlen());"
106 version
108 Return the version of the current IP object (4 or 6).
109 "print ($ip->version());"
111 size
113 Return the number of IP addresses in the current prefix or range. Use
114 of this function requires Math::BigInt.
115 "print ($ip->size());"
117 binmask
119 Return the binary mask of the current prefix, if applicable.
120 "print ($ip->binmask());"
122 mask
124 Return the mask in quad format of the current prefix.
125 "print ($ip->mask());"
127 prefix
129 Return the full prefix (ip+prefix length) in quad (standard) format.
130 "print ($ip->prefix());"
132 print
134 Print the IP object (IP/Prefix or First - Last)
135 "print ($ip->print());"
137 intip
139 Convert the IP in integer format and return it as a Math::BigInt
140 object.
141 "print ($ip->intip());"
143 hexip
145 Return the IP in hex format
146 "print ($ip->hexip());"
148 hexmask
150 Return the mask in hex format
151 "print ($ip->hexmask());"
153 short
155 Return the IP in short format: IPv4 addresses: 194.5/16 IPv6
156 addresses: ab32:f000::
157 "print ($ip->short());"
159 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 "print ($ip->iptype());"
165 reverse_ip
167 Return the reverse IP for a given IP address (in.addr. format).
168 "print ($ip->reserve_ip());"
170 last_ip
172 Return the last IP of a prefix/range in quad format.
173 "print ($ip->last_ip());"
175 last_bin
177 Return the last IP of a prefix/range in binary format.
178 "print ($ip->last_bin());"
180 last_int
182 Return the last IP of a prefix/range in integer format.
183 "print ($ip->last_int());"
185 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 "@list = $ip->find_prefixes($other_ip));"
191 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 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 "if ($ip->bincomp('lt',$ip2) {...}"
200 binadd
202 Binary addition of two IP objects. The value returned is an IP object.
203 "my $sum = $ip->binadd($ip2);"
205 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 "my $total = $ip->aggregate($ip2);"
212 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 "if ($ip->overlaps($ip2)==$IP_A_IN_B_OVERLAP) {...};"
222 looping
224 The "+" operator is overloaded in order to allow looping though a whole
225 range of IP addresses:
226 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 The ++ operator returns undef when the last address of the range is
234 reached.
235 auth
237 Return IP authority information from the IP::Authority module
238 "$auth = ip-"auth ();>
240 Note: IPv4 only
242
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 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 "use Net::IP qw(:PROC);"
254 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 warn Error();
262 Errno
264 Returns a numeric error code corresponding to the error string returned
265 by Error.
266 ip_iptobin
268 Transform an IP address into a bit string.
269 Params : IP address, IP version
271 Returns : binary IP string on success, undef otherwise
272 "$binip = ip_iptobin ($ip,6);"
274 ip_bintoip
276 Transform a bit string into an IP address
277 Params : binary IP, IP version
279 Returns : IP address on success, undef otherwise
280 "$ip = ip_bintoip ($binip,6);"
282 ip_bintoint
284 Transform a bit string into a BigInt.
285 Params : binary IP
287 Returns : BigInt
288 "$bigint = new Math::BigInt (ip_bintoint($binip));"
290 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 Params : BigInt, IP version
296 Returns : binary IP
297 "$binip = ip_inttobin ($bigint);"
299 ip_get_version
301 Try to guess the IP version of an IP address.
302 Params : IP address
304 Returns : 4, 6, undef(unable to determine)
305 "$version = ip_get_version ($ip)"
307 ip_is_ipv4
309 Check if an IP address is of type 4.
310 Params : IP address
312 Returns : 1 (yes) or 0 (no)
313 "ip_is_ipv4($ip) and print "$ip is IPv4";"
315 ip_is_ipv6
317 Check if an IP address is of type 6.
318 Params : IP address
320 Returns : 1 (yes) or 0 (no)
321 "ip_is_ipv6($ip) and print "$ip is IPv6";"
323 ip_expand_address
325 Expand an IP address from compact notation.
326 Params : IP address, IP version
328 Returns : expanded IP address or undef on failure
329 "$ip = ip_expand_address ($ip,4);"
331 ip_get_mask
333 Get IP mask from prefix length.
334 Params : Prefix length, IP version
336 Returns : Binary Mask
337 "$mask = ip_get_mask ($len,6);"
339 ip_last_address_bin
341 Return the last binary address of a prefix.
342 Params : First binary IP, prefix length, IP version
344 Returns : Binary IP
345 "$lastbin = ip_last_address_bin ($ip,$len,6);"
347 ip_splitprefix
349 Split a prefix into IP and prefix length. If it was passed a simple
350 IP, it just returns it.
351 Params : Prefix
353 Returns : IP, optionnaly length of prefix
354 "($ip,$len) = ip_splitprefix ($prefix)"
356 ip_prefix_to_range
358 Get a range of IPs from a prefix.
359 Params : Prefix, IP version
361 Returns : First IP, last IP
362 "($ip1,$ip2) = ip_prefix_to_range ($prefix,6);"
364 ip_bincomp
366 Compare binary Ips with <, >, <=, >=.
367 Operators are lt(<), le(<=), gt(>), and ge(>=)
368 Params : First binary IP, operator, Last binary IP
370 Returns : 1 (yes), 0 (no), or undef (problem)
371 "ip_bincomp ($ip1,'lt',$ip2) == 1 or do {}"
373 ip_binadd
375 Add two binary IPs.
376 Params : First binary IP, Last binary IP
378 Returns : Binary sum or undef (problem)
379 "$binip = ip_binadd ($bin1,$bin2);"
381 ip_get_prefix_length
383 Get the prefix length for a given range of 2 IPs.
384 Params : First binary IP, Last binary IP
386 Returns : Length of prefix or undef (problem)
387 "$len = ip_get_prefix_length ($ip1,$ip2);"
389 ip_range_to_prefix
391 Return all prefixes between two IPs.
392 Params : First IP (binary format), Last IP (binary format), IP version
394 Returns : List of Prefixes or undef (problem)
395 The prefixes returned have the form q.q.q.q/nn.
397 "@prefix = ip_range_to_prefix ($ip1,$ip2,6);"
399 ip_compress_v4_prefix
401 Compress an IPv4 Prefix.
402 Params : IP, Prefix length
404 Returns : Compressed Prefix
405 "$ip = ip_compress_v4_prefix ($ip, $len);"
407 ip_compress_address
409 Compress an IPv6 address. Just returns the IP if it is an IPv4.
410 Params : IP, IP version
412 Returns : Compressed IP or undef (problem)
413 "$ip = ip_compress_adress ($ip, $version);"
415 ip_is_overlap
417 Check if two ranges of IPs overlap.
418 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 "(ip_is_overlap($rb1,$re1,$rb2,$re2,4) eq $IP_A_IN_B_OVERLAP) and do
428 {};"
429 ip_get_embedded_ipv4
431 Get an IPv4 embedded in an IPv6 address
432 Params : IPv6
434 Returns : IPv4 string or undef (not found)
435 "$ip4 = ip_get_embedded($ip6);"
437 ip_check_mask
439 Check the validity of a binary IP mask
440 Params : Mask
442 Returns : 1 or undef (invalid)
443 "ip_check_mask($binmask) or do {};"
445 Checks if mask has only 1s followed by 0s.
447 ip_aggregate
449 Aggregate 2 ranges of binary IPs
450 Params : 1st range (1st IP, Last IP), last range (1st IP, last IP), IP version
452 Returns : prefix or undef (invalid)
453 "$prefix = ip_aggregate ($bip1,$eip1,$bip2,$eip2) || die ..."
455 ip_iptypev4
457 Return the type of an IPv4 address.
458 Params: binary IP
460 Returns: type as of the following table or undef (invalid ip)
461 See RFC 5735 and RFC 6598
463 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 ip_iptypev6
486 Return the type of an IPv6 address.
487 Params: binary ip
489 Returns: type as of the following table or undef (invalid)
490 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 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 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 ip_iptype
536 Return the type of an IP (Public, Private, Reserved)
537 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 "$type = ip_iptype ($ip);"
542 ip_check_prefix
544 Check the validity of a prefix
545 Params : binary IP, length of prefix, IP version
547 Returns : 1 or undef (invalid)
548 Checks if the variant part of a prefix only has 0s, and the length is
550 correct.
551 "ip_check_prefix ($ip,$len,$ipv) or do {};"
553 ip_reverse
555 Get a reverse name from a prefix
556 Params : IP, length of prefix, IP version
558 Returns : Reverse name or undef (error)
559 "$reverse = ip_reverse ($ip);"
561 ip_normalize
563 Normalize data to a range/prefix of IP addresses
564 Params : Data String (Single IP, Range, Prefix)
566 Returns : ip1, ip2 (if range/prefix) or undef (error)
567 "($ip1,$ip2) = ip_normalize ($data);"
569 ip_auth
571 Return IP authority information from the IP::Authority module
572 Params : IP, version
574 Returns : Auth info (RI for RIPE, AR for ARIN, etc)
575 "$auth = ip_auth ($ip,4);"
577 Note: IPv4 only
579
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
586 Manuel Valente <manuel.valente@gmail.com>.
587 Original IPv4 code by Monica Cortes Sack <mcortes@ripe.net>.
589 Original IPv6 code by Lee Wilmot <lee@ripe.net>.
591
593 ipv4pack.pm, iplib.pm, iplibncc.pm.
594
596 perl(1), IP::Authority
597perl v5.32.1 2021-01-27 IP(3)