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::8888CONSTRUCTORS
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 # 6Returns 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::1Stringification is overloaded with "to_string"
my $ip = Net::IPAM::IP->new('Fe80::0001') // die 'wrong format';
say $ip; # fe80::1TO_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::2decr
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::IPYou 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.