1tcllib_ip(n) Domain Name Service tcllib_ip(n)
2______________________________________________________________________________
6
8 tcllib_ip - IPv4 and IPv6 address manipulation
9
11 package require Tcl 8.2
12 package require ip ?1.4?
14 ::ip::version address
16 ::ip::is class address
18 ::ip::equal address address
20 ::ip::normalize address
22 ::ip::contract address
24 ::ip::distance ipaddr1 ipaddr2
26 ::ip::nextIp ipaddr ?offset?
28 ::ip::prefix address
30 ::ip::type address
32 ::ip::mask address
34 ::ip::prefixToNative prefix
36 ::ip::nativeToPrefix nativeList|native ?-ipv4?
38 ::ip::intToString number ?-ipv4?
40 ::ip::toInteger ipaddr
42 ::ip::toHex ipaddr
44 ::ip::maskToInt ipmask
46 ::ip::broadcastAddress prefix ?-ipv4?
48 ::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?
50 ::ip::lengthToMask maskLength ?-ipv4?
52 ::ip::nextNet ipaddr ipmask ?count? ?-ipv4?
54 ::ip::isOverlap prefix prefix...
56 ::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hex‐
58 iplist
59 ::ip::ipToLayer2Multicast ipaddr
61 ::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?
63 ::ip::reduceToAggregates prefixlist
65 ::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?
67 ::ip::collapse prefixlist
69 ::ip::subtract prefixlist
71______________________________________________________________________________
73
75 This package provides a set of commands to help in parsing, displaying
76 and comparing internet addresses. The package can handle both IPv4 (1)
77 and IPv6 (2) address types.
78
80 ::ip::version address
81 Returns the protocol version of the address (4 or 6), or -1 if
82 the address is neither IPv4 or IPv6.
83 ::ip::is class address
85 Returns true if the address is a member of the given protocol
86 class. The class parameter may be either ipv4 or ipv6 This is
87 effectively a boolean equivalent of the version command. The
88 class argument may be shortened to 4 or 6.
89 ::ip::equal address address
91 Compare two address specifications for equivalence. The argu‐
92 ments are normalized and the address prefix determined (if a
93 mask is supplied). The normalized addresses are then compared
94 bit-by-bit and the procedure returns true if they match.
95 ::ip::normalize address
97 Convert an IPv4 or IPv6 address into a fully expanded version.
98 There are various shorthand ways to write internet addresses,
99 missing out redundant parts or digits. This procedure is the
100 opposite of contract.
101 ::ip::contract address
103 Convert a normalized internet address into a more compact form
104 suitable for displaying to users.
105 ::ip::distance ipaddr1 ipaddr2
107 This command computes the (integer) distance from IPv4 address
108 ipaddr1 to IPv4 address ipaddr2, i.e. "ipaddr2 - ipaddr1"
109 % ::ip::distance 1.1.1.1 1.1.1.5
113 4
114 ::ip::nextIp ipaddr ?offset?
117 This command adds the integer offset to the IPv4 address ipaddr
118 and returns the new IPv4 address.
119 % ::ip::distance 1.1.1.1 4
123 1.1.1.5
124 ::ip::prefix address
127 Returns the address prefix generated by masking the address part
128 with the mask if provided. If there is no mask then it is equiv‐
129 alent to calling normalize
130 ::ip::type address
132 ::ip::mask address
134 If the address supplied includes a mask then this is returned
135 otherwise returns an empty string.
136 ::ip::prefixToNative prefix
138 This command converts the string prefix from dotted form
139 (<ipaddr>/<mask> format) to native (hex) form. Returns a list
140 containing two elements, ipaddress and mask, in this order, in
141 hexadecimal notation.
142 % ip::prefixToNative 1.1.1.0/24
146 0x01010100 0xffffff00
147 ::ip::nativeToPrefix nativeList|native ?-ipv4?
150 This command converts from native (hex) form to dotted form. It
151 is the complement of ::ip::prefixToNative.
152 list nativeList (in)
155 List of several ip addresses in native form. The native
156 form is a list as returned by ::ip::prefixToNative.
157 list native (in)
159 A list as returned by ::ip::prefixToNative.
160 The command returns a list of addresses in dotted form if it was called
162 with a list of addresses. Otherwise a single address in dotted form is
163 returned.
164 % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
168 1.1.1.0/24
169 ::ip::intToString number ?-ipv4?
172 This command converts from an ip address specified as integer
173 number to dotted form.
174 ip::intToString 4294967295
178 255.255.255.255
179 ::ip::toInteger ipaddr
182 This command converts a dotted form ip into an integer number.
183 % ::ip::toInteger 1.1.1.0
187 16843008
188 ::ip::toHex ipaddr
191 This command converts dotted form ip into a hexadecimal number.
192 % ::ip::toHex 1.1.1.0
196 0x01010100
197 ::ip::maskToInt ipmask
200 This command convert an ipmask in either dotted (255.255.255.0)
201 form or mask length form (24) into an integer number.
202 ::ip::maskToInt 24
206 4294967040
207 ::ip::broadcastAddress prefix ?-ipv4?
210 This commands returns a broadcast address in dotted form for the
211 given route prefix, either in the form "addr/mask", or in native
212 form. The result is in dotted form.
213 ::ip::broadcastAddress 1.1.1.0/24
217 1.1.1.255
218 ::ip::broadcastAddress {0x01010100 0xffffff00}
220 0x010101ff
221 ::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?
224 This command converts the dotted or integer form of an ipmask to
225 the mask length form.
226 ::ip::maskToLength 0xffffff00 -ipv4
230 24
231 % ::ip::maskToLength 255.255.255.0
233 24
234 ::ip::lengthToMask maskLength ?-ipv4?
237 This command converts an ipmask in mask length form to its dot‐
238 ted form.
239 ::ip::lengthToMask 24
243 255.255.255.0
244 ::ip::nextNet ipaddr ipmask ?count? ?-ipv4?
247 This command returns an ipaddress in the same position in the
248 count next network. The default value for count is 1.
249 The address can be specified as either integer number or in dot‐
251 ted form. The mask can be specified as either integer number,
252 dotted form, or mask length form.
253 The result is in hex form.
255 ::ip::isOverlap prefix prefix...
257 This command checks if the given ip prefixes overlap. All argu‐
258 ments are in dotted "addr/mask" form. All arguments after the
259 first prefix are compared against the first prefix. The result
260 is a boolean value. It is true if an overlap was found for any
261 of the prefixes.
262 % ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
266 0
267 ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
269 1
270 ::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hex‐
273 iplist
274 This command is similar to ::ip::isOverlap, however the argu‐
275 ments are in the native form, and the form of the result is
276 under greater control of the caller. If the option -all is
277 specified it checks all addresses for overlap, not only until
278 the first one is found. If the option -inline is specified the
279 command returns the overlapping prefix instead of index values.
280 The result of the command is, depending on the specified
282 options,
283 no options
285 The index of the first overlap found, or 0 if there is
286 none.
287 -all A list containing the indices of all overlaps found, or
289 an empty list if there are none.
290 -inline
292 The first overlapping prefix, or an empoty string if
293 there is none.
294 -all -inline
296 A list containing the prefixes of all overlaps found, or
297 an empty list if there are none.
298 % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
302 0
303 % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
305 2
306 ::ip::ipToLayer2Multicast ipaddr
309 This command an converts ipv4 address in dotted form into a
310 layer 2 multicast address, also in dotted form.
311 % ::ip::ipToLayer2Multicast 224.0.0.2
315 01.00.5e.00.00.02
316 ::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?
319 This command returns a host address from a prefix in the form
320 "ipaddr/masklen", also making sure that the result is not an
321 address found in the prefixExcludeList. The result is an ip
322 address in dotted form.
323 %::ip::ipHostFromPrefix 1.1.1.5/24
327 1.1.1.1
328 %::ip::ipHostFromPrefix 1.1.1.1/32
330 1.1.1.1
331 ::ip::reduceToAggregates prefixlist
334 This command finds nets that overlap and filters out the more
335 specific nets. The prefixes are in either addr/mask form or in
336 native format. The result is a list containing the non-overlap‐
337 ping ip prefixes from the input.
338 % ::ip::reduceToAggregates {1.1.1.0/24 1.1.0.0/8 2.1.1.0/24 1.1.1.1/32 }
342 1.0.0.0/8 2.1.1.0/24
343 ::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?
346 This command finds longest prefix match from set of prefixes,
347 given a specific host address. The prefixes in the list are in
348 either native or dotted form, whereas the host address is in
349 either ipprefix format, dotted form, or integer form. The
350 result is the prefix which is the most specific match to the
351 host address.
352 % ::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 }
356 1.1.1.0/28
357 ::ip::collapse prefixlist
360 This commands takes a list of prefixes and returns a list pre‐
361 fixes with the largest possible subnet masks covering the input,
362 in this manner collapsing adjacent prefixes into larger ranges.
363 This is different from ::ip::reduceToAggregates in that the lat‐
365 ter only removes specific nets from a list when they are covered
366 by other elements of the input whereas this command actively
367 merges nets into larger ranges when they are adjacent to each
368 other.
369 % ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
373 1.2.2.0/23
374 ::ip::subtract prefixlist
377 This command takes a list of prefixes, some of which are pre‐
378 fixed by a dash. These latter negative prefixes are used to
379 punch holes into the ranges described by the other, positive,
380 prefixes. I.e. the negative prefixes are subtracted frrom the
381 positive ones, resulting in a larger list of describes describ‐
382 ing the covered ranges only as positives.
383
385 % ip::version ::1
386 6
387 % ip::version 127.0.0.1
388 4
389 % ip::normalize 127/8
393 127.0.0.0/8
394 % ip::contract 192.168.0.0
395 192.168
396 %
397 % ip::normalize fec0::1
398 fec0:0000:0000:0000:0000:0000:0000:0001
399 % ip::contract fec0:0000:0000:0000:0000:0000:0000:0001
400 fec0::1
401 % ip::equal 192.168.0.4/16 192.168.0.0/16
405 1
406 % ip::equal fec0::1/10 fec0::fe01/10
407 1
408
411 [1] Postel, J. "Internet Protocol." RFC 791, September 1981,
412 (http://www.ietf.org/rfc/rfc791.txt)
413 [2] Hinden, R. and Deering, S., "Internet Protocol Version 6 (IPv6)
415 Addressing Architecture", RFC 3513, April 2003
416 (http://www.ietf.org/rfc/rfc3513.txt)
417
419 Pat Thoyts
420
422 This document, and the package it describes, will undoubtedly contain
423 bugs and other problems. Please report such in the category dns of the
424 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
425 report any ideas for enhancements you may have for either package
426 and/or documentation.
427 When proposing code changes, please provide unified diffs, i.e the out‐
429 put of diff -u.
430 Note further that attachments are strongly preferred over inlined
432 patches. Attachments can be made by going to the Edit form of the
433 ticket immediately after its creation, and then using the left-most
434 button in the secondary navigation bar.
435
437 inet(3), ip(7), ipv6(7)
438
440 internet address, ip, ipv4, ipv6, rfc 3513
441
443 Networking
444
446 Copyright (c) 2004, Pat Thoyts
447 Copyright (c) 2005 Aamer Akhter <aakhter@cisco.com>
448tcllib 1.4 tcllib_ip(n)