1tcllib_ip(n)                  Domain Name Service                 tcllib_ip(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tcllib_ip - IPv4 and IPv6 address manipulation
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require ip  ?1.4?
14
15       ::ip::version address
16
17       ::ip::is class address
18
19       ::ip::equal address address
20
21       ::ip::normalize address
22
23       ::ip::contract address
24
25       ::ip::distance ipaddr1 ipaddr2
26
27       ::ip::nextIp ipaddr ?offset?
28
29       ::ip::prefix address
30
31       ::ip::type address
32
33       ::ip::mask address
34
35       ::ip::prefixToNative prefix
36
37       ::ip::nativeToPrefix nativeList|native ?-ipv4?
38
39       ::ip::intToString number ?-ipv4?
40
41       ::ip::toInteger ipaddr
42
43       ::ip::toHex ipaddr
44
45       ::ip::maskToInt ipmask
46
47       ::ip::broadcastAddress prefix ?-ipv4?
48
49       ::ip::maskToLength dottedMask|integerMask|hexMask ?-ipv4?
50
51       ::ip::lengthToMask maskLength ?-ipv4?
52
53       ::ip::nextNet ipaddr ipmask ?count? ?-ipv4?
54
55       ::ip::isOverlap prefix prefix...
56
57       ::ip::isOverlapNative ?-all? ?-inline? ?-ipv4? hexipaddr hexipmask hex‐
58       iplist
59
60       ::ip::ipToLayer2Multicast ipaddr
61
62       ::ip::ipHostFromPrefix prefix ?-exclude prefixExcludeList?
63
64       ::ip::reduceToAggregates prefixlist
65
66       ::ip::longestPrefixMatch ipaddr prefixlist ?-ipv4?
67
68       ::ip::collapse prefixlist
69
70       ::ip::subtract prefixlist
71
72______________________________________________________________________________
73

DESCRIPTION

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

COMMANDS

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
84       ::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
90       ::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
96       ::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
102       ::ip::contract address
103              Convert a normalized internet address into a more  compact  form
104              suitable for displaying to users.
105
106       ::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
110
111
112                 % ::ip::distance 1.1.1.1  1.1.1.5
113                 4
114
115
116       ::ip::nextIp ipaddr ?offset?
117              This command adds the integer offset to the IPv4 address  ipaddr
118              and returns the new IPv4 address.
119
120
121
122                 % ::ip::distance 1.1.1.1  4
123                 1.1.1.5
124
125
126       ::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
131       ::ip::type address
132
133       ::ip::mask address
134              If  the  address  supplied includes a mask then this is returned
135              otherwise returns an empty string.
136
137       ::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
143
144
145                 % ip::prefixToNative 1.1.1.0/24
146                 0x01010100 0xffffff00
147
148
149       ::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
153
154              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
158              list native (in)
159                     A list as returned by ::ip::prefixToNative.
160
161       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
165
166
167                 % ip::nativeToPrefix {0x01010100 0xffffff00} -ipv4
168                 1.1.1.0/24
169
170
171       ::ip::intToString number ?-ipv4?
172              This  command  converts  from an ip address specified as integer
173              number to dotted form.
174
175
176
177                     ip::intToString 4294967295
178                     255.255.255.255
179
180
181       ::ip::toInteger ipaddr
182              This command converts a dotted form ip into an integer number.
183
184
185
186                 % ::ip::toInteger 1.1.1.0
187                 16843008
188
189
190       ::ip::toHex ipaddr
191              This command converts dotted form ip into a hexadecimal number.
192
193
194
195                 % ::ip::toHex 1.1.1.0
196                 0x01010100
197
198
199       ::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
203
204
205                 ::ip::maskToInt 24
206                 4294967040
207
208
209       ::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
214
215
216                 ::ip::broadcastAddress 1.1.1.0/24
217                 1.1.1.255
218
219                 ::ip::broadcastAddress {0x01010100 0xffffff00}
220                 0x010101ff
221
222
223       ::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
227
228
229                 ::ip::maskToLength 0xffffff00 -ipv4
230                 24
231
232                 % ::ip::maskToLength 255.255.255.0
233                 24
234
235
236       ::ip::lengthToMask maskLength ?-ipv4?
237              This command converts an ipmask in mask length form to its  dot‐
238              ted form.
239
240
241
242                 ::ip::lengthToMask 24
243                 255.255.255.0
244
245
246       ::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
250              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
254              The result is in hex form.
255
256       ::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
263
264
265                % ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32
266                0
267
268                ::ip::isOverlap 1.1.1.0/24 2.1.0.1/32 1.1.1.1/32
269                1
270
271
272       ::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
281              The result  of  the  command  is,  depending  on  the  specified
282              options,
283
284              no options
285                     The  index  of  the first overlap found, or 0 if there is
286                     none.
287
288              -all   A list containing the indices of all overlaps  found,  or
289                     an empty list if there are none.
290
291              -inline
292                     The  first  overlapping  prefix,  or  an empoty string if
293                     there is none.
294
295              -all -inline
296                     A list containing the prefixes of all overlaps found,  or
297                     an empty list if there are none.
298
299
300
301                % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff}}
302                0
303
304                % ::ip::isOverlapNative 0x01010100 0xffffff00 {{0x02010001 0xffffffff} {0x01010101 0xffffffff}}
305                2
306
307
308       ::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
312
313
314                % ::ip::ipToLayer2Multicast 224.0.0.2
315                01.00.5e.00.00.02
316
317
318       ::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
324
325
326                %::ip::ipHostFromPrefix  1.1.1.5/24
327                1.1.1.1
328
329                %::ip::ipHostFromPrefix  1.1.1.1/32
330                1.1.1.1
331
332
333       ::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
339
340
341                % ::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
344
345       ::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
353
354
355                % ::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
358
359       ::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
364              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
370
371
372              % ::ip::collapse {1.2.2.0/24 1.2.3.0/24}
373              1.2.2.0/23
374
375
376       ::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

EXAMPLES

385              % ip::version ::1
386              6
387              % ip::version 127.0.0.1
388              4
389
390
391
392              % 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
402
403
404              % 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
409

REFERENCES

411       [1]    Postel,  J.  "Internet  Protocol."  RFC  791,   September  1981,
412              (http://www.ietf.org/rfc/rfc791.txt)
413
414       [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

AUTHORS

419       Pat Thoyts
420

BUGS, IDEAS, FEEDBACK

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
428       When proposing code changes, please provide unified diffs, i.e the out‐
429       put of diff -u.
430
431       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

SEE ALSO

437       inet(3), ip(7), ipv6(7)
438

KEYWORDS

440       internet address, ip, ipv4, ipv6, rfc 3513
441

CATEGORY

443       Networking
444
446       Copyright (c) 2004, Pat Thoyts
447       Copyright (c) 2005 Aamer Akhter <aakhter@cisco.com>
448
449
450
451
452tcllib                                1.4                         tcllib_ip(n)
Impressum