Net::IP man page on ElementaryOS

Man page or keyword search:  
man Server   4994 pages
apropos Keyword Search (all sections)
Output format
ElementaryOS logo
[printable version]

IP(3pm)		      User Contributed Perl Documentation	       IP(3pm)

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

SYNOPSIS
	 use 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");

DESCRIPTION
       This 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 INTERFACE
   Object Creation
       A 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 METHODS
       Most 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.

   set
       Set 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.

   error
       Return 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 available.

       "warn ($ip->error());"

   errno
       Return 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());"

   ip
       Return the IP address (or first IP of the prefix or range) in quad
       format, as a string.

       "print ($ip->ip());"

   binip
       Return the IP address as a binary string of 0s and 1s.

       "print ($ip->binip());"

   prefixlen
       Return the length in bits of the current prefix.

       "print ($ip->prefixlen());"

   version
       Return the version of the current IP object (4 or 6).

       "print ($ip->version());"

   size
       Return the number of IP addresses in the current prefix or range.  Use
       of this function requires Math::BigInt.

       "print ($ip->size());"

   binmask
       Return the binary mask of the current prefix, if applicable.

       "print ($ip->binmask());"

   mask
       Return the mask in quad format of the current prefix.

       "print ($ip->mask());"

   prefix
       Return the full prefix (ip+prefix length) in quad (standard) format.

       "print ($ip->prefix());"

   print
       Print the IP object (IP/Prefix or First - Last)

       "print ($ip->print());"

   intip
       Convert the IP in integer format and return it as a Math::BigInt
       object.

       "print ($ip->intip());"

   hexip
       Return the IP in hex format

       "print ($ip->hexip());"

   hexmask
       Return the mask in hex format

       "print ($ip->hexmask());"

   short
       Return the IP in short format:	   IPv4 addresses: 194.5/16	 IPv6
       addresses: ab32:f000::

       "print ($ip->short());"

   iptype
       Return 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_ip
       Return the reverse IP for a given IP address (in.addr. format).

       "print ($ip->reserve_ip());"

   last_ip
       Return the last IP of a prefix/range in quad format.

       "print ($ip->last_ip());"

   last_bin
       Return the last IP of a prefix/range in binary format.

       "print ($ip->last_bin());"

   last_int
       Return the last IP of a prefix/range in integer format.

       "print ($ip->last_int());"

   find_prefixes
       This 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));"

   bincomp
       Binary 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) {...}"

   binadd
       Binary addition of two IP objects. The value returned is an IP object.

       "my $sum = $ip->binadd($ip2);"

   aggregate
       Aggregate 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);"

   overlaps
       Check 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) {...};"

   looping
       The "+" 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.

   auth
       Return IP authority information from the IP::Authority module

       "$auth = ip-"auth ();>

       Note: IPv4 only

PROCEDURAL INTERFACE
       These 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);"

   Error
       Returns 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();

   Errno
       Returns a numeric error code corresponding to the error string returned
       by Error.

   ip_iptobin
       Transform 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_bintoip
       Transform a bit string into an IP address

	   Params  : binary IP, IP version
	   Returns : IP address on success, undef otherwise

       "$ip = ip_bintoip ($binip,6);"

   ip_bintoint
       Transform a bit string into a BigInt.

	   Params  : binary IP
	   Returns : BigInt

       "$bigint = new Math::BigInt (ip_bintoint($binip));"

   ip_inttobin
       Transform 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_version
       Try 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_ipv4
       Check 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_ipv6
       Check 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_address
       Expand 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_mask
       Get IP mask from prefix length.

	   Params  : Prefix length, IP version
	   Returns : Binary Mask

       "$mask = ip_get_mask ($len,6);"

   ip_last_address_bin
       Return 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_splitprefix
       Split a prefix into IP and prefix length.  If it was passed a simple
       IP, it just returns it.

	   Params  : Prefix
	   Returns : IP, optionally length of prefix

       "($ip,$len) = ip_splitprefix ($prefix)"

   ip_prefix_to_range
       Get 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_bincomp
       Compare 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_binadd
       Add two binary IPs.

	   Params  : First binary IP, Last binary IP
	   Returns : Binary sum or undef (problem)

       "$binip = ip_binadd ($bin1,$bin2);"

   ip_get_prefix_length
       Get 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_prefix
       Return 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_prefix
       Compress an IPv4 Prefix.

	   Params  : IP, Prefix length
	   Returns : Compressed Prefix

       "$ip = ip_compress_v4_prefix ($ip, $len);"

   ip_compress_address
       Compress 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_overlap
       Check 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_ipv4
       Get an IPv4 embedded in an IPv6 address

	   Params  : IPv6
	   Returns : IPv4 string or undef (not found)

       "$ip4 = ip_get_embedded($ip6);"

   ip_check_mask
       Check the validity of a binary IP mask

	   Params  : Mask
	   Returns : 1 or undef (invalid)

       "ip_check_mask($binmask) or do {};"

       Checks if mask has only 1s followed by 0s.

   ip_aggregate
       Aggregate 2 ranges of binary IPs

	   Params  : 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_iptypev4
       Return 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_iptypev6
       Return 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_iptype
       Return 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_prefix
       Check the validity of a prefix

	   Params  : 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_reverse
       Get a reverse name from a prefix

	   Params  : IP, length of prefix, IP version
	   Returns : Reverse name or undef (error)

       "$reverse = ip_reverse ($ip);"

   ip_normalize
       Normalize data to a range/prefix of IP addresses

	   Params  : Data String (Single IP, Range, Prefix)
	   Returns : ip1, ip2 (if range/prefix) or undef (error)

       "($ip1,$ip2) = ip_normalize ($data);"

   ip_auth
       Return IP authority information from the IP::Authority module

	   Params  : IP, version
	   Returns : Auth info (RI for RIPE, AR for ARIN, etc)

       "$auth = ip_auth ($ip,4);"

       Note: IPv4 only

BUGS
       The 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 optional.

AUTHORS
       Manuel 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 ON
       ipv4pack.pm, iplib.pm, iplibncc.pm.

SEE ALSO
       perl(1), IP::Authority

perl v5.14.2			  2012-12-15			       IP(3pm)
[top]

List of man pages available for ElementaryOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net