Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Apropos / Subsearch:
optional field

IP(3pm)               User Contributed Perl Documentation              IP(3pm)

       NetAddr::IP - Manages IPv4 and IPv6 addresses and subnets

         use NetAddr::IP qw(

         my $ip = new NetAddr::IP 'loopback';

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

         if ($ip->within(new NetAddr::IP "", "")) {
             print "Is a loopback address\n";

                                       # This prints
         print "You can also say $ip...\n";

       * The following four functions return ipV6 representations of:

         ::                                       = Zeros();
         FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::          = V4mask();
         ::FFFF:FFFF                              = V4net();

       * To accept addresses in the format as returned by inet_aton, invoke
       the module as:

         use NetAddr::IP qw(:aton);

       * To enable usage of legacy data files containing NetAddr::IP objects
       stored using the Storable module.

         use NetAddr::IP qw(:old_storable);

       * To compact many smaller subnets (see: "$me->compact($addr1,

         @compacted_object_list = Compact(@object_list)

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

         $arrayref = Coalesce($masklen, $number, @list_of_subnets)

       Un-tar the distribution in an appropriate directory and type:

               perl Makefile.PL
               make test
               make install

       NetAddr::IP 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 test
               make install

       This module provides an object-oriented abstraction on top of IP
       addresses or IP subnets, that allows for easy manipulations.  Version
       4.xx of NetAdder::IP will will work older versions of Perl and does not
       use Math::BigInt as in previous versions.

       The internal representation of all IP objects is in 128 bit IPv6
       notation.  IPv4 and IPv6 objects may be freely mixed.

       Overloaded Operators

       Many operators have been overloaded, as described below:

       Assignment ("=")
           Has been optimized to copy one NetAddr::IP object to another very

           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.

           "->>copy()" actually creates a new object when called.

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

                   my $ip = new NetAddr::IP '';
                   print "$ip\n";

           Will print the string

           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('','') eq '')
                  { print "Yes\n"; }

           Will print out "Yes".

           Comparison with "==" requires both operands to be NetAddr::IP

           In both cases, a true value is returned if the CIDR representation
           of the operands is equal.

       Comparison via >&gt;, <&lt;, >&gt;=, <&lt;=, <&lt;=>&gt; 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 cidr portion of
           the masks are compared.

       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('') + 5;

           will output The address will wrap around at the
           broadcast back to the network address. This code:

               print NetAddr::IP->new('') + 255;


       Substraction of a constant
           The complement of the addition of a constant.

           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

           Auto-decrementing a NetAddr::IP object performs exactly the
           opposite 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.


       "->new([$addr, [ $mask|IPv6 ]])"
       "->new6([$addr, [ $mask]])"
           These methods creates 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

           "->new6" marks the address as being in ipV6 address space even if
           the format would suggest otherwise.

             i.e.  ->new6('') will result in ::102:304

             addresses submitted to ->new in ipV6 notation will
             remain in that notation permanently. i.e.
                   ->new('::') will result in ::102:304
             whereas new('') would print out as

             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.

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

           To accept addresses in that format, invoke the module as in

             use NetAddr::IP ':aton'

           If called with no arguments, 'default' is assumed.

           $addr can be any of the following and possibly more...

             n.n.n.n/mm            32 bit cidr notation
             loopback, localhost, broadcast, any, default
             0xABCDEF, 0b111111000101011110, (a bcd number)
             a netaddr as returned by 'inet_aton'

           Any RFC1884 notation

             ::n.n.n.n/mmm         128 bit cidr notation
             x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation
             loopback, localhost, unspecified, any, default
             0xABCDEF, 0b111111000101011110 within the limits
             of perl's number resolution
             123456789012  a 'big' bcd number i.e. Math::BigInt

           If called with no arguments, 'default' is assumed.

           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.

           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.

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

           Returns a scalar with the mask as an IPv4 or IPv6 text string as
           described above.

           Returns a scalar the number of one bits in the mask.

           Returns the width of the address in bits. Normally 32 for v4 and
           128 for v6.

           Returns the version of the address or subnet. Currently this can be
           either 4 or 6.

           Returns a scalar with the address and mask in CIDR notation. A
           NetAddr::IP object stringifies to the result of this function.
           (see comments about ->new6() and ->addr() for output formats)

           Returns the address part of the NetAddr::IP 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

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

           Returns a scalar with the address and mask in ipV4 prefix
           representation. 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.

           Just as "->prefix()", but does not include the broadcast address.

           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

           When called in a scalar context, returns the wildcard bits
           corresponding to the mask, in dotted-quad or ipV6 format as

           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.

           Returns the address part in a short or compact notation.

             (ie, becomes 127.1).

           Works with both, V4 and V6.

           Returns true when $me completely contains $other. False is returned
           otherwise and "undef" is returned if $me and $other are not both
           "NetAddr::IP" objects.

           The complement of "->contains()". Returns true when $me is
           completely con tained within $other.

           Note that $me and $other must be "NetAddr::IP" objects.

           Returns a list of objects, representing subnets of $bits mask
           produced 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.

           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.

           Return undef if the number of subnets > 2 ** 32

           Returns the list of hosts within a subnet.

           Faster version of "->hostenum()", returning a reference to a list.

       "$me->compact($addr1, $addr2, ...)"
       "@compacted_object_list = Compact(@object_list)"
           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
           subnets 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's must be "NetAddr::IP" objects.

           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.

       "$me->coalesce($masklen, $number, @list_of_subnets)"
       "$arrayref = 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.

           Called as a method, the array will include $me.

           WARNING: the list of subnet must be the same type. i.e ipV4 or ipV6

           Returns a new object representing the first usable IP address
           within the subnet (ie, the first host address).

           Returns a new object representing the last usable IP address within
           the subnet (ie, one less than the broadcast address).

           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. See the README file for

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

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

           Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite
           Returns the number of usable addresses IP addresses within the
           subnet, not counting the broadcast or network address. Previous
           versions returned th number of IP addresses not counting the
           broadcast address.

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

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

           Returns a Perl regular expression that will match an IP address
           within the given subnet. Defaults to ipV4 notation. Will return an
           ipV6 regex if the address in not in ipV4 space.

           Returns a Perl regular expression that will match an IP address
           within the given subnet. Always returns an ipV6 regex.


       $Id: IP.pm,v 4.7 2007/06/06 20:43:38 luisemunoz Exp $

           o   original  version;  Basic testing  and  release  to CPAN  as
               version 0.01. This is considered beta software.

           o   Multiple changes  to fix endiannes issues. This  code is now
               moderately tested on Wintel and Sun/Solaris boxes.

           o   Added ->first and ->last methods. Version changed to 0.03.

           o   Implemented ->new_subnet. Version changed to 1.00.

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

           o   As  per  Marnix   A.   Van  Ammers  [mav6ATns02.com]
               suggestion, changed  the syntax of the loop  in host_enum to be
               the same of the enum method.

           o   Fixed the MS-DOS ^M  at the end-of-line problem. This should
               make the module easier to use for *nix users.

           o   Implemented ->compact and ->expand methods.

           o   Applying for official name

           o   Added  ->addr_number and  ->mask_bits.  Currently  we return
               normal  numbers (not  BigInts).   Please test  this in  your
               platform and report any problems!

           o   Released under the new *official* name of NetAddr::IP

           o   Added support for ->new($min, $max, $bits) form

           o   Added ->to_numeric. This helps serializing objects

           o   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!

           o   This module is hopefully released with no CR-LF issues!

           o   Fixed a warning about uninitialized values during make test

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

           o   Some changes  suggested by Jeroen Ruigrok  and Anton Berezin
               were included. Thanks guys!

           o   Bug fix for /XXX.XXX.XXX.XXX netmasks under v5.6.1 suggested by
               Tim Wuyts. Thanks!

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

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

           o   Slight change  in license terms to ease  redistribution as a
               Debian package.

           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,
           taking 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
           earlier 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.

           o   Added "->numeric()".

           o   "->new()" called with no parameters creates a default
               NetAddr::IP object.

           o   Fxed "->compact()" for cases of equal subnets or mutually-
               contained IP addresses as pointed out by Peter Wirdemo. Note
               that now only distinct IP addresses will be returned by this

           o   Fixed the docs as suggested by Thomas Linden.

           o   Introduced overloading to ease certain common operations.


                   Fixed compatibility issue with C<-E<gt>num()> on 64-bit processors.

           o   Added more comparison operators.

           o   As per Peter Wirdemo's suggestion, added "->wildcard()" for
               producing subnets in wildcard format.

           o   Added "++" and "+" to provide for efficient iteration
               operations over all the hosts of a subnet without
               "->expand()"ing it.

           o   Got rid of "croak()" when invalid input was fed to "->new()".

           o   As suggested by Andrew Gaskill, added support for prefix
               notation. Thanks for the code of the initial "->prefix()"

           o   Added support for range notation, where base and broadcast
               addresses are given as arguments to "->new()".

           o   Andrew Ruthven pointed out a bug related to proper
               interpretation of "compact" CIDR blocks. This was fixed.

           o   Sami Pohto pointed out a bug with "->last()". This was fixed.

           o   A small bug related to parsing of 'localhost' was fixed.

           o   By popular request, "->new()" now checks the sanity of the
               netmasks it receives. If the netmask is invalid, "undef" will
               be returned.

           o   Fixed typo that invalidated otherwise correct masks. This bug
               appeared in 3.08.

           o   Fixed relops. Semantics where adjusted to remove the netmask
               from the comparison. (ie, it does not make sense to say that
      is > or viceversa).

           o   Thanks to David D. Zuhn for contributing the "->nth()" method.

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

           o   'any' can be used as a synonim of 'default'. Also, 'host' is
               now a valid (/32) netmask.

           o   Added CVS control files, though this is of no relevance to the

           o   Thanks to Steve Snodgrass for pointing out a bug in the
               processing of the special names such as default, any, etc. A
               fix was produced and adequate tests were added to the code.

           o   First steps towards "regexp free" parsing.

           o   Documentation revisited and reorganized within the file, so
               that it helps document the code.

           o   Added "->aton()" and support for this format in "->new()". This
               makes the code helpful to interface with old-style socket code.

           o   Fixes a warning related to 'wrapping', introduced in 3.12 in
               "pack()"/"unpack()" for the new support for "->aton()".

           o   "Socket::gethostbyaddr" in Solaris seems to behave a bit
               different from other OSes. Reversed change in 3.13 and added
               code around this difference.

           This is an interim release just to incorporate the v6 patches
           contributed.  No extensive testing has been done with this support
           yet. More tests are needed.

           o   Preliminary support for IPv6 contributed by Kadlecsik Jozsi
               <kadlec at sunserv.kfki.hu>. Thanks a lot!

           o   IP.pm and other files are enconded in ISO-8859-1 (Latin1) so
               that I can spell my name properly.

           o   Tested under Perl 5.8.0, no surprises found.

           Minor development release.

           o   Added "->version" and "->bits", including testing.

           o   "Compact" can now be exported if the user so requests.

           o   Fixed a bug when octets in a dotted quad were > 256 (ie, were
               not octets). Thanks to Anton Berezin for pointing this out.

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

           As noted by Michael, 127/8 should be and not
  Also, improved docs on the usage of contains() and

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

           Fixed a couple of (minor) bugs in shipped tests in the last
           version. Also, fixed a small pod typo that caused code to show up
           in the documentation.

           Fixed IP.pm so that all test could pass in Solaris machines. Thanks
           to all who reported this.

           Fixed some bugs pointed out by David Lloyd, having to do with the
           module packaging and version requirements. Thanks David!

           Fixed a bug pointed out by Andrew D. Clark, regarding proper
           parsing of IP ranges with non-contiguous masks. Thanks Andrew!

           Suggestion by Reuland Olivier gave birth to "short()", which
           provides for a compact representation of the IP address. Rewrote
           "_compact" to find the longest sequence of zeros to compact.
           Reuland also pointed out a flaw in contains() and within(), which
           was fixed. Thanks Reuland!

           Fixed rt bug #5478 in t/00-load.t.

           Fixed minor v-string problem pointed out by Steve Snodgrass (Thanks
           Steve!). NetAddr::IP can now collaborate with Storable to serialize

           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.

           Included support for Module::Signature. Added ->re() as contributed
           by Laurent Facq (Thanks Laurent!). Added Coalesce() as suggested by

           Version bump. Transfer of 3.23 to CPAN ended up in a truncated file
           being uploaded.

           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.

           Dependence on Math::BigInt removed, works with earlier versions of
           Perl.  The module was partitioned into three logical pieces as

           Util.pm        Math and logic operation on bit strings and number
                     that represent IP addresses and masks. Conversions
                     between various number formats. Implemented in
                     C_XS for speed and PURE PERL of transportability.

           Lite.pm        Operations, simple conversions and comparisons of
                     IP addresses, notations and formats.

           IP.pm          Complex operations and conversions of IP address
                     notation, nets, subnets, and ranges.

           The internal representation of addresses was changed to 128 bit
           binary strings as returned by inet_pton (ipv6_aton in this module).
           Both ipV4 and ipV6 notations can be freely mixed and matched.

           Additional methods added to force operations into ipV6 space even
           when ipV4 notation is used.

       Luis E. MuA~Xoz <luismunozATcpan.org>, Michael Robinton

       This software comes with the same warranty as perl itself (ie, none),
       so by using it you accept any and all the liability.

       This software is (c) Luis E. MuA~Xoz, 1999 - 2007, and (c) Michael
       Robinton, 2006 - 2007.  It can be used under the terms of the Perl
       artistic license provided that proper credit for the work of the
       authors is preserved in the form of this copyright notice and license
       for this module.

         perl(1),NetAddr::IP::Lite, NetAddr::IP::Util.

perl v5.10.0                      2007-06-06                           IP(3pm)