


tcllib_ip(n)           Domain Name Service           tcllib_ip(n)


______________________________________________________________________________

NAME
       tcllib_ip - IPv4 and IPv6 address manipulation

SYNOPSIS
       package require Tcl  8.2

       package require ip  ?1.1.3?

       ::ip::version address

       ::ip::is class address

       ::ip::equal address address

       ::ip::normalize address

       ::ip::contract address

       ::ip::prefix address

       ::ip::type address

       ::ip::mask address

       ::ip::prefixToNative prefix

       ::ip::nativeToPrefix nativeList|native ?-ipv4?

       ::ip::intToString number ?-ipv4?

       ::ip::toInteger ipaddr

       ::ip::toHex ipaddr

       ::ip::maskToInt ipmask

       ::ip::broadcastAddress prefix ?-ipv4?

       ::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?

       ::ip::lengthToMask maskLength ?-ipv4?

       ::ip::nextNet ipaddr ipmask ?count? ?-ipv4?

       ::ip::isOverlap prefix prefix...

       ::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hex-
       iplist

       ::ip::ipToLayer2Multicast ipaddr

       ::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?



dns                           1.1.3                             1





tcllib_ip(n)           Domain Name Service           tcllib_ip(n)


       ::ip::reduceToAggregates prefixlist

       ::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?

_________________________________________________________________

DESCRIPTION
       This package provides a set of commands to help in parsing,  displaying
       and  comparing internet addresses. The package can handle both IPv4 (1)
       and IPv6 (2) address types.

COMMANDS
       ::ip::version address
              Returns the protocol version of the address (4 or 6) or 0 if the
              address is neither IPv4 or IPv6.

       ::ip::is class address
              Returns  true  if  the address is a member of the given protocol
              class. The class parameter may be either ipv4 or  ipv6  This  is
              effectively  a  boolean  equivalent  of the version command. The
              class argument may be shortened to 4 or 6.

       ::ip::equal address address
              Compare two address specifications for  equivalence.  The  argu-
              ments  are  normalized  and  the address prefix determined (if a
              mask is supplied). The normalized addresses  are  then  compared
              bit-by-bit and the procedure returns true if they match.

       ::ip::normalize address
              Convert  an  IPv4 or IPv6 address into a fully expanded version.
              There are various shorthand ways to  write  internet  addresses,
              missing  out  redundant  parts  or digts.. This procedure is the
              opposite of contract.

       ::ip::contract address
              Convert a normalized internet address into a more  compact  form
              suitable for displaying to users.

       ::ip::prefix address
              Returns the address prefix generated by masking the address part
              with the mask if provided. If there is no mask then it is equiv-
              alent to calling normalize

       ::ip::type address

       ::ip::mask address
              If  the  address  supplied includes a mask then this is returned
              otherwise returns an empty string.

       ::ip::prefixToNative prefix
              This  command  converts  the  string  prefix  from  dotted  form
              (<ipaddr>/<mask>  format)  to  native (hex) form. Returns a list
              containing two elements, ipaddress and mask, in this  order,  in
              hexadecimal notation.



dns                           1.1.3                             2





tcllib_ip(n)           Domain Name Service           tcllib_ip(n)


                 % ip::prefixToNative 1.1.1.0/24
                 0x01010100 0xffffff00


       ::ip::nativeToPrefix nativeList|native ?-ipv4?
              This command converts from native (hex) form to dotted form.  It
              is the complement of ::ip::prefixToNative.


              list nativeList (in)
                     List of several ip addresses in native form.  The  native
                     form is a list as returned by ::ip::prefixToNative.

              list native (in)
                     A list as returned by ::ip::prefixToNative.

       The command returns a list of addresses in dotted form if it was called
       with a list of addresses. Otherwise a single address in dotted form  is
       returned.


          % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
          1.1.1.0/24


       ::ip::intToString number ?-ipv4?
              This  command  converts  from an ip address specified as integer
              number to dotted form.


                     ip::intToString 4294967295
                     255.255.255.255


       ::ip::toInteger ipaddr
              This command converts a dotted form ip into an integer number.


                 % ::ip::toInteger 1.1.1.0
                 16843008


       ::ip::toHex ipaddr
              This command converts dotted form ip into a hexadecimal  number.


                 % ::ip::toHex 1.1.1.0
                 0x01010100


       ::ip::maskToInt ipmask
              This  command convert an ipmask in either dotted (255.255.255.0)
              form or mask length form (24) into an integer number.




dns                           1.1.3                             3





tcllib_ip(n)           Domain Name Service           tcllib_ip(n)


                 ::ip::maskToInt 24
                 4294967040


       ::ip::broadcastAddress prefix ?-ipv4?
              This commands returns a broadcast address in dotted form for the
              given route prefix, either in the form "addr/mask", or in native
              form. The result is in dotted form.


                 ::ip::broadcastAddress 1.1.1.0/24
                 1.1.1.255

                 ::ip::broadcastAddress {0x01010100 0xffffff00}
                 0x010101ff





       ::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?


              This command converts the dotted or integer form of an ipmask to
              the mask length form.







                 ::ip::maskToLength 0xffffff00 -ipv4
                 24

                 % ::ip::maskToLength 255.255.255.0
                 24


       ::ip::lengthToMask maskLength ?-ipv4?
              This  command converts an ipmask in mask length form to its dot-
              ted form.


                 ::ip::lengthToMask 24
                 255.255.255.0


       ::ip::nextNet ipaddr ipmask ?count? ?-ipv4?
              This command returns an ipaddress in the same  position  in  the
              count next network. The default value for count is 1.

              The address can be specified as either integer number or in dot-
              ted form. The mask can be specified as  either  integer  number,



dns                           1.1.3                             4





tcllib_ip(n)           Domain Name Service           tcllib_ip(n)


              dotted form, or mask length form.

              The result is in hex form.

       ::ip::isOverlap prefix prefix...
              This command checks if the given ip prefixes overlap.  All argu-
              ments are in dotted "addr/mask" form. All  arguments  after  the
              first  prefix  are compared against the first prefix. The result
              is a boolean value. It is true if an overlap was found  for  any
              of the prefixes.


                % ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
                0

                ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
                1


       ::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hex-
       iplist
              This command is similar to ::ip::isOverlap,  however  the  argu-
              ments  are  in  the  native  form, and the form of the result is
              under greater control of the caller.   If  the  option  -all  is
              specified  it  checks  all addresses for overlap, not only until
              the first one is found.  If the option -inline is specified  the
              command  returns the overlapping prefix instead of index values.

              The result  of  the  command  is,  depending  on  the  specified
              options,

              no options
                     The  index  of  the first overlap found, or 0 if there is
                     none.

              -all   A list containing the indices of all overlaps  found,  or
                     an empty list if there are none.

              -inline
                     The  first  overlapping  prefix,  or  an empoty string if
                     there is none.

              -all -inline
                     A list containing the prefixes of all overlaps found,  or
                     an empty list if there are none.


         % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
         0

         % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
         2





dns                           1.1.3                             5





tcllib_ip(n)           Domain Name Service           tcllib_ip(n)


       ::ip::ipToLayer2Multicast ipaddr
              This  command  an  converts  ipv4  address in dotted form into a
              layer 2 multicast address, also in dotted form.


                % ::ip::ipToLayer2Multicast 224.0.0.2
                01.00.5e.00.00.02


       ::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?
              This command returns a host address from a prefix  in  the  form
              "ipaddr/masklen",  also  making  sure  that the result is not an
              address found in the prefixExcludeList.  The  result  is  an  ip
              address in dotted form.


                %::ip::ipHostFromPrefix  1.1.1.5/24
                1.1.1.1

                %::ip::ipHostFromPrefix  1.1.1.1/32
                1.1.1.1


       ::ip::reduceToAggregates prefixlist
              This  command  finds  nets that overlap and filters out the more
              specifc nets. The prefixes are in either addr/mask  form  or  in
              native format.  The result is a list containing the non-overlap-
              ping ip prefixes from the input.


                % ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8  2.1.1.0/24 1.1.1.1/32 }
                1.0.0.0/8 2.1.1.0/24


       ::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?
              This command finds longest prefix match from  set  of  prefixes,
              given  a  specific host address. The prefixes in the list are in
              either native or dotted form, whereas the  host  address  is  in
              either  ipprefix  format,  dotted  form,  or  integer form.  The
              result is the prefix which is the most  specific  match  to  the
              host address.


                % ::ip::longestPrefixMatch 1.1.1.1 {1.1.1.0/24 1.0.0.0/8  2.1.1.0/24 1.1.1.0/28 }
                1.1.1.0/28



EXAMPLES
       % ip::version ::1
       6
       % ip::version 127.0.0.1
       4




dns                           1.1.3                             6





tcllib_ip(n)           Domain Name Service           tcllib_ip(n)


       % ip::normalize 127/8
       127.0.0.0/8
       % ip::contract 192.168.0.0
       192.168
       %
       % ip::normalize fec0::1
       fec0:0000:0000:0000:0000:0000:0000:0001
       % ip::contract fec0:0000:0000:0000:0000:0000:0000:0001
       fec0::1


       % ip::equal 192.168.0.4/16 192.168.0.0/16
       1
       % ip::equal fec0::1/10 fec0::fe01/10
       1


REFERENCES
       [1]    Postel,  J.  "Internet  Protocol."  RFC  791,   September  1981,
              (http://www.ietf.org/rfc/rfc791.txt)

       [2]    Hinden, R. and Deering, S., "Internet Protocol Version 6  (IPv6)
              Addressing     Architecture",     RFC     3513,    April    2003
              (http://www.ietf.org/rfc/rfc3513.txt)


AUTHORS
       Pat Thoyts

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs and other problems.  Please report such in the category dns of the
       Tcllib  SF  Trackers  [http://sourceforge.net/tracker/?group_id=12883].
       Please  also  report any ideas for enhancements you may have for either
       package and/or documentation.

SEE ALSO
       inet(3), ip(7), ipv6(7)

KEYWORDS
       internet address, ip, ipv4, ipv6, rfc 3513

CATEGORY
       Networking

COPYRIGHT
       Copyright (c) 2004, Pat Thoyts
       Copyright (c) 2005 Aamer Akhter <aakhter@cisco.com>









dns                           1.1.3                             7


