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('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 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
$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:1.2.3.4 => 1.2.3.4
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);
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.
getaddrinfo()
With no error callback "getaddrs" just calls carp() with underlying Socket errors.
carp()
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.
new_from_name
Net::IPAM::IP implements the following methods:
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.
IPv4 addresses are always treated as smaller than IPv6 addresses (::ffff:0.0.0.0 < ::)
$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
Expand IP address into canonical form, useful for grep, aligned output and lexical sort
grep
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 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'
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.
getnameinfo()
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('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"
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>
<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.
bug-net-ipam-ip at rt.cpan.org
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
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.
To install Net::IPAM::IP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::IPAM::IP
CPAN shell
perl -MCPAN -e shell install Net::IPAM::IP
For more information on module installation, please visit the detailed CPAN module installation guide.