Michael Robinton > NetAddr-IP > NetAddr::IP::Util

Download:
NetAddr-IP-4.075.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  3
Open  2
View/Report Bugs
Module Version: 1.51   Source  

NAME ^

NetAddr::IP::Util -- IPv4/6 and 128 bit number utilities

SYNOPSIS ^

  use NetAddr::IP::Util qw(
        inet_aton
        inet_ntoa
        ipv6_aton
        ipv6_ntoa
        ipv6_n2x
        ipv6_n2d
        inet_any2n
        hasbits
        isIPv4
        isNewIPv4
        isAnyIPv4
        inet_n2dx
        inet_n2ad
        inet_pton
        inet_ntop
        inet_4map6
        ipv4to6
        mask4to6
        ipanyto6
        maskanyto6
        ipv6to4
        packzeros
        shiftleft
        addconst
        add128
        sub128
        notcontiguous
        bin2bcd
        bcd2bin
        mode
        AF_INET
        AF_INET6
        naip_gethostbyname
  );

  use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math)

  :inet   =>    inet_aton, inet_ntoa, ipv6_aton
                ipv6_ntoa, ipv6_n2x, ipv6_n2d, 
                inet_any2n, inet_n2dx, inet_n2ad, 
                inet_pton, inet_ntop, inet_4map6, 
                ipv4to6, mask4to6, ipanyto6, packzeros
                maskanyto6, ipv6to4, naip_gethostbyname

  :ipv4   =>    inet_aton, inet_ntoa

  :ipv6   =>    ipv6_aton, ipv6_ntoa, ipv6_n2x, 
                ipv6_n2d, inet_any2n, inet_n2dx, 
                inet_n2ad, inet_pton, inet_ntop,
                inet_4map6, ipv4to6, mask4to6,
                ipanyto6, maskanyto6, ipv6to4,
                packzeros, naip_gethostbyname

  :math   =>    hasbits, isIPv4, isNewIPv4, isAnyIPv4,
                addconst, add128, sub128, notcontiguous,
                bin2bcd, bcd2bin, shiftleft

  $dotquad = inet_ntoa($netaddr);
  $netaddr = inet_aton($dotquad);
  $ipv6naddr = ipv6_aton($ipv6_text);
  $ipv6_text = ipvt_ntoa($ipv6naddr);
  $hex_text = ipv6_n2x($ipv6naddr);
  $dec_text = ipv6_n2d($ipv6naddr);
  $hex_text = packzeros($hex_text);
  $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
  $ipv6naddr = inet_4map6($netaddr or $ipv6naddr);
  $rv = hasbits($bits128);
  $rv = isIPv4($bits128);
  $rv = isNewIPv4($bits128);
  $rv = isAnyIPv4($bits128);
  $dotquad or $hex_text = inet_n2dx($ipv6naddr);
  $dotquad or $dec_text = inet_n2ad($ipv6naddr);
  $netaddr = inet_pton($AF_family,$hex_text);
  $hex_text = inet_ntop($AF_family,$netaddr);
  $ipv6naddr = ipv4to6($netaddr);
  $ipv6naddr = mask4to6($netaddr);
  $ipv6naddr = ipanyto6($netaddr);
  $ipv6naddr = maskanyto6($netaddr);
  $netaddr = ipv6to4($pv6naddr);
  $bitsX2 = shiftleft($bits128,$n);
  $carry = addconst($ipv6naddr,$signed_32con);
  ($carry,$ipv6naddr)=addconst($ipv6naddr,$signed_32con);
  $carry = add128($ipv6naddr1,$ipv6naddr2);
  ($carry,$ipv6naddr)=add128($ipv6naddr1,$ipv6naddr2);
  $carry = sub128($ipv6naddr1,$ipv6naddr2);
  ($carry,$ipv6naddr)=sub128($ipv6naddr1,$ipv6naddr2);
  ($spurious,$cidr) = notcontiguous($mask128);
  $bcdtext = bin2bcd($bits128);
  $bits128 = bcd2bin($bcdtxt);
  $modetext = mode;
  ($name,$aliases,$addrtype,$length,@addrs)=naip_gethostbyname(NAME);
  $trueif = havegethostbyname2();

  NetAddr::IP::Util::lower();
  NetAddr::IP::Util::upper();

INSTALLATION ^

Un-tar the distribution in an appropriate directory and type:

        perl Makefile.PL
        make
        make test
        make install

NetAddr::IP::Util installs by default with its primary functions compiled using Perl's XS extensions to build a 'C' library. If you do not have a 'C' complier available or would like the slower Pure Perl version for some other reason, then type:

        perl Makefile.PL -noxs
        make
        make test
        make install

DESCRIPTION ^

NetAddr::IP::Util provides a suite of tools for manipulating and converting IPv4 and IPv6 addresses into 128 bit string context and back to text. The strings can be manipulated with Perl's logical operators:

        and     &
        or      |
        xor     ^
                ~       compliment

in the same manner as 'vec' strings.

The IPv6 functions support all rfc1884 formats.

  i.e.  x:x:x:x:x:x:x:x:x
        x:x:x:x:x:x:x:d.d.d.d
        ::x:x:x
        ::x:d.d.d.d
  and so on...

EXAMPLES ^

  # convert any textual IP address into a 128 bit vector
  #
  sub text2vec {
    my($anyIP,$anyMask) = @_;

  # not IPv4 bit mask
    my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');

    my $vecip   = inet_any2n($anyIP);
    my $mask    = inet_any2n($anyMask);

  # extend mask bits for IPv4
    my $bits = 128;     # default
    unless (hasbits($mask & $notiv4)) {
      $mask |= $notiv4;
      $bits = 32;
    }
    return ($vecip, $mask, $bits);
  }

  ... alternate implementation, a little faster

  sub text2vec {
    my($anyIP,$anyMask) = @_;

  # not IPv4 bit mask
    my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');

    my $vecip   = inet_any2n($anyIP);
    my $mask    = inet_any2n($anyMask);

  # extend mask bits for IPv4
    my $bits = 128;     # default
    if (isIPv4($mask)) {
      $mask |= $notiv4;
      $bits = 32;
    }
    return ($vecip, $mask, $bits);
  }


  ... elsewhere
    $nip = {
        addr    => $vecip,
        mask    => $mask,
        bits    => $bits,
    };

  # return network and broadcast addresses from IP and Mask
  #
  sub netbroad {
    my($nip) = shift;
    my $notmask = ~ $nip->{mask};
    my $bcast   = $nip->{addr} | $notmask;
    my $network = $nip->{addr} & $nip->{mask};
    return ($network, $broadcast);
  }

  # check if address is within a network
  #
  sub within {
    my($nip,$net) = @_;
    my $addr = $nip->{addr}
    my($nw,$bc) = netbroad($net);
  # arg1 >= arg2, sub128 returns true
    return (sub128($addr,$nw) && sub128($bc,$addr))
        ? 1 : 0;
  }

  # truely hard way to do $ip++
  # add a constant, wrapping at netblock boundaries
  # to subtract the constant, negate it before calling
  # 'addwrap' since 'addconst' will extend the sign bits
  #
  sub addwrap {
    my($nip,$const) = @_;
    my $addr    = $nip->{addr};
    my $mask    = $nip->{mask};
    my $bits    = $nip->{bits};
    my $notmask = ~ $mask;
    my $hibits  = $addr & $mask;
    $addr = addconst($addr,$const);
    my $wraponly = $addr & $notmask;
    my $newip = {
        addr    => $hibits | $wraponly,
        mask    => $mask,
        bits    => $bits,
    };
    # bless $newip as appropriate
    return $newip;
  }

  # something more useful
  # increment a /24 net to the NEXT net at the boundry

  my $nextnet = 256;    # for /24
  LOOP:
  while (...continuing) {
    your code....
    ...
    my $lastip = $ip-copy();
    $ip++;
    if ($ip < $lastip) {        # host part wrapped?
  # discard carry
      (undef, $ip->{addr} = addconst($ip->{addr}, $nextnet);
    }
    next LOOP;
  }

EXPORT_OK ^

        inet_aton
        inet_ntoa
        ipv6_aton
        ipv6_ntoa
        ipv6_n2x
        ipv6_n2d
        inet_any2n
        hasbits
        isIPv4
        isNewIPv4
        isAnyIPv4
        inet_n2dx
        inet_n2ad
        inet_pton
        inet_ntop
        inet_4map6
        ipv4to6
        mask4to6
        ipanyto6
        maskanyto6
        ipv6to4
        packzeros
        shiftleft
        addconst
        add128
        sub128
        notcontiguous
        bin2bcd
        bcd2bin
        mode
        naip_gethostbyname
        havegethostbyname2

AUTHOR ^

Michael Robinton <michael@bizsystems.com>

COPYRIGHT ^

Copyright 2003 - 2014, Michael Robinton <michael@bizsystems.com>

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  a) the GNU General Public License as published by the Free
  Software Foundation; either version 2, or (at your option) any
  later version, or

  b) the "Artistic License" which comes with this distribution.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one.

You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the

        Free Software Foundation, Inc.
        51 Franklin Street, Fifth Floor
        Boston, MA 02110-1301 USA.

or visit their web page on the internet at:

        http://www.gnu.org/copyleft/gpl.html.

AUTHOR ^

Michael Robinton <michael@bizsystems.com>

SEE ALSO ^

NetAddr::IP(3), NetAddr::IP::Lite(3), NetAddr::IP::InetBase(3)

syntax highlighting: