Provided by: tcllib_1.21+dfsg-1_all bug

NAME

       tcllib_ip - IPv4 and IPv6 address manipulation

SYNOPSIS

       package require Tcl  8.2

       package require ip  ?1.4?

       ::ip::version address

       ::ip::is class address

       ::ip::equal address address

       ::ip::normalize address

       ::ip::contract address

       ::ip::distance ipaddr1 ipaddr2

       ::ip::nextIp ipaddr ?offset?

       ::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 hexiplist

       ::ip::ipToLayer2Multicast ipaddr

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

       ::ip::reduceToAggregates prefixlist

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

       ::ip::collapse prefixlist

       ::ip::subtract prefixlist

_________________________________________________________________________________________________

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  -1  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 arguments 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  digits.
              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::distance ipaddr1 ipaddr2
              This command computes the (integer) distance from  IPv4  address  ipaddr1  to  IPv4
              address ipaddr2, i.e. "ipaddr2 - ipaddr1"

                 % ::ip::distance 1.1.1.1  1.1.1.5
                 4

       ::ip::nextIp ipaddr ?offset?
              This command adds the integer offset to the IPv4 address ipaddr and returns the new
              IPv4 address.

                 % ::ip::distance 1.1.1.1  4
                 1.1.1.5

       ::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 equivalent 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.

                 % 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.

                 ::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 dotted 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 dotted form. The mask
              can be specified as either integer number, 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 arguments 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 hexiplist
              This command is similar to ::ip::isOverlap, however the arguments 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

       ::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  specific  nets.  The
              prefixes  are  in  either addr/mask form or in native format.  The result is a list
              containing the non-overlapping 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

       ::ip::collapse prefixlist
              This commands takes a list of prefixes and returns a list prefixes with the largest
              possible subnet masks covering  the  input,  in  this  manner  collapsing  adjacent
              prefixes into larger ranges.

              This  is  different  from  ::ip::reduceToAggregates in that the latter only removes
              specific nets from a list when they are covered by  other  elements  of  the  input
              whereas this command actively merges nets into larger ranges when they are adjacent
              to each other.

              % ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
              1.2.2.0/23

       ::ip::subtract prefixlist
              This command takes a list of prefixes, some of which are prefixed by a dash.  These
              latter  negative  prefixes are used to punch holes into the ranges described by the
              other, positive, prefixes. I.e. the negative  prefixes  are  subtracted  frrom  the
              positive  ones,  resulting  in  a  larger  list of describes describing the covered
              ranges only as positives.

EXAMPLES

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

              % 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  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

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>