Fork: 0
x-way / NetAddr-IP
Transfer to URL with SHA Find file
Newer
Older
NetAddr-IP / Lite / README
@Luis Muñoz Luis Muñoz on 21 Oct 2014 13 KB Import of LUISMUNOZ/NetAddr-IP-4.003 from CPAN.
Raw Blame History 
  1. NAME
  2.     NetAddr::IP::Lite - Manages IPv4 and IPv6 addresses and subnets
  3.  
  4. SYNOPSIS
  5.       use NetAddr::IP::Lite qw(
  6.             Zeros
  7.             Ones
  8.             V4mask
  9.             V4net
  10.             :aton
  11.             :old_nth
  12.       );
  13.  
  14.       my $ip = new NetAddr::IP::Lite '127.0.0.1';
  15.  
  16.       print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;
  17.  
  18.       if ($ip->within(new NetAddr::IP::Lite "127.0.0.0", "255.0.0.0")) {
  19.           print "Is a loopback address\n";
  20.       }
  21.  
  22.                                     # This prints 127.0.0.1/32
  23.       print "You can also say $ip...\n";
  24.  
  25.       The following four functions return ipV6 representations of:
  26.  
  27.       ::                                       = Zeros();
  28.       FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF: = Ones();
  29.       FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::          = V4mask();
  30.       ::FFFF:FFFF                              = V4net();
  31.  
  32. INSTALLATION
  33.     Un-tar the distribution in an appropriate directory and type:
  34.  
  35.             perl Makefile.PL
  36.             make
  37.             make test
  38.             make install
  39.  
  40.     NetAddr::IP::Lite depends on NetAddr::IP::Util which installs by default
  41.     with its primary functions compiled using Perl's XS extensions to build
  42.     a 'C' library. If you do not have a 'C' complier available or would like
  43.     the slower Pure Perl version for some other reason, then type:
  44.  
  45.             perl Makefile.PL -noxs
  46.             make
  47.             make test
  48.             make install
  49.  
  50. DESCRIPTION
  51.     This module provides an object-oriented abstraction on top of IP
  52.     addresses or IP subnets, that allows for easy manipulations. Most of the
  53.     operations of NetAddr::IP are supported. This module will work older
  54.     versions of Perl and does not use Math::BigInt.
  55.  
  56.     The internal representation of all IP objects is in 128 bit IPv6
  57.     notation. IPv4 and IPv6 objects may be freely mixed.
  58.  
  59.     The supported operations are described below:
  60.  
  61.   Overloaded Operators
  62.     Assignment ("=")
  63.         Has been optimized to copy one NetAddr::IP::Lite object to another
  64.         very quickly.
  65.  
  66.     "->copy()"
  67.         The assignment ("=") operation is only put in to operation when the
  68.         copied object is further mutated by another overloaded operation.
  69.         See overload SPECIAL SYMBOLS FOR "use overload" for details.
  70.  
  71.         "->copy()" actually creates a new object when called.
  72.  
  73.     Stringification
  74.         An object can be used just as a string. For instance, the following
  75.         code
  76.  
  77.                 my $ip = new NetAddr::IP::Lite '192.168.1.123';
  78.                 print "$ip\n";
  79.  
  80.         Will print the string 192.168.1.123/32.
  81.  
  82.                 my $ip = new6 NetAddr::IP::Lite '192.168.1.123';
  83.                 print "$ip\n";
  84.  
  85.         Will print the string
  86.  
  87.     Equality
  88.         You can test for equality with either "eq" or "==". "eq" allows the
  89.         comparison with arbitrary strings as well as NetAddr::IP::Lite
  90.         objects. The following example:
  91.  
  92.             if (NetAddr::IP::Lite->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8') 
  93.                { print "Yes\n"; }
  94.  
  95.         Will print out "Yes".
  96.  
  97.         Comparison with "==" requires both operands to be NetAddr::IP::Lite
  98.         objects.
  99.  
  100.         In both cases, a true value is returned if the CIDR representation
  101.         of the operands is equal.
  102.  
  103.     Comparison via >, <, >=, <=, <=> and "cmp"
  104.         Internally, all network objects are represented in 128 bit format.
  105.         The numeric representation of the network is compared through the
  106.         corresponding operation. Comparisons are tried first on the address
  107.         portion of the object and if that is equal then the cidr portion of
  108.         the masks are compared.
  109.  
  110.     Addition of a constant
  111.         Adding a constant to a NetAddr::IP::Lite object changes its address
  112.         part to point to the one so many hosts above the start address. For
  113.         instance, this code:
  114.  
  115.             print NetAddr::IP::Lite->new('127.0.0.1') + 5;
  116.  
  117.         will output 127.0.0.6/8. The address will wrap around at the
  118.         broadcast back to the network address. This code:
  119.  
  120.             print NetAddr::IP::Lite->new('10.0.0.1/24') + 255;
  121.  
  122.         outputs 10.0.0.0/24.
  123.  
  124.     Substraction of a constant
  125.         The complement of the addition of a constant.
  126.  
  127.     Auto-increment
  128.         Auto-incrementing a NetAddr::IP::Lite object causes the address part
  129.         to be adjusted to the next host address within the subnet. It will
  130.         wrap at the broadcast address and start again from the network
  131.         address.
  132.  
  133.     Auto-decrement
  134.         Auto-decrementing a NetAddr::IP::Lite object performs exactly the
  135.         opposite of auto-incrementing it, as you would expect.
  136.  
  137.   Methods
  138.     "->new([$addr, [ $mask|IPv6 ]])"
  139.     "->new6([$addr, [ $mask]])"
  140.         These methods creates a new address with the supplied address in
  141.         $addr and an optional netmask $mask, which can be omitted to get a
  142.         /32 or /128 netmask for IPv4 / IPv6 addresses respectively
  143.  
  144.         "->new6" marks the address as being in ipV6 address space even if
  145.         the format would suggest otherwise.
  146.  
  147.           i.e.  ->new6('1.2.3.4') will result in ::102:304
  148.  
  149.           addresses submitted to ->new in ipV6 notation will
  150.           remain in that notation permanently. i.e.
  151.                 ->new('::1.2.3.4') will result in ::102:304
  152.           whereas new('1.2.3.4') would print out as 1.2.3.4
  153.  
  154.           See "STRINGIFICATION" below.
  155.  
  156.         $addr can be almost anything that can be resolved to an IP address
  157.         in all the notations I have seen over time. It can optionally
  158.         contain the mask in CIDR notation.
  159.  
  160.         prefix notation is understood, with the limitation that the range
  161.         speficied by the prefix must match with a valid subnet.
  162.  
  163.         Addresses in the same format returned by "inet_aton" or
  164.         "gethostbyname" can also be understood, although no mask can be
  165.         specified for them. The default is to not attempt to recognize this
  166.         format, as it seems to be seldom used.
  167.  
  168.         To accept addresses in that format, invoke the module as in
  169.  
  170.           use NetAddr::IP::Lite ':aton'
  171.  
  172.         If called with no arguments, 'default' is assumed.
  173.  
  174.         $addr can be any of the following and possibly more...
  175.  
  176.           n.n
  177.           n.n/mm
  178.           n.n.n
  179.           n.n.n/mm
  180.           n.n.n.n
  181.           n.n.n.n/mm            32 bit cidr notation
  182.           n.n.n.n/m.m.m.m
  183.           loopback, localhost, broadcast, any, default
  184.           x.x.x.x/host
  185.           0xABCDEF, 0b111111000101011110, (a bcd number)
  186.           a netaddr as returned by 'inet_aton'
  187.  
  188.         Any RFC1884 notation
  189.  
  190.           ::n.n.n.n
  191.           ::n.n.n.n/mmm         128 bit cidr notation
  192.           ::n.n.n.n/::m.m.m.m
  193.           ::x:x
  194.           ::x:x/mmm
  195.           x:x:x:x:x:x:x:x
  196.           x:x:x:x:x:x:x:x/mmm
  197.           x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation
  198.           loopback, localhost, unspecified, any, default
  199.           ::x:x/host
  200.           0xABCDEF, 0b111111000101011110 within the limits
  201.           of perl's number resolution
  202.           123456789012  a 'big' bcd number i.e. Math::BigInt
  203.  
  204.         If called with no arguments, 'default' is assumed.
  205.  
  206.     "->broadcast()"
  207.         Returns a new object refering to the broadcast address of a given
  208.         subnet. The broadcast address has all ones in all the bit positions
  209.         where the netmask has zero bits. This is normally used to address
  210.         all the hosts in a given subnet.
  211.  
  212.     "->network()"
  213.         Returns a new object refering to the network address of a given
  214.         subnet. A network address has all zero bits where the bits of the
  215.         netmask are zero. Normally this is used to refer to a subnet.
  216.  
  217.     "->addr()"
  218.         Returns a scalar with the address part of the object as an IPv4 or
  219.         IPv6 text string as appropriate. This is useful for printing or for
  220.         passing the address part of the NetAddr::IP::Lite object to other
  221.         components that expect an IP address. If the object is an ipV6
  222.         address or was created using ->new6($ip) it will be reported in ipV6
  223.         hex format otherwise it will be reported in dot quad format only if
  224.         it resides in ipV4 address space.
  225.  
  226.     "->mask()"
  227.         Returns a scalar with the mask as an IPv4 or IPv6 text string as
  228.         described above.
  229.  
  230.     "->masklen()"
  231.         Returns a scalar the number of one bits in the mask.
  232.  
  233.     "->bits()"
  234.         Returns the width of the address in bits. Normally 32 for v4 and 128
  235.         for v6.
  236.  
  237.     "->version()"
  238.         Returns the version of the address or subnet. Currently this can be
  239.         either 4 or 6.
  240.  
  241.     "->cidr()"
  242.         Returns a scalar with the address and mask in CIDR notation. A
  243.         NetAddr::IP::Lite object *stringifies* to the result of this
  244.         function. (see comments about ->new6() and ->addr() for output
  245.         formats)
  246.  
  247.     "->aton()"
  248.         Returns the address part of the NetAddr::IP::Lite object in the same
  249.         format as the "inet_aton()" or "ipv6_aton" function respectively. If
  250.         the object was created using ->new6($ip), the address returned will
  251.         always be in ipV6 format, even for addresses in ipV4 address space.
  252.  
  253.     "->range()"
  254.         Returns a scalar with the base address and the broadcast address
  255.         separated by a dash and spaces. This is called range notation.
  256.  
  257.     "->numeric()"
  258.         When called in a scalar context, will return a numeric
  259.         representation of the address part of the IP address. When called in
  260.         an array contest, it returns a list of two elements. The first
  261.         element is as described, the second element is the numeric
  262.         representation of the netmask.
  263.  
  264.         This method is essential for serializing the representation of a
  265.         subnet.
  266.  
  267.     "$me->contains($other)"
  268.         Returns true when $me completely contains $other. False is returned
  269.         otherwise and "undef" is returned if $me and $other are not both
  270.         "NetAddr::IP::Lite" objects.
  271.  
  272.     "$me->within($other)"
  273.         The complement of "->contains()". Returns true when $me is
  274.         completely contained within $other, undef if $me and $other are not
  275.         both "NetAddr::IP::Lite" objects.
  276.  
  277.     "->first()"
  278.         Returns a new object representing the first usable IP address within
  279.         the subnet (ie, the first host address).
  280.  
  281.     "->last()"
  282.         Returns a new object representing the last usable IP address within
  283.         the subnet (ie, one less than the broadcast address).
  284.  
  285.     "->nth($index)"
  286.         Returns a new object representing the *n*-th usable IP address
  287.         within the subnet (ie, the *n*-th host address). If no address is
  288.         available (for example, when the network is too small for $index
  289.         hosts), "undef" is returned.
  290.  
  291.         Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
  292.         implements "->nth($index)" and "->num()" exactly as the
  293.         documentation states. Previous versions behaved slightly differently
  294.         and not in a consistent manner.
  295.  
  296.         To use the old behavior for "->nth($index)" and "->num()":
  297.  
  298.           use NetAddr::IP::Lite qw(:old_nth);
  299.  
  300.           old behavior:
  301.           NetAddr::IP->new('10/32')->nth(0) == undef
  302.           NetAddr::IP->new('10/32')->nth(1) == undef
  303.           NetAddr::IP->new('10/31')->nth(0) == undef  
  304.           NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31
  305.           NetAddr::IP->new('10/30')->nth(0) == undef  
  306.           NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30
  307.           NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30
  308.           NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30
  309.  
  310.         Note that in each case, the broadcast address is represented in the
  311.         output set and that the 'zero'th index is alway undef.
  312.  
  313.           new behavior:
  314.           NetAddr::IP->new('10/32')->nth(0)  == 10.0.0.0/32
  315.           NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32
  316.           NetAddr::IP->new('10/31')->nth(0)  == undef  
  317.           NetAddr::IP->new('10/31')->nth(1)  == undef
  318.           NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30
  319.           NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30
  320.           NetAddr::IP->new('10/30')->nth(2) == undef
  321.  
  322.         Note that a /32 net always has 1 usable address while a /31 has none
  323.         since it has a network and broadcast address, but no host addresses.
  324.         The first index (0) returns the address immediately following the
  325.         network address.
  326.  
  327.     "->num()"
  328.         Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
  329.         Returns the number of usable addresses IP addresses within the
  330.         subnet, not counting the broadcast or network address. Previous
  331.         versions returned th number of IP addresses not counting the
  332.         broadcast address.
  333.  
  334.         To use the old behavior for "->nth($index)" and "->num()":
  335.  
  336.           use NetAddr::IP::Lite qw(:old_nth);
  337.  
  338. EXPORT_OK
  339.             Zero
  340.             Ones
  341.             V4mask
  342.             V4net
  343.             :aton
  344.             :old_nth
  345.  
  346. AUTHOR
  347.     Luis E. Muñoz <luismunoz@cpan.org>, Michael Robinton
  348.     <michael@bizsystems.com>
  349.  
  350. WARRANTY
  351.     This software comes with the same warranty as perl itself (ie, none), so
  352.     by using it you accept any and all the liability.
  353.  
  354. LICENSE
  355.     This software is (c) Luis E. Muñoz, 1999 - 2005, and (c) Michael
  356.     Robinton, 2006. It can be used under the terms of the perl artistic
  357.     license provided that proper credit for the work of the author is
  358.     preserved in the form of this copyright notice and license for this
  359.     module.
  360.  
  361. SEE ALSO
  362.     perl(1), NetAddr::IP(3), NetAddr::IP::Util(3)
  363.