NetAddr::IP - Manages IPv4 addresses and subnets

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

This module provides an object-oriented abstraction on top of IP addresses or IP subnets, that allows for easy manipulations. Many operations are supported, as described below:

Many operators have been overloaded, as described below: 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 CWeq or CW==. CWeq 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 CW== 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. 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 network 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 broadcast 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 opposite of auto-incrementing it, as you would expect.

This method creates a new IPv4 address with the supplied address in CW$addr and an optional netmask CW$mask, which can be omitted to get a /32 mask. CW$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 CWinet_aton or CWgethostbyname are also understood, although no mask can be specified for them. 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 a dotted-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. Returns a scalar with the mask as a dotted-quad. Returns a scalar the number of one bits in the mask. Returns a scalar with the address and mask in CIDR notation. A NetAddr::IP object stringifies to the result of this function. Returns the address part of the NetAddr::IP object in the same format as the CWinet_aton() function. This should ease a bit the code required to deal with old-style sockets. 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 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 CW->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 subnet. When called in a scalar context, returns the wildcard bits corresponding 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. Returns true when CW$me completely contains CW$other. False is returned otherwise and CWundef is returned if CW$me and CW$other are of different versions. The complement of CW->contains(). Returns true when CW$me is completely con tained within CW$other. Returns a list of objects, representing subnets of CW$bits mask produced by splitting the original object, which is left unchanged. Note that CW$bits must be longer than the original mask in order for it to be splittable. Note that CW$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 CW->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. Returns the list of hosts within a subnet. Faster version of CW->hostenum(), returning a reference to a list. Given a list of objects (including CW$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. As usual, a faster version of =item CW->compact() that returns a reference to a list. Note that this method takes a reference to a list instead. Returns a new object representing the first useable IP address within the subnet (ie, the first host address). Returns a new object representing the last useable IP address within the subnet (ie, one less than the broadcast address). 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 CW$index hosts), CWundef is returned. Returns the number of useable addresses IP addresses within the subnet, not counting the broadcast address.

None by default.

$Id: IP.pm,v 1.5 2002/10/31 21:32:20 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, CW$max, CW$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, 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.

3.01

*

Added CW->numeric().

*

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

3.02

*

Fxed CW->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 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 CW->wildcard() for producing subnets in wildcard format.

*

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

3.04

*

Got rid of CWcroak() when invalid input was fed to CW->new().

*

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

3.05

*

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

3.06

*

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

3.07

*

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

*

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

3.08

*

By popular request, CW->new() now checks the sanity of the netmasks it receives. If the netmask is invalid, CWundef 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 CW->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.

*

CW'any' can be used as a synonim of CW'default'. Also, CW'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 processing 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 CW->aton() and support for this format in CW->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 CWpack()/CWunpack() for the new support for CW->aton().

3.14

*

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

Luis E. Munoz <luismunoz@cpan.org>

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

perl(1).