NetAddr(3)
NAME
NetAddr::IP - Manages IPv4 and IPv6 addresses and subnets
SYNOPSIS
use NetAddr::IP;
my $ip = new NetAddr::IP 'loopback';
print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;
if ($ip->within(new NetAddr::IP "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";
DESCRIPTION
This module provides an object-oriented abstraction on top of IP
addresses or IP subnets, that allows for easy manipulations. Many oper-
ations are supported, as described below:
Overloaded Operators
Many operators have been overloaded, as described below:
Assignment ("=")
Has been optimized to copy one NetAddr::IP object to another very
quickly.
Stringification
An object can be used just as a string. For instance, the following
code
my $ip = new NetAddr::IP 'loopback';
print "$ip\n";
Will print the string 127.0.0.1/8.
Equality
You can test for equality with either "eq" or "==". "eq" allows the
comparison with arbitrary strings as well as NetAddr::IP objects.
The following example:
if (NetAddr::IP->new('loopback') eq '127.0.0.1/8')
{ print "Yes\n"; }
Will print out "Yes".
Comparison with "==" requires both operands to be NetAddr::IP
objects.
In both cases, a true value is returned if the CIDR representation
of the operands is equal.
Comparison via >, <, >=, <=, <=> and "cmp"
Those are numeric comparisons. All will return undef if you attempt
to compare a V4 subnet with a V6 subnet, when V6 becomes supported
some day.
In case the version matches, the numeric representation of the net-
work is compared through the corresponding operation. The netmask
is ignored for these comparisons, as there is no standard criteria
to say wether 10/8 is larger than 10/10 or not.
Dereferencing as an ARRAY
You can do something along the lines of
my $net = new NetAddr::IP $cidr_spec;
for my $ip (@$net) {
print "Host $ip is in $net\n";
}
However, note that this might generate a very large amount of items
in the list. You must be careful when doing this kind of expansion,
as it is very easy to consume huge amounts of resources. See below
for smarter ways to do loops and other constructions that are much
more conservative.
Addition of a constant
Adding a constant to a NetAddr::IP object changes its address part
to point to the one so many hosts above the start address. For
instance, this code:
print NetAddr::IP->new('loopback') + 5;
will output 127.0.0.6/8. The address will wrap around at the broad-
cast back to the network address. This code:
print NetAddr::IP->new('10.0.0.1/24') + 255;
outputs 10.0.0.0/24.
Substraction of a constant
The complement of the addition of a constant.
Auto-increment
Auto-incrementing a NetAddr::IP 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 object performs exactly the oppo-
site of auto-incrementing it, as you would expect.
Serializing and Deserializing
This module defines hooks to collaborate with Storable for serializing
"NetAddr::IP" objects, through compact and human readable strings. You
can revert to the old format by invoking this module as
use NetAddr::IP ':old_storable';
You must do this if you have legacy data files containing NetAddr::IP
objects stored using the Storable module.
Methods
"->new([$addr, [ $mask|IPv6 ]])"
This method creates a new IPv4 address with the supplied address in
$addr and an optional netmask $mask, which can be omitted to get a
/32 mask.
$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 con-
tain the mask in CIDR notation.
prefix notation is understood, with the limitation that the range
speficied by the prefix must match with a valid subnet.
Addresses in the same format returned by "inet_aton" or "gethostby-
name" 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.
To accept addresses in that format, invoke the module as in
use NetAddr::IP ':aton'
If called with no arguments, 'default' is assumed.
IPv6 addresses according to RFC 1884 are also supported, except
IPv4 compatible IPv6 addresses.
"->broadcast()"
Returns a new object refering 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 refering 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 a dot-
ted-quad. This is useful for printing or for passing the address
part of the NetAddr::IP object to other components that expect an
IP address.
"->mask()"
Returns a scalar with the mask as a dotted-quad.
"->masklen()"
Returns a scalar the number of one bits in the mask.
"->bits()"
Returns the wide 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 object stringifies to the result of this function.
"->aton()"
Returns the address part of the NetAddr::IP object in the same for-
mat as the "inet_aton()" function. This should ease a bit the code
required to deal with "old-style" sockets.
"->range()"
Returns a scalar with the base address and the broadcast address
separated by a dash and spaces. This is called range notation.
"->prefix()"
Returns a scalar with the address and mask in prefix representa-
tion. This is useful for some programs, which expect its input to
be in this format. This method will include the broadcast address
in the encoding.
"->nprefix()"
Just as "->prefix()", but does not include the broadcast address.
"->numeric()"
When called in a scalar context, will return a numeric representa-
tion 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.
"->wildcard()"
When called in a scalar context, returns the wildcard bits corre-
sponding to the mask, in dotted-quad format.
When called in an array context, returns a two-element array. The
first element, is the address part. The second element, is the
wildcard translation of the mask.
"->short()"
Returns the address part in a short or compact notation. (ie,
127.0.0.1 becomes 127.1). Works with both, V4 and V6. Note that
"compact_addr" is now deprecated.
"$me->contains($other)"
Returns true when $me completely contains $other. False is returned
otherwise and "undef" is returned if $me and $other are of differ-
ent versions.
Note that $me and $other must be "NetAddr::IP" objects.
"$me->within($other)"
The complement of "->contains()". Returns true when $me is com-
pletely con tained within $other.
Note that $me and $other must be "NetAddr::IP" objects.
"->split($bits)"
Returns a list of objects, representing subnets of $bits mask pro-
duced by splitting the original object, which is left unchanged.
Note that $bits must be longer than the original mask in order for
it to be splittable.
Note that $bits can be given as an integer (the length of the mask)
or as a dotted-quad. If omitted, a host mask is assumed.
"->splitref($bits)"
A (faster) version of "->split()" that returns a reference to a
list of objects instead of a real list. This is useful when large
numbers of objects are expected.
"->hostenum()"
Returns the list of hosts within a subnet.
"->hostenumref()"
Faster version of "->hostenum()", returning a reference to a list.
"$me->compact($addr1, $addr2, ...)"
Given a list of objects (including $me), this method will compact
all the addresses and subnets into the largest (ie, least specific)
subnets possible that contain exactly all of the given objects.
Note that in versions prior to 3.02, if fed with the same IP sub-
nets multiple times, these subnets would be returned. From 3.02 on,
a more "correct" approach has been adopted and only one address
would be returned.
Note that $me and all $addr-n must be "NetAddr::IP" objects.
"$me->coalesce($masklen, $number, @list_of_subnets)"
Will return a reference to list of "NetAddr::IP" subnets of
$masklen mask length, when $number or more addresses from
@list_of_subnets are found to be contained in said subnet.
Subnets from @list_of_subnets with a mask shorter than $masklen are
passed "as is" to the return list.
Subnets from @list_of_subnets with a mask longer than $masklen will
be counted (actually, the number of IP addresses is counted)
towards $number.
"$me->compactref(\@list)"
As usual, a faster version of =item "->compact()" that returns a
reference to a list. Note that this method takes a reference to a
list instead.
Note that $me must be a "NetAddr::IP" object.
"->first()"
Returns a new object representing the first useable IP address
within the subnet (ie, the first host address).
"->last()"
Returns a new object representing the last useable IP address
within the subnet (ie, one less than the broadcast address).
"->nth($index)"
Returns a new object representing the n-th useable 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.
"->num()"
Returns the number of useable addresses IP addresses within the
subnet, not counting the broadcast address.
"->re()"
Returns a Perl regular expression that will match an IP address
within the given subnet. This is currently only implemented for
IPv4 addresses.
EXPORT
None by default.
HISTORY
$Id: IP.pm,v 3.33 2006/05/11 13:46:47 lem Exp $
0.01
* original version; Basic testing and release to CPAN as
version 0.01. This is considered beta software.
0.02
* Multiple changes to fix endiannes issues. This code is now
moderately tested on Wintel and Sun/Solaris boxes.
0.03
* Added ->first and ->last methods. Version changed to 0.03.
1.00
* Implemented ->new_subnet. Version changed to 1.00.
* less croak()ing when improper input is fed to the module. A
more consistent 'undef' is returned now instead to allow the
user to better handle the error.
1.10
* As per Marnix A. Van Ammers [mav6@ns02.comp.pge.com]
suggestion, changed the syntax of the loop in host_enum to be
the same of the enum method.
* Fixed the MS-DOS ^M at the end-of-line problem. This should
make the module easier to use for *nix users.
1.20
* Implemented ->compact and ->expand methods.
* Applying for official name
1.21
* Added ->addr_number and ->mask_bits. Currently we return
normal numbers (not BigInts). Please test this in your
platform and report any problems!
2.00
* Released under the new *official* name of NetAddr::IP
2.10
* Added support for ->new($min, $max, $bits) form
* Added ->to_numeric. This helps serializing objects
2.20
* Chris Dowling reported that the sort method introduced in
v1.20 for ->expand and ->compact doesn't always return a
number under perl versions < 5.6.0. His fix was applied and
redistributed. Thanks Chris!
* This module is hopefully released with no CR-LF issues!
* Fixed a warning about uninitialized values during make test
2.21
* Dennis Boylan pointed out a bug under Linux and perhaps
other platforms as well causing the error "Sort subroutine
didn't return single value at
/usr/lib/perl5/site_perl/5.6.0/NetAddr/IP.pm line 299, <>
line 2." or similar. This was fixed.
2.22
* Some changes suggested by Jeroen Ruigrok and Anton Berezin
were included. Thanks guys!
2.23
* Bug fix for /XXX.XXX.XXX.XXX netmasks under v5.6.1 suggested by
Tim Wuyts. Thanks!
* Tested the module under MACHTYPE=hppa1.0-hp-hpux11.00. It is
now konwn to work under Linux (Intel/AMD), Digital Unix
(Alpha), Solaris (Sun), HP-UX11 (HP-PA-RISC), Windows
9x/NT/2K (using ActiveState on Intel).
2.24
* A spurious warning when expand()ing with -w under certain
circumstances was removed. This involved using /31s, /32s
and the same netmask as the input. Thanks to Elie Rosenblum
for pointing it out.
* Slight change in license terms to ease redistribution as a
Debian package.
3.00
This is a major rewrite, supposed to fix a number of issues
pointed out in earlier versions.
The goals for this version include getting rid of BigInts, speeding
up and also cleaning up the code, which is written in a modular
enough way so as to allow IPv6 functionality in the future, tak-
ing benefit from most of the methods.
Note that no effort has been made to remain backwards compatible
with earlier versions. In particular, certain semantics of the ear-
lier versions have been removed in favor of faster performance.
This version was tested under Win98/2K (ActiveState
5.6.0/5.6.1), HP-UX11 on PA-RISC (5.6.0), RedHat Linux 6.2
(5.6.0), Digital Unix on Alpha (5.6.0), Solaris on Sparc (5.6.0)
and possibly others.
3.01
* Added "->numeric()".
* "->new()" called with no parameters creates a default
NetAddr::IP object.
3.02
* Fxed "->compact()" for cases of equal subnets or mutually-con-
tained IP addresses as pointed out by Peter Wirdemo. Note that
now only distinct IP addresses will be returned by this method.
* Fixed the docs as suggested by Thomas Linden.
* Introduced overloading to ease certain common operations.
*
Fixed compatibility issue with C<-E<gt>num()> on 64-bit processors.
3.03
* Added more comparison operators.
* As per Peter Wirdemo's suggestion, added "->wildcard()" for
producing subnets in wildcard format.
* Added "++" and "+" to provide for efficient iteration opera-
tions over all the hosts of a subnet without "->expand()"ing
it.
3.04
* Got rid of "croak()" when invalid input was fed to "->new()".
* As suggested by Andrew Gaskill, added support for prefix nota-
tion. Thanks for the code of the initial "->prefix()" function.
3.05
* Added support for range notation, where base and broadcast
addresses are given as arguments to "->new()".
3.06
* Andrew Ruthven pointed out a bug related to proper interpreta-
tion of "compact" CIDR blocks. This was fixed. Thanks!
3.07
* Sami Pohto pointed out a bug with "->last()". This was fixed.
* A small bug related to parsing of 'localhost' was fixed.
3.08
* By popular request, "->new()" now checks the sanity of the net-
masks it receives. If the netmask is invalid, "undef" will be
returned.
3.09
* Fixed typo that invalidated otherwise correct masks. This bug
appeared in 3.08.
3.10
* Fixed relops. Semantics where adjusted to remove the netmask
from the comparison. (ie, it does not make sense to say that
10.0.0.0/24 is > 10.0.0.0/16 or viceversa).
3.11
* Thanks to David D. Zuhn for contributing the "->nth()" method.
* tutorial.htm now included in the distribution. I hope this
helps some people to better understand what kind of stuff can
be done with this module.
* 'any' can be used as a synonim of 'default'. Also, 'host' is
now a valid (/32) netmask.
3.12
* Added CVS control files, though this is of no relevance to the
community.
* Thanks to Steve Snodgrass for pointing out a bug in the pro-
cessing of the special names such as default, any, etc. A fix
was produced and adequate tests were added to the code.
* First steps towards "regexp free" parsing.
* Documentation revisited and reorganized within the file, so
that it helps document the code.
* Added "->aton()" and support for this format in "->new()". This
makes the code helpful to interface with old-style socket code.
3.13
* Fixes a warning related to 'wrapping', introduced in 3.12 in
"pack()"/"unpack()" for the new support for "->aton()".
3.14
* "Socket::gethostbyaddr" in Solaris seems to behave a bit dif-
ferent from other OSes. Reversed change in 3.13 and added code
around this difference.
3.14_1
This is an interim release just to incorporate the v6 patches con-
tributed. No extensive testing has been done with this support
yet. More tests are needed.
* Preliminary support for IPv6 contributed by Kadlecsik Jozsi
<kadlec at sunserv.kfki.hu>. Thanks a lot!
* IP.pm and other files are enconded in ISO-8859-1 (Latin1) so
that I can spell my name properly.
* Tested under Perl 5.8.0, no surprises found.
3.14_2
Minor development release.
* Added "->version" and "->bits", including testing.
* "Compact" can now be exported if the user so requests.
* Fixed a bug when octets in a dotted quad were > 256 (ie, were
not octets). Thanks to Anton Berezin for pointing this out.
3.14_3
Fixed a bug pointed out by Brent Imhoff related to the implicit
comparison that happens within "Compact()". The netmask was being
ignored in the comparison (ie, 10/8 was considered the same as
10.0/16). Since some people have requested that 10.0/16 was consid-
ered larger than 10/8, I added this change, which makes the bug go
away. This will be the last '_' release, pending new bugs.
Regarding the comparison of subnets, I'm still open to debate so as
to wether 10.0/16 > 10/8. Certainly 255.255.0.0 > 255.0.0.0, but 2
** 24 are more hosts than 2 ** 16. I think we might use gt &
friends for this semantic and make everyone happy, but I won't do
anything else here without (significant) feedback.
3.14_4
As noted by Michael, 127/8 should be 127.0.0.0/8 and not
0.0.0.128/8. Also, improved docs on the usage of contains() and
friends.
3.15
Finally. Added POD tests (and fixed minor doc bug in IP.pm). As
reported by Anand Vijay, negative numbers are assumed to be signed
ints and converted accordingly to a v4 address. split() and nth()
now work with IPv6 addresses (Thanks to Venkata Pingali for report-
ing). Tests were added for v6 base functionality and splitting.
Also tests for bitwise aritmethic with long integers has been
added. I'm afraid Math::BigInt is now required.
Note that IPv6 might not be as solid as I would like. Be careful...
3.16
Fixed a couple of (minor) bugs in shipped tests in the last ver-
sion. Also, fixed a small pod typo that caused code to show up in
the documentation.
3.17
Fixed IP.pm so that all test could pass in Solaris machines. Thanks
to all who reported this.
3.18
Fixed some bugs pointed out by David Lloyd, having to do with the
module packaging and version requirements. Thanks David!
3.19
Fixed a bug pointed out by Andrew D. Clark, regarding proper pars-
ing of IP ranges with non-contiguous masks. Thanks Andrew!
3.20
Suggestion by Reuland Olivier gave birth to "short()", which pro-
vides for a compact representation of the IP address. Rewrote
"_compact" to find the longest sequence of zeros to compact. Reu-
land also pointed out a flaw in contains() and within(), which was
fixed. Thanks Reuland!
Fixed rt bug #5478 in t/00-load.t.
3.21
Fixed minor v-string problem pointed out by Steve Snodgrass (Thanks
Steve!). NetAddr::IP can now collaborate with Storable to serialize
itself.
3.22
Fixed bug rt.cpan.org #7070 reported by Grover Browning
(auto-inc/dec on v6 fails). Thanks Grover. Ruben van Staveren
pointed out a bug in v6 canonicalization, as well as providing a
patch that was applied. Thanks Ruben.
3.23
Included support for Module::Signature. Added ->re() as contributed
by Laurent Facq (Thanks Laurent!). Added Coalesce() as suggested by
Perullo.
3.24
Version bump. Transfer of 3.23 to CPAN ended up in a truncated file
being uploaded.
3.25
Some IP specs resembling range notations but not depicting actual
CIDR ranges, were being erroneously recognized. Thanks to Steve
Snodgrass for reporting a bug with parsing IP addresses in 4-octet
binary format. Added optional Pod::Coverage tests. compact_addr has
been commented out, after a long time as deprecated. Improved speed
of ->new() for the case of a single host IPv4 address, which seems
to be the most common one.
$Log: IP.pm,v $ Revision 3.33 2006/05/11 13:46:47 lem Next release to
correct goof with signatures
Revision 3.32 2006/05/01 17:11:18 lem Force update as upload failed
Revision 3.31 2006/05/01 16:47:15 lem Fixed CPAN #16754, version con-
tained a space
Revision 3.30 2006/05/01 15:31:19 lem Moved DNS resolution to the
last spot in the chain, before special keywords, as suggested by Kevin
Brintnall - Thanks!
Revision 3.29 2005/10/05 18:01:30 lem Change version digits back to
previous levels
Revision 3.28 2005/09/28 23:56:52 lem Each revision will now add the
CVS log to the docs automatically.
AUTHOR
Luis E. Muoz <luismunoz@cpan.org>
WARRANTY
This software comes with the same warranty as perl itself (ie, none),
so by using it you accept any and all the liability.
LICENSE
This software is (c) Luis E. Muoz. It can be used under the terms of
the perl artistic license provided that proper credit for the work of
the author is preserved in the form of this copyright notice and
license for this module.
SEE ALSO
perl(1).
perl v5.8.8 2006-05-11 IP(3)
Man(1) output converted with
man2html