NAME

NetAddr::IP - Manipulate IP Addresses easily

SYNOPSIS

  use NetAddr::IP qw($Use_CIDR_Notation $Always_Display_Mask);

  # Initialization of NetAddr::IP objects
  my $ip = new NetAddr::IP "10.0.0.1";
  my $subnet = new NetAddr::IP("10.0.0.0", "255.255.255.0");
  my $othersubnet = new NetAddr::IP("10.0.0.0", "24");
  my $yetanothersubnet = new NetAddr::IP "10.0.0.0/24";
  my $serialsubnet = new NetAddr::IP($min, $max, $bits);

  # A proper subnet (or undef if any host but is set)
  my $subnet_ok = new_subnet NetAddr::IP("10.0.0.0", "24");
  my $subnet_undef = new_subnet NetAddr::IP("10.0.0.1", "24");

  # A numeric representation of a subnet/host address
  my $address = $ip->to_numeric();
  my ($min, $max, $bits) = $ip->to_numeric();

  # A string representation of an address or subnet
  print "My ip address is ", $ip->to_string, "\n";

  # Just the string or the mask part...
  print "My ip address alone is ", $ip->addr_to_string, "\n";
  print "and my netmask is ", $ip->mask_to_string, "\n";

  # Enumeration of all the addresses within a given subnet, keeping
  # the original mask
  my @hosts = $subnet->enum;
  for $i (@hosts) {
      print "address ", $i->to_string, 
      " belongs to subnet ", $subnet->to_string, "\n";
  }

  # You can also produce the list of host addresses in a given subnet
  my @hosts = $subnet->host_enum;
  for $i (@hosts) {
      print "Host ", $i->to_string, 
      " is in subnet ", $subnet->to_string, "\n";
  }

  # This calculates network and broadcast addresses for a subnet
  my $network = $subnet->network;
  my $broadcast = $subnet->broadcast;
  print "Subnet ", $subnet->to_string, " has broadcast address ",
    $broadcast->to_string, " and network number ", $network->to_string,
    "\n";

  # Checks to see if a host address or subnet is contained within another
  # subnet
  if ($subnet->contains $ip) {
      print "Host ", $ip->to_string, " is contained in ",
      $subnet->to_string, "\n";
  }

  # Masks and address components can be copied from object to object
  $ip1->set_addr($ip2);
  $ip1->set_mask($subnet);

  # Ammount of hosts in a subnet can also be easily calculated
  $max_hosts_in_subnet = $subnet->how_many - 2;

  # A range of IP Addresses
  @range = $ip->range($final_ip); # From $ip to $final_ip
  @range = $ip->range(@dont_know_which_is_larger);
				# From the smallest on the list + $ip to
				# the largest

  # Usable addresses in a subnet
  $first_address = $subnet->first;
  $last_address = $subnet->last;

  # Compact subnets or addresses into the largest possible CIDR block
  @compact_block = NetAddr::IP::compact(@many_small_ip_address_blocks);

  # Split a set of blocks into smaller subnets
  @small_subnets = NetAddr::IP::expand(@ip_address_blocks);

  # Obtain a numeric representation of an IP address
  my $number = $ip->addr_number;

  # How many bits are there in the mask?
  my $masklen = $ip->mask_bits;

DESCRIPTION

This module provides a simple interface to the tedious bit manipulation involved when handling IP address calculations. It also helps by performing range comparisons between subnets as well as other frequently used functions.

Most of the primitive functions return a NetAddr::IP object.

The variables $Use_CIDR_Notation and $Always_Display_Mask affect how the ->to_string function will present its result. The names are hopefully intuitive enough. Note that IP addresses are not properly compacted (ie, 200.44.0/18 is written as 200.44.0.0/18) because this adapts to the widely adopted but incorrect notation. Perhaps a later version will include a variable to change this.

This code has not been widely tested yet. Endianness problems might very well exist. Please email the author if such problems are found.

This software is (c) Luis E. Munoz. It can be used under the terms of the perl artistic license provided that proper credit is preserved and that the original documentation is not removed.

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

AUTHOR

Luis E. Munoz <lem@cantv.net>

SEE ALSO

perl(1).