.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::Netmask 3pm"
.TH Net::Netmask 3pm "2019-01-15" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\& Net::Netmask \- parse, manipulate and lookup IP network blocks
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Net::Netmask;
\&
\& $block = Net::Netmask\->new(network block)
\& $block = Net::Netmask\->new(network block, netmask)
\& $block = Net::Netmask\->new2(network block)
\& $block = Net::Netmask\->new2(network block, netmask)
\&
\& print $block;                      # a.b.c.d/bits or 1:2:3::4/bits
\& print $block\->base()
\& print $block\->mask()
\& print $block\->hostmask()
\& print $block\->bits()
\& print $block\->size()
\& print $block\->maxblock()
\& print $block\->broadcast()
\& print $block\->next()
\& print $block\->match($ip);
\& print $block\->nth(1, [$bitstep]);
\& print $block\->protocol();
\&
\& if ($block\->sameblock("network block")) ...
\& if ($block\->cmpblocks("network block")) ...
\&
\& $newblock = $block\->nextblock([count]);
\&
\& for $ip ($block\->enumerate([$bitstep])) { }
\&
\& for $zone ($block\->inaddr()) { }
\&
\& my $table = {};
\& $block\->storeNetblock([$table])
\& $block\->deleteNetblock([$table])
\& @missingblocks = $block\->cidrs2inverse(@blocks)
\&
\& $block = findNetblock(ip, [$table])
\& $block = findOuterNetblock(ip, [$table])
\& @blocks = findAllNetblock(ip, [$table])
\& if ($block\->checkNetblock([$table]) ...
\& $block2 = $block1\->findOuterNetblock([$table])
\& @blocks = dumpNetworkTable([$table])
\&
\& @blocks = range2cidrlist($beginip, $endip);
\& @blocks = cidrs2cidrs(@blocks_with_dups)
\&
\& @listofblocks = cidrs2contiglists(@blocks);
\&
\& @blocks = sort @blocks
\& @blocks = sort_network_blocks(@blocks)
\&
\& @sorted_ip_addrs = sort_by_ip_address(@unsorted_ip_addrs)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Net::Netmask parses and understands IPv4 and IPv6 \s-1CIDR\s0 blocks (see
<https://en.wikipedia.org/wiki/Classless_Inter\-Domain_Routing>
for more information on \s-1CIDR\s0 blocks).  It's built with an
object-oriented interface, with functions being methods that
operate on a Net::Netmask object.
.PP
These methods provide nearly all types of information about a
network block that you might want.
.PP
There are also functions to insert a network block into a table
and then later lookup network blocks by \s-1IP\s0 address using that table.
There are functions to turn a \s-1IP\s0 address range into a list of
\&\s-1CIDR\s0 blocks.  There are functions to turn a list of \s-1CIDR\s0 blocks
into a list of \s-1IP\s0 addresses.
.PP
There is a function for sorting by text \s-1IP\s0 address.
.PP
All functions understand both IPv4 and IPv6.  Matches, finds, etc,
will always return false when an IPv4 address is matched against
an IPv6 address.
.PP
IPv6 support was added in 1.9104.
.SH "CONSTRUCTING"
.IX Header "CONSTRUCTING"
Net::Netmask objects are created with an \s-1IP\s0 address and optionally
a mask.  There are many forms that are recognized:
.IP "'216.240.32.0/24'" 32
.IX Item "'216.240.32.0/24'"
The preferred IPv6 form.
.IP "'216.240.32.0:255.255.255.0'" 32
.IX Item "'216.240.32.0:255.255.255.0'"
.PD 0
.IP "'216.240.32.0\-255.255.255.0'" 32
.IX Item "'216.240.32.0-255.255.255.0'"
.IP "'216.240.32.0', '255.255.255.0'" 32
.IX Item "'216.240.32.0', '255.255.255.0'"
.IP "'216.240.32.0', '0xffffff00'" 32
.IX Item "'216.240.32.0', '0xffffff00'"
.IP "'216.240.32.0 \- 216.240.32.255'" 32
.IX Item "'216.240.32.0 - 216.240.32.255'"
.IP "'216.240.32.4'" 32
.IX Item "'216.240.32.4'"
.PD
A /32 block.
.IP "'216.240.32'" 32
.IX Item "'216.240.32'"
Always a /24 block.
.IP "'216.240'" 32
.IX Item "'216.240'"
Always a /16 block.
.IP "'140'" 32
.IX Item "'140'"
Always a /8 block.
.IP "'216.240.32/24'" 32
.IX Item "'216.240.32/24'"
.PD 0
.IP "'216.240/16'" 32
.IX Item "'216.240/16'"
.IP "'default' or 'any'" 32
.IX Item "'default' or 'any'"
.PD
0.0.0.0/0 (the default route)
.IP "'216.240.32.0#0.0.31.255'" 32
.IX Item "'216.240.32.0#0.0.31.255'"
A hostmask (as used by Cisco access-lists \- that is, the hostmask
is the bitwise inverse of a netmask).
.IP "'2001:db8:1234:5678::/64'" 32
.IX Item "'2001:db8:1234:5678::/64'"
The preferred IPv6 form.
.IP "'2001:db8:1234:5678::9876'" 32
.IX Item "'2001:db8:1234:5678::9876'"
A /128 block.
.IP "'default6' or 'any6'" 32
.IX Item "'default6' or 'any6'"
::/0 (the default route)
.PP
There are two constructor methods: \f(CW\*(C`new\*(C'\fR and \f(CW\*(C`new2\*(C'\fR.  \f(CW\*(C`new2\*(C'\fR
differs from \f(CW\*(C`new\*(C'\fR in that it will return undef for invalid netmasks,
while \f(CW\*(C`new\*(C'\fR will return a netmask object even if the constructor
could not figure out what the network block should be.
.PP
With \f(CW\*(C`new\*(C'\fR, the error string can be found as \f(CW$block\fR\->{'\s-1ERROR\s0'}.  With
\&\f(CW\*(C`new2\*(C'\fR the error can be found as Net::Netmask::errstr or \f(CW$Net::Netmask::error\fR.
.SH "METHODS"
.IX Header "METHODS"
.IP "\->\fBdesc\fR()" 25
.IX Item "->desc()"
Returns a description of the network block.  Eg: \*(L"216.240.32.0/19\*(R"
or \*(L"2001:db8:1234::/48\*(R".  This is also available as overloaded
stringification.
.IP "\->\fBbase\fR()" 25
.IX Item "->base()"
Returns base address of the network block as a string.  Eg: \*(L"216.240.32.0\*(R".
or \*(L"2001:db8:1234::/48\*(R".  \fBBase\fR does not give an indication of the size
of the network block.
.IP "\->\fBmask\fR()" 25
.IX Item "->mask()"
Returns the netmask as a string. Eg: \*(L"255.255.255.0\*(R" or \*(L"ffff:ffff:ffff:ffff::\*(R"
.IP "\->\fBhostmask\fR()" 25
.IX Item "->hostmask()"
Returns the host mask which is the opposite of the netmask.
Eg: \*(L"0.0.0.255\*(R" or \*(L"::ffff:ffff:ffff:ffff\*(R".
.IP "\->\fBbits\fR()" 25
.IX Item "->bits()"
Returns the netmask as a number of bits in the network
portion of the address for this block.  Eg: 24.
.IP "\->\fBsize\fR()" 25
.IX Item "->size()"
Returns the number of \s-1IP\s0 addresses in a block.  Eg: 256.  For IPv6 addresses,
this will be a Math::BigInt object.
.IP "\->\fBbroadcast\fR()" 25
.IX Item "->broadcast()"
The blocks broadcast address. (The last \s-1IP\s0 address inside the
block.) Eg: 192.168.1.0/24 => 192.168.1.255
or 2001:db8::/64 => 2001:db8::ffff:ffff:ffff:ffff
.IP "\->\fBnext\fR()" 25
.IX Item "->next()"
The first \s-1IP\s0 address following the block. (The \s-1IP\s0 address following
the broadcast address.) Eg: 192.168.1.0/24 => 192.168.2.0
or 2001:db8:0:1::/64 => 2001:db8:0:2::/64
.IP "\->\fBfirst\fR() & \->\fBlast\fR()" 25
.IX Item "->first() & ->last()"
Synonyms for \->\fBbase\fR() and \->\fBbroadcast\fR()
.IP "\->\fBprotocol\fR()" 25
.IX Item "->protocol()"
Added in version 1.9102.
.Sp
Returns the address family/protocol represented by the block.
Either 'IPv4' or 'IPv6'.
.IP "\->\fBmatch\fR($ip)" 25
.IX Item "->match($ip)"
Returns a true if the \s-1IP\s0 number \f(CW$ip\fR matches the given network. That
is, a true value is returned if \f(CW$ip\fR is between \fBbase()\fR and \fBbroadcast()\fR.
For example, if we have the network 192.168.1.0/24, then
.Sp
.Vb 5
\&  192.168.0.255 => 0
\&  192.168.1.0   => "0 "
\&  192.168.1.1   => 1
\&  ...
\&  192.168.1.255 => 255
.Ve
.Sp
\&\f(CW$ip\fR should be a dotted-quad (eg: \*(L"192.168.66.3\*(R") or an IPv6 address
in standard notation (eg: \*(L"2001:db8::1\*(R").
.Sp
It just happens that the return value is the position within the block.
Since zero is a legal position, the true string \*(L"0 \*(R" is returned in
it's place.  \*(L"0 \*(R" is numerically zero though.  When wanting to know
the position inside the block, a good idiom is:
.Sp
.Vb 2
\&  $pos = $block\->match($ip) or die;
\&  $pos += 0;
.Ve
.IP "\->\fBmaxblock\fR()" 25
.IX Item "->maxblock()"
Much of the time, it is not possible to determine the size
of a network block just from it's base address.  For example,
with the network block '216.240.32.0/27', if you only had the
\&'216.240.32.0' portion you wouldn't be able to tell for certain
the size of the block.  '216.240.32.0' could be anything from a
\&'/23' to a '/32'.  The \fBmaxblock\fR() method gives the size of
the largest block that the current block's address would allow it
to be.  The size is given in bits.  Eg: 23.
.IP "\->\fBenumerate\fR([$bitstep)" 25
.IX Item "->enumerate([$bitstep)"
Returns a list of all the \s-1IP\s0 addresses in the block.  Be very
careful not to use this function of large blocks.  The \s-1IP\s0
addresses are returned as strings.  Eg: '216.240.32.0', '216.240.32.1',
\&... '216.240.32.255'.
.Sp
If the optional argument is given, step through the block in
increments of a given network size.  To step by 4, use a bitstep
of 30 (as in a /30 network).
.Sp
Note that for IPv6, this will return failure if more than 1,000,000,000
addresses would be returned.
.IP "\->\fBnth\fR($index, [$bitstep])" 25
.IX Item "->nth($index, [$bitstep])"
Returns the nth element of the array that \fBenumerate\fR would return
if it were called.  So, to get the first usable address in a block,
use \fBnth\fR(1).  To get the broadcast address, use \fBnth\fR(\-1).  To
get the last usable address, use \fBnth\fR(\-2).
.IP "\->\fBinaddr\fR()" 25
.IX Item "->inaddr()"
Returns an inline list of tuples.
.Sp
For IPv4:
.Sp
There is a tuple for each \s-1DNS\s0 zone name (at the /24 level) in the block.
If the block is smaller than a /24, then the zone of the enclosing /24
is returned.
.Sp
Each tuple contains: the \s-1DNS\s0 zone name, the last component of
the first \s-1IP\s0 address in the block in that zone, the last component
of the last \s-1IP\s0 address in the block in that zone.
.Sp
Examples: the list returned for the block '216.240.32.0/23' would
be: '32.240.216.in\-addr.arpa', 0, 255, '33.240.216.in\-addr.arpa', 0, 255.
The list returned for the block '216.240.32.64/27' would be:
\&'32.240.216.in\-addr.arpa', 64, 95.
.Sp
For IPv6:
.Sp
A list is returned with each \s-1DNS\s0 zone name at the shortest-prefix length
possible.  This is not returned as a tuple, but just a list of strings.
.Sp
Examples: the list returned for the block '2002::/16' would be a one
element list, containing just 2.0.0.2.ip6.arpa'.  The list
for '2002::/17' would return a two element list
containing '0.2.0.0.2.ip6.arpa' and '1.2.0.0.2.ip6.arpa'.
.IP "\->\fBnextblock\fR([$count])" 25
.IX Item "->nextblock([$count])"
Without a \f(CW$count\fR, return the next block of the same size after the
current one.  With a count, return the Nth block after the current one.
A count of \-1 returns the previous block.  Undef will be returned if
out of legal address space.
.IP "\->\fBsameblock\fR($block)" 25
.IX Item "->sameblock($block)"
Compares two blocks.  The second block will be auto-converted from
a string if it isn't already a Net::Netmask object.  Returns 1 if
they are identical.
.IP "\->\fBcmpblocks\fR($block)" 25
.IX Item "->cmpblocks($block)"
Compares two blocks.  The second block will be auto-converted from
a string if it isn't already a Net::Netmask object.  Returns \-1,
0, or 1 depending on which one has the lower base address or which
one is larger if they have the same base address.
.IP "\->\fBcontains\fR($block)" 25
.IX Item "->contains($block)"
Compares two blocks.  The second block will be auto-converted from
a string if it isn't already a Net::Netmask object.  Returns 1
if the second block fits inside the first block.  Returns 0 otherwise.
.IP "\->\fBstoreNetblock\fR([$t])" 25
.IX Item "->storeNetblock([$t])"
Adds the current block to an table of network blocks.  The
table can be used to query which network block a given \s-1IP\s0 address
is in.
.Sp
The optional argument allows there to be more than one table.
By default, an internal table is used.   If more than one table
is needed, then supply a reference to a \s-1HASH\s0 to store the
data in.
.IP "\->\fBdeleteNetblock\fR([$t])" 25
.IX Item "->deleteNetblock([$t])"
Deletes the current block from a table of network blocks.
.Sp
The optional argument allows there to be more than one table.
By default, an internal table is used.   If more than one table
is needed, then supply a reference to a \s-1HASH\s0 to store the
data in.
.IP "\->\fBcheckNetblock\fR([$t])" 25
.IX Item "->checkNetblock([$t])"
Returns true of the netblock is already in the network table.
.ie n .IP "\->\fBtag\fR($name [, $value])" 25
.el .IP "\->\fBtag\fR($name [, \f(CW$value\fR])" 25
.IX Item "->tag($name [, $value])"
Tag network blocks with your own data.  The first argument is the
name of your tag (hash key) and the second argument (if present) is
the new value.  The old value is returned.
.IP "\->\fBsplit\fR($parts)" 25
.IX Item "->split($parts)"
Splits a netmask into a number of sub netblocks. This number must be
a base 2 number (2,4,8,16,etc.) and the number must not exceed the
number of IPs within this netmask.
.Sp
For instance,
.Sp
.Vb 1
\&  Net::Netmask\->new( \*(Aq10.0.0.0/24\*(Aq )\->split(2)
.Ve
.Sp
is equivilent to
.Sp
.Vb 1
\&  ( Net::Netmask( \*(Aq10.0.0.0/25\*(Aq), Net::Netmask( \*(Aq10.0.0.128/25\*(Aq ) )
.Ve
.SH "METHOD/FUNCTION COMBOS"
.IX Header "METHOD/FUNCTION COMBOS"
.IP "\fBfindOuterNetblock\fR(ip, [$t])" 25
.IX Item "findOuterNetblock(ip, [$t])"
Search the table of network blocks (created with \fBstoreNetBlock\fR)
to find if any of them contain the given \s-1IP\s0 address.  The \s-1IP\s0 address
can either be a string or a Net::Netmask object (method invocation).
If more than one block in the table contains the \s-1IP\s0 address or
block, the largest network block will be the one returned.
.Sp
The return value is either a Net::Netmask object or undef.
.ie n .IP "\fBcidrs2inverse\fR(block, @listOfBlocks)" 25
.el .IP "\fBcidrs2inverse\fR(block, \f(CW@listOfBlocks\fR)" 25
.IX Item "cidrs2inverse(block, @listOfBlocks)"
Given a block and a list of blocks, \fBcidrs2inverse\fR() will return
a list of blocks representing the \s-1IP\s0 addresses that are in the block
but not in the list of blocks.  It finds the gaps.
.Sp
The block will be auto-converted from a string if it isn't already
a Net::Netmask object.  The list of blocks should be Net::Netmask
objects.
.Sp
The return value is a list of Net::Netmask objects.
.SH "OVERLOADING"
.IX Header "OVERLOADING"
.ie n .IP "\fB""""\fR" 25
.el .IP "\fB``''\fR" 25
.IX Item """"""
Strinification is overloaded to be the \->\fBdesc\fR() method.
.IP "\fBcmp\fR" 25
.IX Item "cmp"
Numerical and string comparisons have been overloaded to
the \->\fBcmpblocks\fR() method.  This allows blocks to be sorted
without specifying a sort function.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBsort_by_ip_address\fR" 25
.IX Item "sort_by_ip_address"
This function is included in \f(CW\*(C`Net::Netmask\*(C'\fR simply because
there doesn't seem to be a better place to put it on \s-1CPAN.\s0
It turns out that there is one method for sorting dotted-quads
(\*(L"a.b.c.d\*(R") that is faster than all the rest.  This is that
way.  Use it as \f(CW\*(C`sort_by_ip_address(@list_of_ips)\*(C'\fR.  That was
the theory anyway.  Someone sent a faster version ...
.Sp
This method also will sort IPv6 addresses, but is not performance
optimized.  It is correct, however.
.IP "\fBsort_network_blocks\fR" 25
.IX Item "sort_network_blocks"
This function is a function to sort Net::Netmask objects.  It's
faster than the simpler \f(CW\*(C`sort @blocks\*(C'\fR that also works.
.IP "\fBfindNetblock\fR(ip, [$t])" 25
.IX Item "findNetblock(ip, [$t])"
Search the table of network blocks (created with \fBstoreNetBlock\fR) to
find if any of them contain the given \s-1IP\s0 address.  The \s-1IP\s0 address
is expected to be a string.  If more than one block in the table
contains the \s-1IP\s0 address, the smallest network block will be the
one returned.
.Sp
The return value is either a Net::Netmask object or undef.
.IP "\fBfindAllNetblock\fR(ip, [$t])" 25
.IX Item "findAllNetblock(ip, [$t])"
Search the table of network blocks (created with \fBstoreNetBlock\fR) to
find if any of them contain the given \s-1IP\s0 address.  The \s-1IP\s0 address
is expected to be a string.   All network blocks in the table that
contain the \s-1IP\s0 address will be returned.
.Sp
The return value is a list of Net::Netmask objects.
.IP "\fBdumpNetworkTable\fR([$t])" 25
.IX Item "dumpNetworkTable([$t])"
Returns a list of the networks in a network table (as
created by \->\fBstoreNetblock\fR()).
.ie n .IP "\fBrange2cidrlist\fR($startip, $endip)" 25
.el .IP "\fBrange2cidrlist\fR($startip, \f(CW$endip\fR)" 25
.IX Item "range2cidrlist($startip, $endip)"
Given a range of \s-1IP\s0 addresses, return a list of blocks that
span that range.
.Sp
For example, range2cidrlist('216.240.32.128', '216.240.36.127'),
will return a list of Net::Netmask objects that correspond to:
.Sp
.Vb 4
\&    216.240.32.128/25
\&    216.240.33.0/24
\&    216.240.34.0/23
\&    216.240.36.0/25
.Ve
.IP "\fBcidrs2contiglists\fR(@listOfBlocks)" 25
.IX Item "cidrs2contiglists(@listOfBlocks)"
\&\f(CW\*(C`cidrs2contiglists\*(C'\fR will rearrange a list of Net::Netmask objects
such that contiguous sets are in sublists and each sublist is
discontiguous with the next.
.Sp
For example, given a list of Net::Netmask objects corresponding to
the following blocks:
.Sp
.Vb 3
\&    216.240.32.128/25
\&    216.240.33.0/24
\&    216.240.36.0/25
.Ve
.Sp
\&\f(CW\*(C`cidrs2contiglists\*(C'\fR will return a list with two sublists:
.Sp
.Vb 1
\&    216.240.32.128/25 216.240.33.0/24
\&
\&    216.240.36.0/25
.Ve
.Sp
Overlapping blocks will be placed in the same sublist.
.IP "\fBcidrs2cidrs\fR(@listOfBlocks)" 25
.IX Item "cidrs2cidrs(@listOfBlocks)"
\&\f(CW\*(C`cidrs2cidrs\*(C'\fR will collapse a list of Net::Netmask objects by
combining adjacent blocks into larger blocks.   It returns a list
of blocks that covers exactly the same \s-1IP\s0 space.  Overlapping
blocks will be collapsed.
.SH "AUTHORS"
.IX Header "AUTHORS"
Joelle Maslak <jmaslak@antelope.net> (current maintainer)
.PP
David Muir Sharnoff (original creator/author)
.SH "LICENSE"
.IX Header "LICENSE"
Copyright (C) 1998\-2006 David Muir Sharnoff.
.PP
Copyright (C) 2011\-2013 Google, Inc.
.PP
Copyright (C) 2018 Joelle Maslak
.PP
This module may be used, modified and redistributed under the same
terms as Perl itself.