tcllib_ip(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

tcllib_ip(n) — straight outta the Domain Name Service section of tcllib, and bestie, it's a whole vibe. This is the page for tcllib_ip, and yes, it's long, so buckle up 💅

🎀 NAME 🎀

tcllib_ip — IPv4 and IPv6 address manipulation

no cap, that's the whole job description: it manipulates addresses. both flavors. iconic.

📦 SYNOPSIS 📦

okay so here's the roster of commands, all of them, not skipping a single one:

package require Tcl 8.5 9

package require ip ?1.5.1?

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

that's a lot of slashes and colons, I know, but trust the process 🫶

💖 DESCRIPTION 💖

so like, what even is this package? this package hands you a whole set of commands that help you parse, display, and compare internet addresses. that's the trio. parse it, show it off, and compare it to its friends.

and the way it does NOT discriminate between generations — it handles both IPv4 (1) and IPv6 (2) address types. both. equally. periodt. 👑

iykyk, the little (1) and (2) up there are footnote markers, so they're staying exactly where they are. do not touch. 🚫

okay that's the setup, bestie — the actual command breakdowns are coming right up, so don't go anywhere 🌸

✨ COMMANDS ✨

okay bestie, here's the whole toolkit, command by command, no skips, no crumbs 💅

  • ::ip::version address — tells you the protocol version of the address: 4 or 6. And if the address is neither IPv4 nor IPv6? It hits you with -1. periodt.
  • ::ip::is class address — returns true if the address is a member of the given protocol class. The class parameter can be either ipv4 or ipv6. This is basically the boolean bestie of the version command — same energy, just true/false. The class argument can also be shortened to 4 or 6.
  • ::ip::equal address address — compares two address specifications for equivalence. The arguments get normalized, and the address prefix gets determined (if a mask is supplied). Then the normalized addresses get compared bit-by-bit, and the procedure returns true if they match. it's giving "are you two the same person" 🔍
  • ::ip::normalize address — converts an IPv4 or IPv6 address into a fully expanded version. There are so many shorthand ways to write internet addresses — missing out redundant parts or digits — and this is the glow-up that spells everything out. It's the literal opposite of contract.
  • ::ip::contract address — converts a normalized internet address into a more compact form, the kind you'd actually show a human. It's the inverse of normalize, bestie 🎀
  • ::ip::distance ipaddr1 ipaddr2 — 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? — adds the integer offset to the IPv4 address ipaddr and hands you back the new IPv4 address.
% ::ip::distance 1.1.1.1  4
1.1.1.5
bestie the page literally writes distance in that example, not nextIp — not my typo, I'm just the messenger 💀
  • ::ip::prefix address — returns the address prefix you get by masking the address part with the mask, if one is provided. And if there's no mask? Then it's equivalent to calling normalize. easy 💅
  • ::ip::type address — bestie. the page lists this one with literally no description. just the signature. so that's what you get 🎀
  • ::ip::mask address — if the address you supplied includes a mask, this returns it. otherwise it returns an empty string. no mask, no problem.
  • ::ip::prefixToNative prefix — converts the string prefix from dotted form (<ipaddr>/<mask> format) into native (hex) form. Returns a list with two elements — ipaddress and mask, in that order — in hexadecimal notation.
% ip::prefixToNative 1.1.1.0/24
0x01010100 0xffffff00
  • ::ip::nativeToPrefix nativeList|native ?-ipv4? — converts from native (hex) form to dotted form. It's the complement of ::ip::prefixToNative — the other half of the duo 🫶
    • list nativeList (in) — a 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? — converts from an ip address specified as an integer number into dotted form.
ip::intToString 4294967295
255.255.255.255
  • ::ip::toInteger ipaddr — converts a dotted form ip into an integer number.
% ::ip::toInteger 1.1.1.0
16843008
  • ::ip::toHex ipaddr — converts dotted form ip into a hexadecimal number.
% ::ip::toHex 1.1.1.0
0x01010100
  • ::ip::maskToInt ipmask — converts an ipmask in either dotted form (255.255.255.0) or mask length form (24) into an integer number.
::ip::maskToInt 24
4294967040
  • ::ip::broadcastAddress prefix ?-ipv4? — 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? — converts the dotted or integer form of an ipmask into the mask length form. so many input flavours, one iconic output 💅
::ip::maskToLength 0xffffff00 -ipv4
24

% ::ip::maskToLength 255.255.255.0
24
  • ::ip::lengthToMask maskLength ?-ipv4? — converts an ipmask in mask length form into its dotted form.
::ip::lengthToMask 24
255.255.255.0
  • ::ip::nextNet ipaddr ipmask ?count? ?-ipv4? — 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 an integer number or in dotted form. The mask can be specified as either an integer number, dotted form, or mask length form.

The result is in hex form.

  • ::ip::isOverlap prefix prefix... — checks if the given ip prefixes overlap. All the arguments are in dotted "addr/mask" form. Every argument after the first prefix gets compared against the first prefix. The result is a boolean value — true if an overlap was found for any of the prefixes. overlap? caught in 4k 🕵️
% ::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 — similar to ::ip::isOverlap, except the arguments are in native form and the shape of the result is way more under the caller's control. If -all is specified it checks all addresses for overlap, not just until the first one is found. If -inline is specified, the command returns the overlapping prefix instead of index values.

The result of the command is, depending on which options you specified:

  • 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 empty 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 — converts an 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? — returns a host address from a prefix in the form "ipaddr/masklen", and it also makes sure 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 — finds nets that overlap and filters out the more specific nets. The prefixes are in either addr/mask form or 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? — finds the longest prefix match from a set of prefixes, given a specific host address. The prefixes in the list are in either native or dotted form, while 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. main character prefix only 💅
% ::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 — takes a list of prefixes and returns a list of prefixes with the largest possible subnet masks covering the input, collapsing adjacent prefixes into larger ranges. it's literally merging, bestie 🌈

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

% ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
1.2.2.0/23
  • ::ip::subtract prefixlist — 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 from the positive ones, resulting in a larger list describing the covered ranges only as positives. hole-punching, but make it networking 🕳️

🌸 EXAMPLES 🌸

the receipts, bestie:

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

okay bestie, real talk: this doc, and the whole package it's describing, will have bugs and other problems. like, undoubtedly. that's just how software is 💀

so if you find something, please report it in the category dns of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist. and while you're there, if you've got ideas for enhancements for the package and/or the documentation? report those too, we want them 🫶

✨ so you wanna propose code changes ✨

when you do, pls provide unified diffs, i.e. the output of diff -u. that's the vibe, that's the format, no other format.

heads up: attachments are strongly preferred over inlined patches. like, strongly. the way to attach stuff is to go to the Edit form of the ticket immediately after its creation, and then hit the left-most button in the secondary navigation bar. that's the one. that's your girl 💅

👀 SEE ALSO 👀

🔑 KEYWORDS 🔑

internet address, ip, ipv4, ipv6, rfc 3513

🌈 CATEGORY 🌈

Networking

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

and that's the whole page, bestie!! you read all of it, iconic behavior honestly 👑 the footer tells us this is tcllib version 1.5.1, page tcllib_ip(n) — no date stamped on it, she's mysterious like that 🎀✨

now go resolve some addresses. slay 💖

📦 where this page comes from