|
Net::IP - Perl extension for manipulating IPv4/IPv6 addresses SYNOPSISuse Net::IP; my $ip = new Net::IP ('193.0.1/24') or die (Net::IP::Error()); print ("IP : ".$ip->ip()."\n"); print ("Sho : ".$ip->short()."\n"); print ("Bin : ".$ip->binip()."\n"); print ("Int : ".$ip->intip()."\n"); print ("Mask: ".$ip->mask()."\n"); print ("Last: ".$ip->last_ip()."\n"); print ("Len : ".$ip->prefixlen()."\n"); print ("Size: ".$ip->size()."\n"); print ("Type: ".$ip->iptype()."\n"); print ("Rev: ".$ip->reverse_ip()."\n"); DESCRIPTIONThis module provides functions to deal with IPv4/IPv6 addresses. The module can be used as a class, allowing the user to instantiate IP objects, which can be single IP addresses, prefixes, or ranges of addresses. There is also a procedural way of accessing most of the functions. Most subroutines can take either IPv4 or IPv6 addresses transparently.OBJECT-ORIENTED INTERFACEObject CreationA Net::IP object can be created from a single IP address:$ip = new Net::IP ('193.0.1.46') || die ... Or from a Classless Prefix (a /24 prefix is equivalent to a C class): $ip = new Net::IP ('195.114.80/24') || die ... Or from a range of addresses: $ip = new Net::IP ('20.34.101.207 - 201.3.9.99') || die ... Or from a address plus a number: $ip = new Net::IP ('20.34.10.0 + 255') || die ... The new() function accepts IPv4 and IPv6 addresses: $ip = new Net::IP ('dead:beef::/32') || die ... Optionnaly, the function can be passed the version of the IP. Otherwise, it tries to guess what the version is (see _is_ipv4() and _is_ipv6()). $ip = new Net::IP ('195/8',4); # Class A OBJECT METHODSMost of these methods are front-ends for the real functions, which use a procedural interface. Most functions return undef on failure, and a true value on success. A detailed description of the procedural interface is provided below.setSet an IP address in an existing IP object. This method has the same functionality as the new() method, except that it reuses an existing object to store the new IP."$ip->set('130.23.1/24',4);" Like new(), set() takes two arguments - a string used to build an IP address, prefix, or range, and optionally, the IP version of the considered address. It returns an IP object on success, and undef on failure. errorReturn the current object error string. The error string is set whenever one of the methods produces an error. Also, a global, class-wide Error() function is avaliable."warn ($ip->error());" errnoReturn the current object error number. The error number is set whenever one of the methods produces an error. Also, a global $ERRNO variable is set when an error is produced."warn ($ip->errno());" ipReturn the IP address (or first IP of the prefix or range) in quad format, as a string."print ($ip->ip());" binipReturn the IP address as a binary string of 0s and 1s."print ($ip->binip());" prefixlenReturn the length in bits of the current prefix."print ($ip->prefixlen());" versionReturn the version of the current IP object (4 or 6)."print ($ip->version());" sizeReturn the number of IP addresses in the current prefix or range. Use of this function requires Math::BigInt."print ($ip->size());" binmaskReturn the binary mask of the current prefix, if applicable."print ($ip->binmask());" maskReturn the mask in quad format of the current prefix."print ($ip->mask());" prefixReturn the full prefix (ip+prefix length) in quad (standard) format."print ($ip->prefix());" "print ($ip->print());" intipConvert the IP in integer format and return it as a Math::BigInt object."print ($ip->intip());" hexipReturn the IP in hex format"print ($ip->hexip());" hexmaskReturn the mask in hex format"print ($ip->hexmask());" shortReturn the IP in short format: IPv4 addresses: 194.5/16 IPv6 addresses: ab32:f000::"print ($ip->short());" iptypeReturn the IP Type - this describes the type of an IP (Public, Private, Reserved, etc.) See procedural interface ip_iptype for more details."print ($ip->iptype());" reverse_ipReturn the reverse IP for a given IP address (in.addr. format)."print ($ip->reserve_ip());" last_ipReturn the last IP of a prefix/range in quad format."print ($ip->last_ip());" last_binReturn the last IP of a prefix/range in binary format."print ($ip->last_bin());" last_intReturn the last IP of a prefix/range in integer format."print ($ip->last_int());" find_prefixesThis function finds all the prefixes that can be found between the two addresses of a range. The function returns a list of prefixes."@list = $ip->find_prefixes($other_ip));" bincompBinary comparaison of two IP objects. The function takes an operation and an IP object as arguments. It returns a boolean value.The operation can be one of: lt: less than (smaller than) le: smaller or equal to gt: greater than ge: greater or equal to "if ($ip->bincomp('lt',$ip2) {...}" binaddBinary addition of two IP objects. The value returned is an IP object."my $sum = $ip->binadd($ip2);" aggregateAggregate 2 IPs - Append one range/prefix of IPs to another. The last address of the first range must be the one immediately preceding the first address of the second range. A new IP object is returned."my $total = $ip->aggregate($ip2);" overlapsCheck if two IP ranges/prefixes overlap each other. The value returned by the function should be one of: $IP_PARTIAL_OVERLAP (ranges overlap) $IP_NO_OVERLAP (no overlap) $IP_A_IN_B_OVERLAP (range2 contains range1) $IP_B_IN_A_OVERLAP (range1 contains range2) $IP_IDENTICAL (ranges are identical) undef (problem)"if ($ip->overlaps($ip2)==$IP_A_IN_B_OVERLAP) {...};" loopingThe "+" operator is overloaded in order to allow looping though a whole range of IP addresses:my $ip = new Net::IP ('195.45.6.7 - 195.45.6.19') || die; # Loop do { print $ip->ip(), "\n"; } while (++$ip); The ++ operator returns undef when the last address of the range is reached. authReturn IP authority information from the IP::Authority module"$auth = ip-"auth ();> Note: IPv4 only PROCEDURAL INTERFACEThese functions do the real work in the module. Like the OO methods, most of these return undef on failure. In order to access error codes and strings, instead of using $ip->error() and $ip->errno(), use the global functions "Error()" and "Errno()".The functions of the procedural interface are not exported by default. In order to import these functions, you need to modify the use statement for the module: "use Net::IP qw(:PROC);" ErrorReturns the error string corresponding to the last error generated in the module. This is also useful for the OO interface, as if the new() function fails, we cannot call $ip->error() and so we have to use Error().warn Error(); ErrnoReturns a numeric error code corresponding to the error string returned by Error.ip_iptobinTransform an IP address into a bit string.Params : IP address, IP version Returns : binary IP string on success, undef otherwise "$binip = ip_iptobin ($ip,6);" ip_bintoipTransform a bit string into an IP addressParams : binary IP, IP version Returns : IP address on success, undef otherwise "$ip = ip_bintoip ($binip,6);" ip_bintointTransform a bit string into a BigInt.Params : binary IP Returns : BigInt "$bigint = new Math::BigInt (ip_bintoint($binip));" ip_inttobinTransform a BigInt into a bit string. Warning: sets warnings ("-w") off. This is necessary because Math::BigInt is not compliant.Params : BigInt, IP version Returns : binary IP "$binip = ip_inttobin ($bigint);" ip_get_versionTry to guess the IP version of an IP address.Params : IP address Returns : 4, 6, undef(unable to determine) "$version = ip_get_version ($ip)" ip_is_ipv4Check if an IP address is of type 4.Params : IP address Returns : 1 (yes) or 0 (no) "ip_is_ipv4($ip) and print "$ip is IPv4";" ip_is_ipv6Check if an IP address is of type 6.Params : IP address Returns : 1 (yes) or 0 (no) "ip_is_ipv6($ip) and print "$ip is IPv6";" ip_expand_addressExpand an IP address from compact notation.Params : IP address, IP version Returns : expanded IP address or undef on failure "$ip = ip_expand_address ($ip,4);" ip_get_maskGet IP mask from prefix length.Params : Prefix length, IP version Returns : Binary Mask "$mask = ip_get_mask ($len,6);" ip_last_address_binReturn the last binary address of a prefix.Params : First binary IP, prefix length, IP version Returns : Binary IP "$lastbin = ip_last_address_bin ($ip,$len,6);" ip_splitprefixSplit a prefix into IP and prefix length. If it was passed a simple IP, it just returns it.Params : Prefix Returns : IP, optionnaly length of prefix "($ip,$len) = ip_splitprefix ($prefix)" ip_prefix_to_rangeGet a range of IPs from a prefix.Params : Prefix, IP version Returns : First IP, last IP "($ip1,$ip2) = ip_prefix_to_range ($prefix,6);" ip_bincompCompare binary Ips with <, >, <=, >=. Operators are lt(<), le(<=), gt(>), and ge(>=)Params : First binary IP, operator, Last binary IP Returns : 1 (yes), 0 (no), or undef (problem) "ip_bincomp ($ip1,'lt',$ip2) == 1 or do {}" ip_binaddAdd two binary IPs.Params : First binary IP, Last binary IP Returns : Binary sum or undef (problem) "$binip = ip_binadd ($bin1,$bin2);" ip_get_prefix_lengthGet the prefix length for a given range of 2 IPs.Params : First binary IP, Last binary IP Returns : Length of prefix or undef (problem) "$len = ip_get_prefix_length ($ip1,$ip2);" ip_range_to_prefixReturn all prefixes between two IPs.Params : First IP (binary format), Last IP (binary format), IP version Returns : List of Prefixes or undef (problem) The prefixes returned have the form q.q.q.q/nn. "@prefix = ip_range_to_prefix ($ip1,$ip2,6);" ip_compress_v4_prefixCompress an IPv4 Prefix.Params : IP, Prefix length Returns : Compressed Prefix "$ip = ip_compress_v4_prefix ($ip, $len);" ip_compress_addressCompress an IPv6 address. Just returns the IP if it is an IPv4.Params : IP, IP version Returns : Compressed IP or undef (problem) "$ip = ip_compress_adress ($ip, $version);" ip_is_overlapCheck if two ranges of IPs overlap.Params : Four binary IPs (begin of range 1,end1,begin2,end2), IP version $IP_PARTIAL_OVERLAP (ranges overlap) $IP_NO_OVERLAP (no overlap) $IP_A_IN_B_OVERLAP (range2 contains range1) $IP_B_IN_A_OVERLAP (range1 contains range2) $IP_IDENTICAL (ranges are identical) undef (problem) "(ip_is_overlap($rb1,$re1,$rb2,$re2,4) eq $IP_A_IN_B_OVERLAP) and do {};" ip_get_embedded_ipv4Get an IPv4 embedded in an IPv6 addressParams : IPv6 Returns : IPv4 string or undef (not found) "$ip4 = ip_get_embedded($ip6);" ip_check_maskCheck the validity of a binary IP maskParams : Mask Returns : 1 or undef (invalid) "ip_check_mask($binmask) or do {};" Checks if mask has only 1s followed by 0s. ip_aggregateAggregate 2 ranges of binary IPsParams : 1st range (1st IP, Last IP), last range (1st IP, last IP), IP version Returns : prefix or undef (invalid) "$prefix = ip_aggregate ($bip1,$eip1,$bip2,$eip2) || die ..." ip_iptypev4Return the type of an IPv4 address.Params: binary IP Returns: type as of the following table or undef (invalid ip) See RFC 5735 and RFC 6598 Address Block Present Use Reference ------------------------------------------------------------------- 0.0.0.0/8 "This" Network RFC 1122 PRIVATE 10.0.0.0/8 Private-Use Networks RFC 1918 PRIVATE 100.64.0.0/10 CGN Shared Address Space RFC 6598 SHARED 127.0.0.0/8 Loopback RFC 1122 LOOPBACK 169.254.0.0/16 Link Local RFC 3927 LINK-LOCAL 172.16.0.0/12 Private-Use Networks RFC 1918 PRIVATE 192.0.0.0/24 IETF Protocol Assignments RFC 5736 RESERVED 192.0.2.0/24 TEST-NET-1 RFC 5737 TEST-NET 192.88.99.0/24 6to4 Relay Anycast RFC 3068 6TO4-RELAY 192.168.0.0/16 Private-Use Networks RFC 1918 PRIVATE 198.18.0.0/15 Network Interconnect Device Benchmark Testing RFC 2544 RESERVED 198.51.100.0/24 TEST-NET-2 RFC 5737 TEST-NET 203.0.113.0/24 TEST-NET-3 RFC 5737 TEST-NET 224.0.0.0/4 Multicast RFC 3171 MULTICAST 240.0.0.0/4 Reserved for Future Use RFC 1112 RESERVED 255.255.255.255/32 Limited Broadcast RFC 919 BROADCAST RFC 922 ip_iptypev6Return the type of an IPv6 address.Params: binary ip Returns: type as of the following table or undef (invalid) See IANA Internet Protocol Version 6 Address Space <http://www.iana.org/assignments/ipv6-address-space/ipv6-address-space.txt> and IANA IPv6 Special Purpose Address Registry <http://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.txt> Prefix Allocation Reference ------------------------------------------------------------- 0000::/8 Reserved by IETF [RFC4291] RESERVED 0100::/8 Reserved by IETF [RFC4291] RESERVED 0200::/7 Reserved by IETF [RFC4048] RESERVED 0400::/6 Reserved by IETF [RFC4291] RESERVED 0800::/5 Reserved by IETF [RFC4291] RESERVED 1000::/4 Reserved by IETF [RFC4291] RESERVED 2000::/3 Global Unicast [RFC4291] GLOBAL-UNICAST 4000::/3 Reserved by IETF [RFC4291] RESERVED 6000::/3 Reserved by IETF [RFC4291] RESERVED 8000::/3 Reserved by IETF [RFC4291] RESERVED A000::/3 Reserved by IETF [RFC4291] RESERVED C000::/3 Reserved by IETF [RFC4291] RESERVED E000::/4 Reserved by IETF [RFC4291] RESERVED F000::/5 Reserved by IETF [RFC4291] RESERVED F800::/6 Reserved by IETF [RFC4291] RESERVED FC00::/7 Unique Local Unicast [RFC4193] UNIQUE-LOCAL-UNICAST FE00::/9 Reserved by IETF [RFC4291] RESERVED FE80::/10 Link Local Unicast [RFC4291] LINK-LOCAL-UNICAST FEC0::/10 Reserved by IETF [RFC3879] RESERVED FF00::/8 Multicast [RFC4291] MULTICAST Prefix Assignment Reference --------------------------------------------------------------------- ::1/128 Loopback Address [RFC4291] UNSPECIFIED ::/128 Unspecified Address [RFC4291] LOOPBACK ::FFFF:0:0/96 IPv4-mapped Address [RFC4291] IPV4MAP 0100::/64 Discard-Only Prefix [RFC6666] DISCARD 2001:0000::/32 TEREDO [RFC4380] TEREDO 2001:0002::/48 BMWG [RFC5180] BMWG 2001:db8::/32 Documentation Prefix [RFC3849] DOCUMENTATION 2001:10::/28 ORCHID [RFC4843] ORCHID 2002::/16 6to4 [RFC3056] 6TO4 FC00::/7 Unique-Local [RFC4193] UNIQUE-LOCAL-UNICAST FE80::/10 Linked-Scoped Unicast [RFC4291] LINK-LOCAL-UNICAST FF00::/8 Multicast [RFC4291] MULTICAST ip_iptypeReturn the type of an IP (Public, Private, Reserved)Params : Binary IP to test, IP version (defaults to 6) Returns : type (see ip_iptypev4 and ip_iptypev6 for details) or undef (invalid) "$type = ip_iptype ($ip);" ip_check_prefixCheck the validity of a prefixParams : binary IP, length of prefix, IP version Returns : 1 or undef (invalid) Checks if the variant part of a prefix only has 0s, and the length is correct. "ip_check_prefix ($ip,$len,$ipv) or do {};" ip_reverseGet a reverse name from a prefixParams : IP, length of prefix, IP version Returns : Reverse name or undef (error) "$reverse = ip_reverse ($ip);" ip_normalizeNormalize data to a range/prefix of IP addressesParams : Data String (Single IP, Range, Prefix) Returns : ip1, ip2 (if range/prefix) or undef (error) "($ip1,$ip2) = ip_normalize ($data);" ip_authReturn IP authority information from the IP::Authority moduleParams : IP, version Returns : Auth info (RI for RIPE, AR for ARIN, etc) "$auth = ip_auth ($ip,4);" Note: IPv4 only BUGSThe Math::BigInt library is needed for functions that use integers. These are ip_inttobin, ip_bintoint, and the size method. In a next version, Math::BigInt will become optionnal.AUTHORSManuel Valente <manuel.valente@gmail.com>.Original IPv4 code by Monica Cortes Sack <mcortes@ripe.net>. Original IPv6 code by Lee Wilmot <lee@ripe.net>. BASED ONipv4pack.pm, iplib.pm, iplibncc.pm.SEE ALSOperl(1), IP::Authority
Visit the GSP FreeBSD Man Page Interface. |