The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-IPAM-IP-4.01
River stage one • 2 direct dependents • 2 total dependents
2 ++
/ Net::IPAM::IP

NAME

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

SYNOPSIS

  use Net::IPAM::IP;

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

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

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

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

  say $ip1;    # 1.2.3.4
  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;      # 1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.e.f

  $ip = Net::IPAM::IP->new_from_bytes( pack( 'C4', 192,    168,   0, 1 ) );                 # 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";  #  8.8.8.8 8.8.4.4 2001:4860:4860::8844 2001:4860:4860::8888

CONSTRUCTORS

new

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

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

Returns undef on illegal input.

new_from_bytes

  $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";  #  8.8.8.8 8.8.4.4 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.

METHODS

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

cmp

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

  $this->cmp($other)

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

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

For even faster sorting import "sort_ip".

version

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

Returns 4 or 6.

to_string

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

TO_JSON

helper method for JSON serialization, just calls $ip->to_string. See also "OBJECT SERIALISATION" in JSON.

incr

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

decr

Returns the previous IP address, returns undef on underflow.

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

expand

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

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

reverse

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

 Net::IPAM::IP->new('fe80::1')->reverse; # '1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.e.f'
 Net::IPAM::IP->new('1.2.3.4')->reverse; # '4.3.2.1'

getname([$error_cb])

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.

LIMITATION:

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.

bytes

  $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('10.0.0.1');
  $bytes = $ip->bytes;    # "\x0a\x00\x00\x01"

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

is4in6

  $ip = Net::IPAM::IP->new('::ffff:1.2.3.4')
  if ( $ip->is4in6 ) {
     ...
  }

Returns true if the IP address is a IPv4-mapped IPv6 address.

FUNCTIONS

sort_ip

  use Net::IPAM::IP 'sort_ip';

  @sorted_ips = sort_ip @unsorted_ips;

Faster sort implemention (Schwartzian transform) as explcit sort function:

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

OPERATORS

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

bool

  my $bool = !!$ip;

Always true.

stringify

  my $str = "$ip";

Alias for "to_string".

WARNING

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.

AUTHOR

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

BUGS

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.

SUPPORT

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

    perldoc Net::IPAM::IP

You can also look for information at:

  • on github

    TODO

SEE ALSO

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

LICENSE AND COPYRIGHT

This software is copyright (c) 2020-2022 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.