NAME

NetAddr::IP::Lite - Manages IPv4 and IPv6 addresses and subnets (lightweight)

VERSION

version 4.080_07

SYNOPSIS

use NetAddr::IP::Lite qw(
    Zeros
    Ones
    V4mask
    V4net
);
use NetAddr::IP::Util qw(inet_aton ipv6_n2x);

my $ip = NetAddr::IP::Lite->new('192.0.2.1');
# from a packed IPv4 address
my $a = NetAddr::IP::Lite->new_from_aton(inet_aton('192.0.2.1'));   # 192.0.2.1/32
# leading zeros read as decimal
my $b = NetAddr::IP::Lite->new_no('198.051.100.001');               # 198.51.100.1/32

print 'The address is ', $ip->addr, ' with mask ', $ip->mask, "\n" ;
# The address is 192.0.2.1 with mask 255.255.255.255

if ($ip->within(NetAddr::IP::Lite->new('192.0.2.0', '255.255.255.224'))) {
    print "Is within 192.0.2.0/27\n";      # Is within 192.0.2.0/27
}

print "You can also say $ip...\n";       # You can also say 192.0.2.1/32...

# The following four functions return 128-bit vectors; this shows
# their string form via ipv6_n2x():
print ipv6_n2x(Zeros()), "\n";      # 0:0:0:0:0:0:0:0
print ipv6_n2x(Ones()), "\n";       # FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF
print ipv6_n2x(V4mask()), "\n";     # FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:0:0
print ipv6_n2x(V4net()), "\n";      # 0:0:0:0:0:0:FFFF:FFFF

DESCRIPTION

The build steps, including the pure Perl mode, are in README.md. This module does not choose how it was built; mode() from NetAddr::IP::Util reports which implementation is active.

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. It is compatible with Math::BigInt, and requires perl 5.14 or later.

This module is the base class of NetAddr::IP. It has the constructors, the accessors, the containment tests, the host counts and every operator except @{}. The rest is in NetAddr::IP only: the text forms short, canon, full, full6, full6m, prefix, nprefix and wildcard, the splitting and set operations, hostenum, hostenumref, re, re6 and netlimit.

Once NetAddr::IP is loaded, a NetAddr::IP::Lite object can call those methods too, because the AUTOLOAD in this module passes the call on to NetAddr::IP. Before that the call dies:

use NetAddr::IP::Lite;

my $ip = NetAddr::IP::Lite->new('192.0.2.0/30');
print eval { $ip->hostenum; 1 } ? "works\n" : "dies\n";   # dies
require NetAddr::IP;
print join(' ', $ip->hostenum), "\n";   # 192.0.2.1/32 192.0.2.2/32

* IPv6 text comes back in uppercase unless :lower is imported.

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 keep uppercase whatever the default becomes:

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 overload SPECIAL SYMBOLS FOR "use overload" for details.

Calling ->copy() actually creates a new object.

Stringification

An object can be used just as a string. For instance, the following code

my $ip = NetAddr::IP::Lite->new('192.0.2.123');
    print "$ip\n";

Will print the string 192.0.2.123/32.

my $ip = NetAddr::IP::Lite->new6('192.0.2.123');
print "$ip\n";

Will print the string 0:0:0:0:0:0:C000:27B/128

Equality

You can test for equality with either eq, ne, == or !=. The eq and ne operators allow comparison with arbitrary strings as well as NetAddr::IP::Lite objects. The following example:

if (NetAddr::IP::Lite->new('198.51.100.1','255.255.255.224') eq '198.51.100.1/27')
    { 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, and the comparison runs on that numeric form. The order is deterministic: the address portion first, then, when the addresses are equal, the numeric value of the masks. Since a longer mask is the larger number, this leads to the counterintuitive result that

/24 > /16

The same order applies to sort:

my @nets = map { NetAddr::IP::Lite->new($_) }
    qw(192.0.2.1/32 192.0.2.1/8 192.0.2.1/24 192.0.2.1/16);
print join(', ', sort @nets), "\n";
# 192.0.2.1/8, 192.0.2.1/16, 192.0.2.1/24, 192.0.2.1/32

So the ordering is predictable, but it is not the ordering most people mean by "bigger". To rank netblocks by size, compare the mask lengths directly:

$ip1->masklen <=> $ip2->masklen

Against an operand that is not a NetAddr::IP::Lite object, such as a string, a number or undef, <=> returns undef, as Perl's own <=> does for NaN, and >, <, >= and <= return false, as == does. An undef variable used as that operand stays undef. The cmp operator compares the CIDR text with the operand instead, as eq does, so lt, gt, le and ge agree with eq:

my $ip = NetAddr::IP::Lite->new('192.0.2.1');
$ip <=> '192.0.2.1';      # undef
$ip <   '192.0.2.1';      # false
$ip cmp '192.0.2.1/32';   # 0

Addition of a constant (+)

Add a signed integer 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('203.0.113.1/24') + 5;

will output 203.0.113.6/24. The address wraps around at the broadcast back to the network address, so this code:

print NetAddr::IP::Lite->new('203.0.113.1/24') + 255;

outputs 203.0.113.0/24.

Returns a copy of the object when the constant is missing or zero. The constant must be an integer with a magnitude below 2**64; anything else croaks, including a string that is not a number, such as '0x10'. Values above 2**53 must be passed as integers (IV or UV), since a floating point value that large has no unit precision and is rejected.

Subtraction of a constant (-)

The complement of the addition of a constant.

The object must be the left operand. Subtracting an object from a constant (10 - $ip) has no meaning and croaks.

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.

Negation and absolute value (- and abs)

Both croak. An address has no meaningful negation, and abs would be the identity at best:

-$ip;      # cannot negate a NetAddr::IP::Lite object
abs $ip;   # cannot take the absolute value of a NetAddr::IP::Lite object

To move to another address, add or subtract a constant with the overloaded + and -, or use nth().

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.

Constructors

->new([$addr, [ $mask|IPv6 ]])

->new4([$addr, [ $mask]])

->new6([$addr, [ $mask]])

->new6FFFF([$addr, [ $mask]])

->new_no([$addr, [ $mask]])

->new_from_aton($netaddr)

->new_cis("$addr $mask")

->new_cis6("$addr $mask")

The constructors new, new4 and new6 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. All three accept the same notations. The new constructor returns whichever family the input reads as, new4 returns IPv4 or undef, and new6 returns IPv6. See "Numbers and masks" for how each one reads a number and a mask.

The third constructor, new6FFFF, is what makes an IPv4-mapped address, RFC 4291 s2.5.5.2. An IPv4 address, whether dotted, short, a range or a number of up to 32 bits, comes back inside ::ffff:0:0/96, so a /24 becomes a /120. An IPv6 address comes back as new6 gives it: NetAddr::IP::Lite->new6FFFF('192.0.2.1'); # 0:0:0:0:0:FFFF:C000:201/128 NetAddr::IP::Lite->new6FFFF('192.0.2.0/24'); # 0:0:0:0:0:FFFF:C000:200/120 NetAddr::IP::Lite->new6FFFF('2001:db8::1'); # 2001:DB8:0:0:0:0:0:1/128 NetAddr::IP::Lite->new6FFFF('::192.0.2.1'); # 0:0:0:0:0:0:C000:201/128

IPv6 text such as ::192.0.2.1 is an IPv6 address, and so are a number wider than 32 bits and the keywords, such as loopback, which new6 reads as IPv6. A host name follows the address it resolves to.

An IPv4 address with a leading zero in any part, such as 192.0.2.010 or 010, is not an address to new: the C library's inet_aton reads 010 as octal 8, and a person reads it as decimal 10. So is the upper bound of a short range, such as 192.0.2.8-011, and a negative number, such as -012. The constructor for that less strict reading is new_no. A part that is not an address once the zeros are removed is still refused. The result, or undef when the text is not an address:

input           new                new_no
192.0.2.1       192.0.2.1/32       192.0.2.1/32
192.0.2.010     undef              192.0.2.10/32
192.0.2.07      undef              192.0.2.7/32
192.0.2.107     192.0.2.107/32     192.0.2.107/32
192.0.2.0107    undef              192.0.2.107/32
010             undef              0.0.0.10/32
192.0.2.0256    undef              undef
192.0.2.8-011   undef              192.0.2.8/30
-012            undef              255.255.255.244/32

Under new_no, 192.0.2.07 is 192.0.2.7, so a typo for 192.0.2.107 succeeds. Likewise 192.0.2.0107 is 192.0.2.107, so an extra zero in front of that address succeeds too. And 010 is 0.0.0.10, the same address as new('10').

IPv6 text is left alone, so 2001:db8::1 is the same address from both constructors, and ::ffff:192.0.2.010 is undef from both. A prefix length is decimal either way, so 192.0.2.0/024 is 192.0.2.0/24 from both. A dotted mask is stripped the same way as an address: new_no('192.0.2.0', '255.255.255.000') is 192.0.2.0/24 and new returns undef.

The new_from_aton constructor takes a packed IPv4 address and assumes a /32 mask. This function replaces the :aton functionality, which reads a packed string as text first and is fundamentally broken. See "DEPRECATED".

The constructors new_cis and new_cis6 accept the common Cisco address notation for address/mask pairs with a space as a separator instead of a slash (/). Both are deprecated in favour of new and new6, which do the same. See "DEPRECATED".

Both ->new6 and ->new_cis6 mark the address as being in ipV6 address space even if the format would suggest otherwise.

print NetAddr::IP::Lite->new6('192.0.2.1'), "\n";    # 0:0:0:0:0:0:C000:201/128

Addresses submitted to ->new in ipV6 notation will remain in that notation permanently, whereas the same address in dotted quad notation prints as IPv4:

print NetAddr::IP::Lite->new('::192.0.2.1'), "\n";   # 0:0:0:0:0:0:C000:201/128
print NetAddr::IP::Lite->new('192.0.2.1'), "\n";     # 192.0.2.1/32

The addr() value is what stringifies as the first part.

The $addr argument can be almost anything that can be resolved to an IP address. It can optionally contain the mask in CIDR notation. A host name is resolved with one getaddrinfo call, so an IPv6 name resolves as well as an IPv4 one. The IPv4 constructor uses an IPv4 answer when there is one. The IPv6 constructor uses an IPv6 answer when there is one, unless that answer is an IPv4-mapped or IPv4-compatible address and an IPv4 answer exists, as for a name with both ::1 and 127.0.0.1.

The prefix notation is understood, with the limitation that the range specified by the prefix must match with a valid subnet.

An IPv6-form mask on an IPv4 address covers all 128 bits, so it needs the 96 leading ones above the address. A mask with 1 to 95 ones returns undef; through new6 the same mask is an IPv6 prefix:

NetAddr::IP::Lite->new('192.0.2.4', 'ffff::');    # undef
NetAddr::IP::Lite->new6('192.0.2.4', 'ffff::');   # 0:0:0:0:0:0:C000:204/16
NetAddr::IP::Lite->new('192.0.2.4',
    'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ff00');   # 192.0.2.4/24

The same holds for a mask written as a whole number. One that fits in 32 bits is an IPv4 mask. A wider one covers all 128 bits, so it needs the 96 leading ones too. The two long masks below are ffff:ffff:ffff:ffff:ffff:ffff:ffff:ff00 and ffff:: written as whole numbers:

NetAddr::IP::Lite->new('192.0.2.4', 4294967040);   # 192.0.2.4/24
NetAddr::IP::Lite->new('192.0.2.4',
    '340282366920938463463374607431768211200');   # 192.0.2.4/24
NetAddr::IP::Lite->new('192.0.2.4',
    '340277174624079928635746076935438991360');   # undef

Addresses in the packed format returned by inet_aton or gethostbyname are understood only under the deprecated :aton tag, and no mask can be specified for them. Even then a packed string is read as text first and looked up as a host name second, so one whose bytes also spell text comes back as a different address or as undef; see :aton under "DEPRECATED". Use new_from_aton for a packed IPv4 address.

The $addr argument 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
n.n.n.n-n.n.n.n   range notation, with or without spaces at the dash
default, any, broadcast, loopback (keywords, see below)
host, as a mask keyword
x.x.x.x/host
x:x:x/host
0xABCDEF, 0b111111000101011110, (a bcd number)
a netaddr as returned by 'inet_aton', but only with the deprecated
:aton tag, and only when its bytes do not also read as one of these
forms or as a host name; without the tag a packed string returns undef

Any RFC 4291 s2.2 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 with a mask
default, any, loopback, unspecified (keywords, see below)
::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

A Math::BigInt is read as its decimal text, sign included, so Math::BigInt->new(-5) gives the same result as '-5'. A Math::BigInt NaN or infinity gives undef.

A Fully Qualified Domain Name which returns an ipV4 address or an ipV6 address, embodied in that order. This previously undocumented feature may be disabled with:

use NetAddr::IP::Lite qw(:nofqdn);

Surrounding whitespace is ignored on the address and on a separate mask, so a line read from a file needs no chomp:

NetAddr::IP::Lite->new("192.0.2.0/24\n");        # 192.0.2.0/24
NetAddr::IP::Lite->new("2001:db8::1\r\n");       # 2001:DB8:0:0:0:0:0:1/128
NetAddr::IP::Lite->new('192.0.2.0', " 24\n");    # 192.0.2.0/24

The text functions of NetAddr::IP::InetBase and NetAddr::IP::Util do not strip it, so there the string has to be the address and nothing else.

Called with no arguments, 'default' is assumed. An explicit undef argument returns undef, and an empty string returns undef.

Accepted forms in full

The list above is abbreviated. These are the forms worth knowing about, all verified on both builds.

Range and prefix notation, where the prefix has to name a valid subnet:

NetAddr::IP::Lite->new('192.0.2.0-192.0.2.255');   # 192.0.2.0/24
NetAddr::IP::Lite->new('192.0.2.4-7');             # 192.0.2.4/30
NetAddr::IP::Lite->new('192.0.2.');                # 192.0.2.0/24
NetAddr::IP::Lite->new('192.0.');                  # 192.0.0.0/16
NetAddr::IP::Lite->new('10.');                     # 10.0.0.0/8
NetAddr::IP::Lite->new('192.0-3.');                # 192.0.0.0/14

A range has to cover exactly one subnet: its first address has to start the subnet and its last has to end it. Any other range gives undef, in the short form as in the full one:

NetAddr::IP::Lite->new('192.0.2.5-6');             # undef
NetAddr::IP::Lite->new('192.1-2.');                # undef
NetAddr::IP::Lite->new('192.0.2.5-192.0.2.6');     # undef

Short dotted forms change meaning when a mask argument is given, which is the one trap here worth writing out. On its own the short form is a host address; with a mask it is the network of that size:

NetAddr::IP::Lite->new('10.1');         # 10.0.0.1/32
NetAddr::IP::Lite->new('10.1', 8);      # 10.1.0.0/8
NetAddr::IP::Lite->new('10.1.2');       # 10.1.0.2/32
NetAddr::IP::Lite->new('10.1.2', 24);   # 10.1.2.0/24

RFC 3986 brackets around an IPv6 literal, which is how a URI carries one:

NetAddr::IP::Lite->new('[2001:db8::1]/64');  # 2001:DB8:0:0:0:0:0:1/64
NetAddr::IP::Lite->new('[2001:db8::1]');     # 2001:DB8:0:0:0:0:0:1/128

Brackets around an IPv4 literal are not accepted and return undef.

Keywords. The set is not the same for every constructor, which is worth knowing before reaching for one:

NetAddr::IP::Lite->new('broadcast');     # 255.255.255.255/32
NetAddr::IP::Lite->new('unspecified');   # 0:0:0:0:0:0:0:0/128
NetAddr::IP::Lite->new('any');           # 0.0.0.0/0
NetAddr::IP::Lite->new('default');       # 0.0.0.0/0
NetAddr::IP::Lite->new('loopback');      # 127.0.0.1/8
NetAddr::IP::Lite->new('localhost');     # 127.0.0.1/32, via the resolver

A mask argument of ipv6 asks for the IPv6 form of a keyword, the same address new6 gives:

NetAddr::IP::Lite->new('loopback', 'ipv6');      # 0:0:0:0:0:0:0:1/128
NetAddr::IP::Lite->new('unspecified', 'ipv6');   # 0:0:0:0:0:0:0:0/128
NetAddr::IP::Lite->new('default', 'ipv6');       # 0:0:0:0:0:0:0:0/0

The broadcast keyword is IPv4 only: new6('broadcast') returns undef, while new6('unspecified') gives an IPv6 unspecified address. The loopback keyword gives a /8, not a /32. The name localhost is not a keyword at all: it is resolved, so it is undef under :nofqdn and resolver-dependent otherwise. Under new4, unspecified and the ipv6 mask give undef, since both name IPv6 addresses.

Numbers and masks

Text says which family it is in: dotted text such as 192.0.2.1 is IPv4, and text with a colon such as 2001:db8::1 is IPv6. A number does not, so the constructor decides:

input                  new         new4        new6
IPv4 text              IPv4        IPv4        IPv6, ::a.b.c.d
IPv6 text              IPv6        undef       IPv6
::ffff:a.b.c.d text    IPv6        IPv4        IPv6
number below 2**32     IPv4        IPv4        IPv6
number from 2**32      IPv6        undef       IPv6
negative number        IPv4        IPv4        undef

Under new4, IPv4-mapped text such as ::ffff:192.0.2.1 is the IPv4 address it carries, when its prefix is 96 bits or longer. A host name takes the family of its answer, so new4 gives undef for a name with no IPv4 address. Since new reads a number below 2**32 as IPv4, it cannot make an IPv6 address inside ::/96, such as ::1, from a number; new6 can.

A number is a whole decimal number such as 3221225985, a 0x or 0b literal of up to 32 bits such as 0xc0000201, or a Math::BigInt. A decimal number or a Math::BigInt goes up to 2**128 - 1. On its own a number is the address with that value:

NetAddr::IP::Lite->new('3221225985');    # 192.0.2.1/32
NetAddr::IP::Lite->new('4294967296');    # 0:0:0:0:0:1:0:0/128
NetAddr::IP::Lite->new4('4294967296');   # undef
NetAddr::IP::Lite->new6('1');            # 0:0:0:0:0:0:0:1/128

With a prefix length, new and new4 read a number from 0 to 255 as the first octet, the short form of 10.0.0.0/8, and a larger number as the address value. Under new6 the number is always the address value, and the prefix length is an IPv6 one:

NetAddr::IP::Lite->new('10', 8);     # 10.0.0.0/8
NetAddr::IP::Lite->new('300', 24);   # 0.0.1.44/24
NetAddr::IP::Lite->new6('10', 8);    # 0:0:0:0:0:0:0:A/8
NetAddr::IP::Lite->new6('10', 64);   # 0:0:0:0:0:0:0:A/64

A mask written as a whole number above 128 is a raw mask, the form numeric returns. With a raw mask the number is always the address value:

NetAddr::IP::Lite->new('10', 4294967040);   # 0.0.0.10/24

A negative number counts down from 2**32, so -1 is 255.255.255.255. Both new and new4 accept -1 to -4294967296, and new6 refuses a negative number:

NetAddr::IP::Lite->new('-1');    # 255.255.255.255/32
NetAddr::IP::Lite->new6('-1');   # undef

A mask is read for the family of the address:

mask                      IPv4 address          IPv6 address
prefix length 0 to 32     IPv4 prefix           IPv6 prefix
prefix length 33 to 128   undef                 IPv6 prefix
dotted, 255.255.255.0     IPv4 mask             96 plus its length
IPv6 form, ffff::         needs the 96          IPv6 mask
                          leading ones
whole number above 128    32 bits, or 128       128 bits
                          with the 96 leading
                          ones
host                      /32                   /128
default, any              /0                    /0
loopback                  /8                    /128
broadcast                 /32                   undef
unspecified               undef                 /128

Under new6, IPv4 text becomes ::a.b.c.d. A prefix length or a dotted mask on it is read as an IPv4 one and gains 96, and any other mask is read as for an IPv6 address:

NetAddr::IP::Lite->new6('192.0.2.1', 24);         # 0:0:0:0:0:0:C000:201/120
NetAddr::IP::Lite->new6('192.0.2.1', 'ffff::');   # 0:0:0:0:0:0:C000:201/16
NetAddr::IP::Lite->new6('192.0.2.1', 'host');     # 0:0:0:0:0:0:C000:201/128

Address and mask

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

Boundaries

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

The netmask is carried over from the object it was called on, so a /24 gives a /24 and a /32 gives a /32. Use addr() for the network address on its own, and cidr() for it in slash notation.

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

->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).

->range()

Returns a scalar with the base address and the broadcast address separated by a dash and spaces. This is called range notation.

Numeric forms

->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 context, 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.

Passing both values back rebuilds the object. The new6 constructor rebuilds an IPv6 object, including ::/0 and ::1/0. The new4 constructor and new rebuild an IPv4 object when the numeric mask is above 128. A numeric mask of 0 is still prefix length 0, so 0.0.0.5/0 comes back as 5.0.0.0/0. The new constructor reads the values of an IPv6 object inside ::/96, such as ::1, as IPv4:

my $ip = NetAddr::IP::Lite->new6('::1');
print NetAddr::IP::Lite->new6($ip->numeric), "\n";  # 0:0:0:0:0:0:0:1/128
print NetAddr::IP::Lite->new($ip->numeric), "\n";   # 0.0.0.1/32

The ipV6 value has more digits than a Perl number holds, so ==, <=> and sort on two numeric() results compare them as floats and call distinct addresses equal:

my $x = NetAddr::IP::Lite->new('2001:db8::1');
my $y = NetAddr::IP::Lite->new('2001:db8::2');
print scalar $x->numeric, "\n";   # 42540766411282592856903984951653826561
print $x->numeric == $y->numeric ? 'same' : 'different';
# same, though the addresses differ in the last digit

Compare the objects directly, since both operators are overloaded, or use ->bigint():

print $x == $y ? 'same' : 'different';     # different
print $x <=> $y;                            # -1
print $x->bigint == $y->bigint ? 'same' : 'different';   # different

->bigint()

When called in scalar context, will return a Math::BigInt representation of the address part of the IP address. When called in an array context, it returns a list of two elements, The first element is as described, the second element is the Math::BigInt representation of the netmask.

Containment

$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.

An IPv4 object and an IPv6 object never contain each other, even when the IPv6 address is the IPv4 address in ::a.b.c.d or ::ffff:a.b.c.d form. Compare ->addr() of the two to see why: they print as different addresses.

->is_rfc1918()

Returns true when $me is an RFC 1918 address.

10.0.0.0     -  10.255.255.255  (10/8 prefix)
172.16.0.0   -  172.31.255.255  (172.16/12 prefix)
192.168.0.0  -  192.168.255.255 (192.168/16 prefix)

->is_local()

Returns true when $me is a local network address.

i.e.   ipV4   127.0.0.0 - 127.255.255.255
or     ipV6   === ::1
or     ipV6   ::127.0.0.0 - ::127.255.255.255
or     ipV6   ::ffff:127.0.0.0 - ::ffff:127.255.255.255

An IPv4 loopback address held in an IPv6 object, whether from new6 or as a mapped address, is local, the same as its IPv4 form.

Hosts

->num()

Returns the number of usable addresses in the subnet: the host count, excluding the network and broadcast addresses. A /31 or /127 counts as 2 usable addresses per RFC 3021, and a /32 or /128 counts as 1:

print NetAddr::IP::Lite->new('192.0.2.0/31')->num();     # 2
print NetAddr::IP::Lite->new('2001:db8::/127')->num();   # 2
print NetAddr::IP::Lite->new('192.0.2.0/30')->num();     # 2
print NetAddr::IP::Lite->new('192.0.2.0/28')->num();     # 14
print NetAddr::IP::Lite->new('192.0.2.1/32')->num();     # 1

To use the old behavior for ->nth($index) and ->num():

use NetAddr::IP::Lite qw(:old_nth);

WARNING:

The module 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.

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

See "DEPRECATED" and the Changes file for the change, and the :old_nth tag for the old behaviour.

To use the old behavior for ->nth($index) and ->num():

use NetAddr::IP::Lite qw(:old_nth);

old behavior:
NetAddr::IP::Lite->new('192.0.2.0/32')->nth(0) == undef
NetAddr::IP::Lite->new('192.0.2.0/32')->nth(1) == undef
NetAddr::IP::Lite->new('192.0.2.0/31')->nth(0) == undef
NetAddr::IP::Lite->new('192.0.2.0/31')->nth(1) == 192.0.2.1/31
NetAddr::IP::Lite->new('192.0.2.0/30')->nth(0) == undef
NetAddr::IP::Lite->new('192.0.2.0/30')->nth(1) == 192.0.2.1/30
NetAddr::IP::Lite->new('192.0.2.0/30')->nth(2) == 192.0.2.2/30
NetAddr::IP::Lite->new('192.0.2.0/30')->nth(3) == 192.0.2.3/30

Note that in each case, the broadcast address is represented in the output set and that the 'zero'th index is always undef.

new behavior:
NetAddr::IP::Lite->new('192.0.2.0/32')->nth(0) == 192.0.2.0/32
NetAddr::IP::Lite->new('192.0.2.1/32')->nth(0) == 192.0.2.1/32
NetAddr::IP::Lite->new('192.0.2.0/31')->nth(0) == 192.0.2.0/31
NetAddr::IP::Lite->new('192.0.2.0/31')->nth(1) == 192.0.2.1/31
NetAddr::IP::Lite->new('192.0.2.0/30')->nth(0) == 192.0.2.1/30
NetAddr::IP::Lite->new('192.0.2.0/30')->nth(1) == 192.0.2.2/30
NetAddr::IP::Lite->new('192.0.2.0/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.

FUNCTIONS

Zeros, Zero, Ones, V4mask and V4net

use NetAddr::IP::Lite qw(Ones V4mask V4net Zeros);
use NetAddr::IP::Util qw(ipv6_n2x);

print ipv6_n2x(Zeros()), "\n";    # 0:0:0:0:0:0:0:0
print ipv6_n2x(Ones()), "\n";     # FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF
print ipv6_n2x(V4mask()), "\n";   # FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:0:0
print ipv6_n2x(V4net()), "\n";    # 0:0:0:0:0:0:FFFF:FFFF

Each returns a 128 bit string, the form an object keeps its address and mask in. The first is all zero bits and the second all one bits. The IPv4 pair, V4mask and V4net, has ones above the low 32 bits and in them respectively. Another name for Zeros is Zero.

EXPORT_OK

Zeros
Zero
Ones
V4mask
V4net

IMPORT TAGS

Five tags are accepted by this module. All of them are process-wide: they change behaviour for the whole program, not for one object, so an import in an unrelated package changes the output for everyone. Under ithreads each thread has its own copy; see "THREADS".

:lower

Return IPv6 text in lowercase, which RFC 5952 s4.3 recommends.

:upper

Return IPv6 text in uppercase, which is the default. If both :lower and :upper are given, :upper wins, whichever order they are in:

use NetAddr::IP::Lite qw(:lower :upper);
print NetAddr::IP::Lite->new('2001:db8::1')->addr, "\n";
# 2001:DB8:0:0:0:0:0:1

use NetAddr::IP::Lite qw(:upper :lower);
print NetAddr::IP::Lite->new('2001:db8::1')->addr, "\n";
# 2001:DB8:0:0:0:0:0:1

Note that :lower and :upper set $NetAddr::IP::InetBase::Upper, true for uppercase, shared by NetAddr::IP, NetAddr::IP::Lite, NetAddr::IP::Util and NetAddr::IP::InetBase. Importing either tag in one module changes the output of every other module in the same program. The last import wins.

:nofqdn

Do not resolve a fully qualified domain name in the constructor, which is otherwise done for you. The switch is $NetAddr::IP::Lite::NoFQDN. See "THREADS".

:old_nth

Restore the pre-4.00 nth() and num() behaviour. The switch is $NetAddr::IP::Lite::Old_nth. Deprecated; see "DEPRECATED" and "THREADS".

:aton

Accept a raw packed address in new(). Deprecated; see "DEPRECATED".

The full NetAddr::IP accepts two more, :old_storable and :rfc3021, and rejects nothing that this module accepts.

THREADS

The library keeps no state that threads share. Its functions hold nothing between calls, so several threads can call them at the same time.

The settings that change behaviour are package state: the :lower and :upper tags, and :nofqdn, :old_nth and :aton. Under ithreads each thread has its own copy. A thread starts with the settings in force when it was created, and a change made afterwards stays in the thread that made it. Within one thread they are still process-wide, as described under "IMPORT TAGS". With local, a change to one of these variables lasts to the end of the block, and the previous value returns there, including after die:

local $NetAddr::IP::InetBase::Upper = 0;   # lowercase IPv6 text
local $NetAddr::IP::Lite::NoFQDN    = 1;   # do not resolve a name
local $NetAddr::IP::Lite::Old_nth   = 1;   # pre-4.00 nth() and num()

DEPRECATED

Everything listed here is deprecated and will be removed in version 5.

:aton

Enables ->new() to accept a raw packed address of four or sixteen bytes, and stops it stripping surrounding whitespace from a string of four or sixteen bytes, which may be a packed address that begins or ends with a whitespace byte. Plain inet_aton notation is accepted without this tag.

The length of the string does not mark it as packed. Every text form listed under "Constructors" is tried first, then a host name lookup, and the string is read as packed only when all of them fail. A packed address whose bytes also spell text comes back as that text, or as undef:

string   packed address   result of new() under :aton
"1 23"   49.32.50.51      1.0.0.0/23, an address and a mask
"a bc"   97.32.98.99      undef, a mask that is not valid
"1234"   49.50.51.52      0.0.4.210/32, a decimal integer
"1.23"   49.46.50.51      1.0.0.23/32, a short dotted form
"0x1f"   48.120.49.102    0.0.0.31/32, a hex literal
"::1f"   58.58.49.102     0:0:0:0:0:0:0:1F/128, IPv6 text

Strings of digits with dots, hyphens, or an x or b after a leading zero can read as integers, short dotted forms, ranges and hex or binary literals. A space, tab, newline, carriage return, vertical tab, form feed or slash between two runs of letters, digits, dots, colons and hyphens splits the string into an address and a mask.

Any byte 0x3A, an ASCII colon, sends the string to the IPv6 text parser. Unless the whole string is IPv6 text, as in the last row above, the result is undef. Packed IPv4 addresses with an octet of 58, such as 192.0.2.58, fall into this group, as does 2001:db8::3a packed into sixteen bytes.

A string made only of ASCII letters, digits, dots, hyphens and underscores is looked up as a host name before it is read as packed. A packed address such as 109.97.105.108, the bytes "mail", makes the call wait for the resolver. If the name resolves, the answer is returned in place of the packed address.

The order also affects text. A four or sixteen character string that is not valid text and does not resolve, a mistyped host name for example, can come back as the address its bytes spell instead of undef.

Use new_from_aton for a packed IPv4 address: it reads every four byte string as packed and makes no lookup. There is no replacement for the packed sixteen byte case.

use NetAddr::IP::Lite qw(:aton);

new_cis and new_cis6

Accept the Cisco address and mask notation, with a space separator in place of a slash. Both ->new() and ->new6() do the same.

->new('192.0.2.0 24')       in place of   ->new_cis('192.0.2.0 24')
->new6('::192.0.2.0 120')   in place of   ->new_cis6('::192.0.2.0 120')

AUTHORS

Dean Hamstead <dean@fragfest.com.au>
Luis E. Muñoz <luismunoz@cpan.org>
Michael Robinton <michael@bizsystems.com>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The MIT (X11) License

The full text of the license can be found in the LICENSE file included with this distribution.

To install NetAddr::IP, copy and paste the appropriate command in to your terminal.

cpanm

cpanm NetAddr::IP

CPAN shell

perl -MCPAN -e shell
install NetAddr::IP

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)