++ed by:

1 PAUSE user
1 non-PAUSE user.

Author image Karl Gaissmaier
and 1 contributors


Net::IPAM::IP - A library for reading, formatting, sorting and converting IP-addresses.


  use Net::IPAM::IP;

  # parse and normalize
  $ip1 = Net::IPAM::IP->new('') // die 'wrong format,';
  $ip2 = Net::IPAM::IP->new('fe80::1') // die 'wrong format,';

  $ip3 = $ip2->incr // die 'overflow,';

  say $ip1;    #
  say $ip2;    # fe80::1
  say $ip3;    # fe80::2

  $ip3 = $ip2->decr // die 'underflow,';

  say $ip1;    #
  say $ip2;    # fe80::1
  say $ip3;    # fe80::0

  say $ip1->cmp($ip2);    # -1

  say $ip2->expand;       # fe80:0000:0000:0000:0000:0000:0000:0001
  say $ip2->reverse;      #

  $ip = Net::IPAM::IP->new_from_bytes( pack( 'C4', 192,    168,   0, 1 ) );                 #
  $ip = Net::IPAM::IP->new_from_bytes( pack( 'n8', 0x2001, 0xdb8, 0, 0, 0, 0, 0, 1, ) );    # 2001:db8::1

  @ips = Net::IPAM::IP->getaddrs('dns.google.');
  say "@ips";  # 2001:4860:4860::8844 2001:4860:4860::8888



  $ip = Net::IPAM::IP->new("::1");

Parse the input string as IPv4/IPv6 address and returns the IP address object.

IPv4-mapped-IPv6 addresses are normalized and sorted as IPv4 addresses.

  ::ffff:    =>

Returns undef on illegal input.


  $ip = Net::IPAM::IP->new_from_bytes("\x0a\x00\x00\x01")

Parse the input as packed IPv4/IPv6/IPv4-mapped-IPv6 address and returns the IP address object.

Croaks on illegal input.

Can be used for cloning the object:

  $clone = $obj->new_from_bytes($obj->bytes);

getaddrs($name, [$error_cb])

Returns a list of ip objects for a given $name or undef if there is no RR record for $name.

  my @ips = Net::IPAM::IP->getaddrs('dns.google.');
  say "@ips";  # 2001:4860:4860::8844 2001:4860:4860::8888

"getaddrs" calls the Socket function getaddrinfo() under the hood.

With no error callback "getaddrs" just calls carp() with underlying Socket errors.

For granular error handling use your own error callback:

  my $my_error_cb = sub {
    my $error = shift;
    # check the $error and do what you want

  my @ips = Net::IPAM::IP->getaddrs( $name, $my_error_cb );

or shut up the default error handler with:

  my @ips = Net::IPAM::IP->getaddrs( $name, sub { } );

ANNOTATION: This constructor could also be named new_from_name but it behaves differently because it returns a list of objects and supports an optional argument as error callback, reporting underlying Socket errors.


Net::IPAM::IP implements the following methods:


Compare IP objects, returns -1, 0, +1


  @sorted_ips = sort { $a->cmp($b) } @unsorted_ips;

Fast bytewise lexical comparison of the binary representation in network byte order.

IPv4 addresses are always treated as smaller than IPv6 addresses (::ffff: < ::)


  $v = Net::IPAM::IP->new('fe80::1')->version    # 6

Returns 4 or 6.


Returns the input string in canonical form.

  lower case hexadecimal characters
  zero compression
  remove leading zeros

  say Net::IPAM::IP->new('Fe80::0001')->to_string;  # fe80::1

Stringification is overloaded with "to_string"

  my $ip = Net::IPAM::IP->new('Fe80::0001') // die 'wrong format';
  say $ip; # fe80::1


Returns the next IP address, returns undef on overflow.

  $next_ip = Net::IPAM::IP->new('fe80::1')->incr // die 'overflow,';
  say $next_ip;   # fe80::2


Returns the previous IP address, returns undef on underflow.

  $prev_ip = Net::IPAM::IP->new('fe80::1')->decr // die 'overflow,';
  say $prev_ip;   # fe80::


Expand IP address into canonical form, useful for grep, aligned output and lexical sort

        Net::IPAM::IP->new('')->expand;   # ''
        Net::IPAM::IP->new('fe80::1')->expand;   # 'fe80:0000:0000:0000:0000:0000:0000:0001'


Reverse IP address, needed for PTR entries in DNS zone files.

 Net::IPAM::IP->new('fe80::1')->reverse; # ''
 Net::IPAM::IP->new('')->reverse; # ''


Returns the DNS name for the ip object or undef if there is no PTR RR.

  say Net::IPAM::IP->new('2001:4860:4860::8888')->getname;   # dns.google.

"getname" calls the Socket function getnameinfo() under the hood.

With no error callback "getname" just calls carp() with underlying Socket errors.


Returns just one name even if the IP has more than one PTR RR. This is a limitation of Socket::getnameinfo. If you need all names for IPs with more than one PTR RR then you should use Net::DNS or similar modules.


  $ip = Net::IPAM::IP->new('fe80::');
  $bytes = $ip->bytes;    # "\xfe\x80\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00"

  $ip    = Net::IPAM::IP->new('');
  $bytes = $ip->bytes;    # "\x0a\x00\x00\x01"

Returns the packed IP address as byte-string. It's the opposite to "new_from_bytes"


Net::IPAM::IP overloads the following operators.


  my $bool = !!$ip;

Always true.


  my $str = "$ip";

Alias for "to_string".


Some Socket::inet_XtoY implementations are hopelessly buggy.

Tests are made during loading and in case of errors, these functions are redefined with a (slower) pure-perl implementation.


Karl Gaissmaier, <karl.gaissmaier(at)uni-ulm.de>


Please report any bugs or feature requests to bug-net-ipam-ip at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-IPAM-IP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


You can find documentation for this module with the perldoc command.

    perldoc Net::IPAM::IP

You can also look for information at:

  • on github



Net::IPAM::Util Net::IPAM::Block Net::IPAM::Tree


This software is copyright (c) 2020 by Karl Gaissmaier.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.