- NAME
- NetAddr::IP::Lite - Manages IPv4 and IPv6 addresses and subnets
-
- SYNOPSIS
- use NetAddr::IP::Lite qw(
- Zeros
- Ones
- V4mask
- V4net
- :aton DEPRECATED !
- :old_nth
- :upper
- :lower
- );
-
- my $ip = new NetAddr::IP::Lite '127.0.0.1';
- or if your prefer
- my $ip = NetAddr::IP::Lite->new('127.0.0.1);
- or from a packed IPv4 address
- my $ip = new_from_aton NetAddr::IP::Lite (inet_aton('127.0.0.1'));
- or from an octal filtered IPv4 address
- my $ip = new_no NetAddr::IP::Lite '127.012.0.0';
-
- print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;
-
- if ($ip->within(new NetAddr::IP::Lite "127.0.0.0", "255.0.0.0")) {
- print "Is a loopback address\n";
- }
-
- # This prints 127.0.0.1/32
- print "You can also say $ip...\n";
-
- The following four functions return ipV6 representations of:
-
- :: = Zeros();
- FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones();
- FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask();
- ::FFFF:FFFF = V4net();
-
- INSTALLATION
- Un-tar the distribution in an appropriate directory and type:
-
- perl Makefile.PL
- make
- make test
- make install
-
- NetAddr::IP::Lite depends on NetAddr::IP::Util which installs by default
- with its primary functions compiled using Perl's XS extensions to build
- a 'C' library. If you do not have a 'C' complier available or would like
- the slower Pure Perl version for some other reason, then type:
-
- perl Makefile.PL -noxs
- make
- make test
- make install
-
- DESCRIPTION
- This module provides an object-oriented abstraction on top of IP
- addresses or IP subnets, that allows for easy manipulations. Most of the
- operations of NetAddr::IP are supported. This module will work older
- versions of Perl and does not use but is compatible with Math::BigInt.
-
- * By default NetAddr::IP functions and methods return string IPv6
- addresses in uppercase. To change that to lowercase:
-
- NOTE: the AUGUST 2010 RFC5952 states:
-
- 4.3. Lowercase
-
- The characters "a", "b", "c", "d", "e", and "f" in an IPv6
- address MUST be represented in lowercase.
-
- It is recommended that all NEW applications using NetAddr::IP::Lite be
- invoked as shown on the next line.
-
- use NetAddr::IP::Lite qw(:lower);
-
- * To ensure the current IPv6 string case behavior even if the default
- changes:
-
- use NetAddr::IP::Lite qw(:upper);
-
- The internal representation of all IP objects is in 128 bit IPv6
- notation. IPv4 and IPv6 objects may be freely mixed.
-
- The supported operations are described below:
-
- Overloaded Operators
-
- Assignment ("=")
- Has been optimized to copy one NetAddr::IP::Lite object to another
- very quickly.
-
- "->copy()"
- The assignment ("=") operation is only put in to operation when the
- copied object is further mutated by another overloaded operation.
- See the overload manpage SPECIAL SYMBOLS FOR "use overload" for
- details.
-
- "->copy()" actually creates a new object when called.
-
- Stringification
- An object can be used just as a string. For instance, the following
- code
-
- my $ip = new NetAddr::IP::Lite '192.168.1.123';
- print "$ip\n";
-
- Will print the string 192.168.1.123/32.
-
- my $ip = new6 NetAddr::IP::Lite '192.168.1.123';
- print "$ip\n";
-
- Will print the string 0:0:0:0:0:0:C0A8:17B/128
-
- Equality
- You can test for equality with either "eq", "ne", "==" or "!=".
- "eq", "ne" allows the comparison with arbitrary strings as well as
- NetAddr::IP::Lite objects. The following example:
-
- if (NetAddr::IP::Lite->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')
- { print "Yes\n"; }
-
- Will print out "Yes".
-
- Comparison with "==" and "!=" requires both operands to be
- NetAddr::IP::Lite objects.
-
- Comparison via >, <, >=, <=, <=> and "cmp"
- Internally, all network objects are represented in 128 bit format.
- The numeric representation of the network is compared through the
- corresponding operation. Comparisons are tried first on the address
- portion of the object and if that is equal then the NUMERIC cidr
- portion of the masks are compared. This leads to the
- counterintuitive result that
-
- /24 > /16
-
- Comparison should not be done on netaddr objects with different CIDR
- as this may produce indeterminate - unexpected results, rather the
- determination of which netblock is larger or smaller should be done
- by comparing
-
- $ip1->masklen <=> $ip2->masklen
-
- Addition of a constant ("+")
- Add a 32 bit signed constant to the address part of a NetAddr
- object. This operation changes the address part to point so many
- hosts above the current objects start address. For instance, this
- code:
-
- print NetAddr::IP::Lite->new('127.0.0.1/8') + 5;
-
- will output 127.0.0.6/8. The address will wrap around at the
- broadcast back to the network address. This code:
-
- print NetAddr::IP::Lite->new('10.0.0.1/24') + 255;
-
- outputs 10.0.0.0/24.
-
- Returns the the unchanged object when the constant is missing or out
- of range.
-
- 2147483647 <= constant >= -2147483648
-
- Subtraction of a constant ("-")
- The complement of the addition of a constant.
-
- Difference ("-")
- Returns the difference between the address parts of two
- NetAddr::IP::Lite objects address parts as a 32 bit signed number.
-
- Returns undef if the difference is out of range.
-
- Auto-increment
- Auto-incrementing a NetAddr::IP::Lite object causes the address part
- to be adjusted to the next host address within the subnet. It will
- wrap at the broadcast address and start again from the network
- address.
-
- Auto-decrement
- Auto-decrementing a NetAddr::IP::Lite object performs exactly the
- opposite of auto-incrementing it, as you would expect.
-
- Methods
-
- "->new([$addr, [ $mask|IPv6 ]])"
- "->new6([$addr, [ $mask]])"
- "->new_no([$addr, [ $mask]])"
- "->new_from_aton($netaddr)"
- new_cis and new_cis6 are DEPRECATED
- "->new_cis("$addr $mask)"
- "->new_cis6("$addr $mask)"
- The first two methods create a new address with the supplied address
- in "$addr" and an optional netmask "$mask", which can be omitted to
- get a /32 or /128 netmask for IPv4 / IPv6 addresses respectively.
-
- The third method "new_no" is exclusively for IPv4 addresses and
- filters improperly formatted dot quad strings for leading 0's that
- would normally be interpreted as octal format by NetAddr per the
- specifications for inet_aton.
-
- new_from_aton takes a packed IPv4 address and assumes a /32 mask.
- This function replaces the DEPRECATED :aton functionality which is
- fundamentally broken.
-
- The last two methods new_cis and new_cis6 differ from new and new6
- only in that they except the common Cisco address notation for
- address/mask pairs with a space as a separator instead of a slash
- (/)
-
- These methods are DEPRECATED because the functionality is now
- included in the other "new" methods
-
- i.e. ->new_cis('1.2.3.0 24')
- or
- ->new_cis6('::1.2.3.0 120')
-
- "->new6" and "->new_cis6" mark the address as being in ipV6 address
- space even if the format would suggest otherwise.
-
- i.e. ->new6('1.2.3.4') will result in ::102:304
-
- addresses submitted to ->new in ipV6 notation will
- remain in that notation permanently. i.e.
- ->new('::1.2.3.4') will result in ::102:304
- whereas new('1.2.3.4') would print out as 1.2.3.4
-
- See "STRINGIFICATION" below.
-
- "$addr" can be almost anything that can be resolved to an IP address
- in all the notations I have seen over time. It can optionally
- contain the mask in CIDR notation. If the OPTIONAL perl module
- Socket6 is available in the local library it will autoload and ipV6
- host6 names will be resolved as well as ipV4 hostnames.
-
- prefix notation is understood, with the limitation that the range
- specified by the prefix must match with a valid subnet.
-
- Addresses in the same format returned by "inet_aton" or
- "gethostbyname" can also be understood, although no mask can be
- specified for them. The default is to not attempt to recognize this
- format, as it seems to be seldom used.
-
- ###### DEPRECATED, will be remove in version 5 ############ To
- accept addresses in that format, invoke the module as in
-
- use NetAddr::IP::Lite ':aton'
-
- ###### USE new_from_aton instead ##########################
-
- If called with no arguments, 'default' is assumed.
-
- "$addr" can be any of the following and possibly more...
-
- n.n
- n.n/mm
- n.n mm
- n.n.n
- n.n.n/mm
- n.n.n mm
- n.n.n.n
- n.n.n.n/mm 32 bit cidr notation
- n.n.n.n mm
- n.n.n.n/m.m.m.m
- n.n.n.n m.m.m.m
- loopback, localhost, broadcast, any, default
- x.x.x.x/host
- 0xABCDEF, 0b111111000101011110, (or a bcd number)
- a netaddr as returned by 'inet_aton'
-
- Any RFC1884 notation
-
- ::n.n.n.n
- ::n.n.n.n/mmm 128 bit cidr notation
- ::n.n.n.n/::m.m.m.m
- ::x:x
- ::x:x/mmm
- x:x:x:x:x:x:x:x
- x:x:x:x:x:x:x:x/mmm
- x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation
- loopback, localhost, unspecified, any, default
- ::x:x/host
- 0xABCDEF, 0b111111000101011110 within the limits
- of perl's number resolution
- 123456789012 a 'big' bcd number (bigger than perl likes)
- and Math::BigInt
-
- If called with no arguments, 'default' is assumed.
-
- "->broadcast()"
- Returns a new object referring to the broadcast address of a given
- subnet. The broadcast address has all ones in all the bit positions
- where the netmask has zero bits. This is normally used to address
- all the hosts in a given subnet.
-
- "->network()"
- Returns a new object referring to the network address of a given
- subnet. A network address has all zero bits where the bits of the
- netmask are zero. Normally this is used to refer to a subnet.
-
- "->addr()"
- Returns a scalar with the address part of the object as an IPv4 or
- IPv6 text string as appropriate. This is useful for printing or for
- passing the address part of the NetAddr::IP::Lite object to other
- components that expect an IP address. If the object is an ipV6
- address or was created using ->new6($ip) it will be reported in ipV6
- hex format otherwise it will be reported in dot quad format only if
- it resides in ipV4 address space.
-
- "->mask()"
- Returns a scalar with the mask as an IPv4 or IPv6 text string as
- described above.
-
- "->masklen()"
- Returns a scalar the number of one bits in the mask.
-
- "->bits()"
- Returns the width of the address in bits. Normally 32 for v4 and 128
- for v6.
-
- "->version()"
- Returns the version of the address or subnet. Currently this can be
- either 4 or 6.
-
- "->cidr()"
- Returns a scalar with the address and mask in CIDR notation. A
- NetAddr::IP::Lite object *stringifies* to the result of this
- function. (see comments about ->new6() and ->addr() for output
- formats)
-
- "->aton()"
- Returns the address part of the NetAddr::IP::Lite object in the same
- format as the "inet_aton()" or "ipv6_aton" function respectively. If
- the object was created using ->new6($ip), the address returned will
- always be in ipV6 format, even for addresses in ipV4 address space.
-
- "->range()"
- Returns a scalar with the base address and the broadcast address
- separated by a dash and spaces. This is called range notation.
-
- "->numeric()"
- When called in a scalar context, will return a numeric
- representation of the address part of the IP address. When called in
- an array contest, it returns a list of two elements. The first
- element is as described, the second element is the numeric
- representation of the netmask.
-
- This method is essential for serializing the representation of a
- subnet.
-
- "->bigint()"
- When called in a scalar context, will return a Math::BigInt
- representation of the address part of the IP address. When called in
- an array contest, it returns a list of two elements. The first
- element is as described, the second element is the Math::BigInt
- representation of the netmask.
-
- "$me->contains($other)"
- Returns true when "$me" completely contains "$other". False is
- returned otherwise and "undef" is returned if "$me" and "$other" are
- not both "NetAddr::IP::Lite" objects.
-
- "$me->within($other)"
- The complement of "->contains()". Returns true when "$me" is
- completely contained within "$other", undef if "$me" and "$other"
- are not both "NetAddr::IP::Lite" objects.
-
- "->first()"
- Returns a new object representing the first usable IP address within
- the subnet (ie, the first host address).
-
- "->last()"
- Returns a new object representing the last usable IP address within
- the subnet (ie, one less than the broadcast address).
-
- "->nth($index)"
- Returns a new object representing the *n*-th usable IP address
- within the subnet (ie, the *n*-th host address). If no address is
- available (for example, when the network is too small for "$index"
- hosts), "undef" is returned.
-
- Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
- implements "->nth($index)" and "->num()" exactly as the
- documentation states. Previous versions behaved slightly differently
- and not in a consistent manner.
-
- To use the old behavior for "->nth($index)" and "->num()":
-
- use NetAddr::IP::Lite qw(:old_nth);
-
- old behavior:
- NetAddr::IP->new('10/32')->nth(0) == undef
- NetAddr::IP->new('10/32')->nth(1) == undef
- NetAddr::IP->new('10/31')->nth(0) == undef
- NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31
- NetAddr::IP->new('10/30')->nth(0) == undef
- NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30
- NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30
- NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30
-
- Note that in each case, the broadcast address is represented in the
- output set and that the 'zero'th index is alway undef except for a
- point-to-point /31 or /127 network where there are exactly two
- addresses in the network.
-
- new behavior:
- NetAddr::IP->new('10/32')->nth(0) == 10.0.0.0/32
- NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32
- NetAddr::IP->new('10/31')->nth(0) == 10.0.0.0/32
- NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/32
- NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30
- NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30
- NetAddr::IP->new('10/30')->nth(2) == undef
-
- Note that a /32 net always has 1 usable address while a /31 has
- exactly two usable addresses for point-to-point addressing. The
- first index (0) returns the address immediately following the
- network address except for a /31 or /127 when it return the network
- address.
-
- "->num()"
- As of version 4.42 of NetAddr::IP and version 1.27 of
- NetAddr::IP::Lite a /31 and /127 with return a net num value of 2
- instead of 0 (zero) for point-to-point networks.
-
- Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
- return the number of usable IP addresses within the subnet, not
- counting the broadcast or network address.
-
- Previous versions worked only for ipV4 addresses, returned a maximum
- span of 2**32 and returned the number of IP addresses not counting
- the broadcast address. (one greater than the new behavior)
-
- To use the old behavior for "->nth($index)" and "->num()":
-
- use NetAddr::IP::Lite qw(:old_nth);
-
- WARNING:
-
- NetAddr::IP will calculate and return a numeric string for network
- ranges as large as 2**128. These values are TEXT strings and perl
- can treat them as integers for numeric calculations.
-
- Perl on 32 bit platforms only handles integer numbers up to 2**32
- and on 64 bit platforms to 2**64.
-
- If you wish to manipulate numeric strings returned by NetAddr::IP
- that are larger than 2**32 or 2**64, respectively, you must load
- additional modules such as Math::BigInt, bignum or some similar
- package to do the integer math.
-
- EXPORT_OK
- Zeros
- Ones
- V4mask
- V4net
- :aton DEPRECATED
- :old_nth
- :upper
- :lower
-
- AUTHORS
- Luis E. Muñoz <luismunoz@cpan.org>, Michael Robinton
- <michael@bizsystems.com>
-
- WARRANTY
- This software comes with the same warranty as perl itself (ie, none), so
- by using it you accept any and all the liability.
-
- COPYRIGHT
- This software is (c) Luis E. Muñoz, 1999 - 2005
- and (c) Michael Robinton, 2006 - 2011.
-
- All rights reserved.
-
- This program is free software; you can redistribute it and/or modify it
- under the terms of either:
-
- a) the GNU General Public License as published by the Free
- Software Foundation; either version 2, or (at your option) any
- later version, or
-
- b) the "Artistic License" which comes with this distribution.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
- General Public License or the Artistic License for more details.
-
- You should have received a copy of the Artistic License with this
- distribution, in the file named "Artistic". If not, I'll be glad to
- provide one.
-
- You should also have received a copy of the GNU General Public License
- along with this program in the file named "Copying". If not, write to
- the
-
- Free Software Foundation, Inc.
- 59 Temple Place, Suite 330
- Boston, MA 02111-1307, USA
-
- or visit their web page on the internet at:
-
- http://www.gnu.org/copyleft/gpl.html.
-
- SEE ALSO
- NetAddr::IP(3), NetAddr::IP::Util(3), NetAddr::IP::InetBase(3)
-