1Util(3)               User Contributed Perl Documentation              Util(3)
2
3
4

NAME

6       NetAddr::IP::Util -- IPv4/6 and 128 bit number utilities
7

SYNOPSIS

9         use NetAddr::IP::Util qw(
10               inet_aton
11               inet_ntoa
12               ipv6_aton
13               ipv6_n2x
14               ipv6_n2d
15               inet_any2n
16               hasbits
17               isIPv4
18               inet_n2dx
19               inet_n2ad
20               ipv4to6
21               mask4to6
22               ipanyto6
23               maskanyto6
24               ipv6to4
25               shiftleft
26               addconst
27               add128
28               sub128
29               notcontiguous
30               bin2bcd
31               bcd2bin
32               mode
33         );
34
35         use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math)
36
37         :inet   =>    inet_aton, inet_ntoa, ipv6_aton,
38                       ipv6_n2x, ipv6_n2d, inet_any2n,
39                       inet_n2dx, inet_n2ad, ipv4to6,
40                       mask4to6, ipanyto6, maskanyto6,
41                       ipv6to4
42
43         :ipv4   =>    inet_aton, inet_ntoa
44
45         :ipv6   =>    ipv6_aton, ipv6_n2x, ipv6_n2d,
46                       inet_any2n, inet_n2dx, inet_n2ad
47                       ipv4to6, mask4to6, ipanyto6,
48                       maskanyto6, ipv6to4
49
50         :math   =>    hasbits, isIPv4, addconst,
51                       add128, sub128, notcontiguous,
52                       bin2bcd, bcd2bin, shiftleft
53
54         $dotquad = inet_ntoa($netaddr);
55         $netaddr = inet_aton($dotquad);
56         $ipv6naddr = ipv6_aton($ipv6_text);
57         $hex_text = ipv6_n2x($ipv6naddr);
58         $dec_text = ipv6_n2d($ipv6naddr);
59         $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
60         $rv = hasbits($bits128);
61         $rv = isIPv4($bits128);
62         $dotquad or $hex_text = inet_n2dx($ipv6naddr);
63         $dotquad or $dec_text = inet_n2ad($ipv6naddr);
64         $ipv6naddr = ipv4to6($netaddr);
65         $ipv6naddr = mask4to6($netaddr);
66         $ipv6naddr = ipanyto6($netaddr);
67         $ipv6naddr = maskanyto6($netaddr);
68         $netaddr = ipv6to4($pv6naddr);
69         $bitsX2 = shiftleft($bits128,$n);
70         $carry = addconst($ipv6naddr,$signed_32con);
71         ($carry,$ipv6naddr)=addconst($ipv6naddr,$signed_32con);
72         $carry = add128($ipv6naddr1,$ipv6naddr2);
73         ($carry,$ipv6naddr)=add128($ipv6naddr1,$ipv6naddr2);
74         $carry = sub128($ipv6naddr1,$ipv6naddr2);
75         ($carry,$ipv6naddr)=sub128($ipv6naddr1,$ipv6naddr2);
76         ($spurious,$cidr) = notcontiguous($mask128);
77         $bcdtext = bin2bcd($bits128);
78         $bits128 = bcd2bin($bcdtxt);
79         $modetext = mode;
80
81         NetAddr::IP::Util::lower();
82         NetAddr::IP::Util::upper();
83

INSTALLATION

85       Un-tar the distribution in an appropriate directory and type:
86
87               perl Makefile.PL
88               make
89               make test
90               make install
91
92       NetAddr::IP::Util installs by default with its primary functions
93       compiled using Perl's XS extensions to build a 'C' library. If you do
94       not have a 'C' complier available or would like the slower Pure Perl
95       version for some other reason, then type:
96
97               perl Makefile.PL -noxs
98               make
99               make test
100               make install
101

DESCRIPTION

103       NetAddr::IP::Util provides a suite of tools for manipulating and
104       converting IPv4 and IPv6 addresses into 128 bit string context and back
105       to text. The strings can be manipulated with Perl's logical operators:
106
107               and     &
108               or      |
109               xor     ^
110                       ~       compliment
111
112       in the same manner as 'vec' strings.
113
114       The IPv6 functions support all rfc1884 formats.
115
116         i.e.  x:x:x:x:x:x:x:x:x
117               x:x:x:x:x:x:x:d.d.d.d
118               ::x:x:x
119               ::x:d.d.d.d
120         and so on...
121
122       ·   $dotquad = inet_ntoa($netaddr);
123
124           Convert a packed IPv4 network address to a dot-quad IP address.
125
126             input:        packed network address
127             returns:      IP address i.e. 10.4.12.123
128
129       ·   $netaddr = inet_aton($dotquad);
130
131           Convert a dot-quad IP address into an IPv4 packed network address.
132
133             input:        IP address i.e. 192.5.16.32
134             returns:      packed network address
135
136       ·   $ipv6addr = ipv6_aton($ipv6_text);
137
138           Takes an IPv6 address of the form described in rfc1884 and returns
139           a 128 bit binary RDATA string.
140
141             input:        ipv6 text
142             returns:      128 bit RDATA string
143
144       ·   $hex_text = ipv6_n2x($ipv6addr);
145
146           Takes an IPv6 RDATA string and returns an 8 segment IPv6 hex
147           address
148
149             input:        128 bit RDATA string
150             returns:      x:x:x:x:x:x:x:x
151
152       ·   $dec_text = ipv6_n2d($ipv6addr);
153
154           Takes an IPv6 RDATA string and returns a mixed hex - decimal IPv6
155           address with the 6 uppermost chunks in hex and the lower 32 bits in
156           dot-quad representation.
157
158             input:        128 bit RDATA string
159             returns:      x:x:x:x:x:x:d.d.d.d
160
161       ·   $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
162
163           This function converts a text IPv4 or IPv6 address in text format
164           in any standard notation into a 128 bit IPv6 string address. It
165           prefixes any dot-quad address (if found) with '::' and passes it to
166           ipv6_aton.
167
168             input:        dot-quad or rfc1844 address
169             returns:      128 bit IPv6 string
170
171       ·   $rv = hasbits($bits128);
172
173           This function returns true if there are one's present in the 128
174           bit string and false if all the bits are zero.
175
176             i.e.  if (hasbits($bits128)) {
177                     &do_something;
178                   }
179
180             or    if (hasbits($bits128 & $mask128) {
181                     &do_something;
182                   }
183
184           This allows the implementation of logical functions of the form of:
185
186                   if ($bits128 & $mask128) {
187                       ...
188
189             input:        128 bit IPv6 string
190             returns:      true if any bits are present
191
192       ·   $rv = isIPv4($bits128);
193
194           This function returns true if there are no on bits present in the
195           IPv6 portion of the 128 bit string and false otherwise.
196
197       ·   $dotquad or $hex_text = inet_n2dx($ipv6naddr);
198
199           This function does the right thing and returns the text for either
200           a dot-quad IPv4 or a hex notation IPv6 address.
201
202             input:        128 bit IPv6 string
203             returns:      ddd.ddd.ddd.ddd
204                       or  x:x:x:x:x:x:x:x
205
206       ·   $dotquad or $dec_text = inet_n2ad($ipv6naddr);
207
208           This function does the right thing and returns the text for either
209           a dot-quad IPv4 or a hex::decimal notation IPv6 address.
210
211             input:        128 bit IPv6 string
212             returns:      ddd.ddd.ddd.ddd
213                       or  x:x:x:x:x:x:ddd.ddd.ddd.dd
214
215       ·   $ipv6naddr = ipv4to6($netaddr);
216
217           Convert an ipv4 network address into an ipv6 network address.
218
219             input:        32 bit network address
220             returns:      128 bit network address
221
222       ·   $ipv6naddr = mask4to6($netaddr);
223
224           Convert an ipv4 network address/mask into an ipv6 network mask.
225
226             input:        32 bit network/mask address
227             returns:      128 bit network/mask address
228
229           NOTE: returns the high 96 bits as one's
230
231       ·   $ipv6naddr = ipanyto6($netaddr);
232
233           Similar to ipv4to6 except that this function takes either an IPv4
234           or IPv6 input and always returns a 128 bit IPv6 network address.
235
236             input:        32 or 128 bit network address
237             returns:      128 bit network address
238
239       ·   $ipv6naddr = maskanyto6($netaddr);
240
241           Similar to mask4to6 except that this function takes either an IPv4
242           or IPv6 netmask and always returns a 128 bit IPv6 netmask.
243
244             input:        32 or 128 bit network mask
245             returns:      128 bit network mask
246
247       ·   $netaddr = ipv6to4($pv6naddr);
248
249           Truncate the upper 96 bits of a 128 bit address and return the
250           lower 32 bits. Returns an IPv4 address as returned by inet_aton.
251
252             input:        128 bit network address
253             returns:      32 bit inet_aton network address
254
255       ·   $bitsXn = shiftleft($bits128,$n);
256
257             input:        128 bit string variable,
258                           number of shifts [optional]
259             returns:      bits X n shifts
260
261             NOTE: a single shift is performed
262                   if $n is not specified
263
264       ·   addconst($ipv6naddr,$signed_32con);
265
266           Add a signed constant to a 128 bit string variable.
267
268             input:        128 bit IPv6 string,
269                           signed 32 bit integer
270             returns:  scalar      carry
271                       array       (carry, result)
272
273       ·   add128($ipv6naddr1,$ipv6naddr2);
274
275           Add two 128 bit string variables.
276
277             input:        128 bit string var1,
278                           128 bit string var2
279             returns:  scalar      carry
280                       array       (carry, result)
281
282       ·   sub128($ipv6naddr1,$ipv6naddr2);
283
284           Subtract two 128 bit string variables.
285
286             input:        128 bit string var1,
287                           128 bit string var2
288             returns:  scalar      carry
289                       array       (carry, result)
290
291           Note: The carry from this operation is the result of adding the
292           one's complement of ARG2 +1 to the ARG1. It is logically NOT
293           borrow.
294
295                   i.e.    if ARG1 >= ARG2 then carry = 1
296                   or      if ARG1  < ARG2 then carry = 0
297
298       ·   ($spurious,$cidr) = notcontiguous($mask128);
299
300           This function counts the bit positions remaining in the mask when
301           the rightmost '0's are removed.
302
303                   input:  128 bit netmask
304                   returns true if there are spurious
305                               zero bits remaining in the
306                               mask, false if the mask is
307                               contiguous one's,
308                           128 bit cidr number
309
310       ·   $bcdtext = bin2bcd($bits128);
311
312           Convert a 128 bit binary string into binary coded decimal text
313           digits.
314
315             input:        128 bit string variable
316             returns:      string of bcd text digits
317
318       ·   $bits128 = bcd2bin($bcdtxt);
319
320           Convert a bcd text string to 128 bit string variable
321
322             input:        string of bcd text digits
323             returns:      128 bit string variable
324
325       ·   $modetext = mode;
326
327           Returns the operating mode of this module.
328
329                   input:          none
330                   returns:        "Pure Perl"
331                              or   "CC XS"
332
333       ·   NetAddr::IP::Util::lower();
334
335           Return IPv6 strings in lowercase.
336
337       ·   NetAddr::IP::Util::upper();
338
339           Return IPv6 strings in uppercase.  This is the default.
340

EXAMPLES

342         # convert any textual IP address into a 128 bit vector
343         #
344         sub text2vec {
345           my($anyIP,$anyMask) = @_;
346
347         # not IPv4 bit mask
348           my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
349
350           my $vecip   = inet_any2n($anyIP);
351           my $mask    = inet_any2n($anyMask);
352
353         # extend mask bits for IPv4
354           my $bits = 128;     # default
355           unless (hasbits($mask & $notiv4)) {
356             $mask |= $notiv4;
357             $bits = 32;
358           }
359           return ($vecip, $mask, $bits);
360         }
361
362         ... alternate implementation, a little faster
363
364         sub text2vec {
365           my($anyIP,$anyMask) = @_;
366
367         # not IPv4 bit mask
368           my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
369
370           my $vecip   = inet_any2n($anyIP);
371           my $mask    = inet_any2n($anyMask);
372
373         # extend mask bits for IPv4
374           my $bits = 128;     # default
375           if (isIPv4($mask)) {
376             $mask |= $notiv4;
377             $bits = 32;
378           }
379           return ($vecip, $mask, $bits);
380         }
381
382
383         ... elsewhere
384           $nip = {
385               addr    => $vecip,
386               mask    => $mask,
387               bits    => $bits,
388           };
389
390         # return network and broadcast addresses from IP and Mask
391         #
392         sub netbroad {
393           my($nip) = shift;
394           my $notmask = ~ $nip->{mask};
395           my $bcast   = $nip->{addr} | $notmask;
396           my $network = $nip->{addr} & $nip->{mask};
397           return ($network, $broadcast);
398         }
399
400         # check if address is within a network
401         #
402         sub within {
403           my($nip,$net) = @_;
404           my $addr = $nip->{addr}
405           my($nw,$bc) = netbroad($net);
406         # arg1 >= arg2, sub128 returns true
407           return (sub128($addr,$nw) && sub128($bc,$addr))
408               ? 1 : 0;
409         }
410
411         # add a constant, wrapping at netblock boundaries
412         # to subtract the constant, negate it before calling
413         # 'addwrap' since 'addconst' will extend the sign bits
414         #
415         sub addwrap {
416           my($nip,$const) = @_;
417           my $mask    = $nip->{addr};
418           my $bits    = $nip->{bits};
419           my $notmask = ~ $mask;
420           my $hibits  = $addr & $mask;
421           my $addr = addconst($addr,$const);
422           my $wraponly = $addr & $notmask;
423           my $newip = {
424               addr    => $hibits | $wraponly,
425               mask    => $mask,
426               bits    => $bits,
427           };
428           # bless $newip as appropriate
429           return $newip;
430         }
431

EXPORT_OK

433               inet_aton
434               inet_ntoa
435               ipv6_aton
436               ipv6_n2x
437               ipv6_n2d
438               inet_any2n
439               hasbits
440               isIPv4
441               inet_n2dx
442               inet_n2ad
443               ipv4to6
444               mask4to6
445               ipanyto6
446               maskanyto6
447               ipv6to4
448               shiftleft
449               addconst
450               add128
451               sub128
452               notcontiguous
453               bin2bcd
454               bcd2bin
455               mode
456

AUTHOR

458       Michael Robinton <michael@bizsystems.com>
459

ACKNOWLEDGMENTS

461       The following functions are used in whole or in part as include files
462       to Util.xs. The copyright is include in the file.
463
464         file:              function:
465
466         miniSocket.inc  inet_aton, inet_ntoa
467
468       inet_aton, inet_ntoa are from the perl-5.8.0 release by Larry Wall,
469       copyright 1989-2002. inet_aton, inet_ntoa code is current through
470       perl-5.9.3 release.  Thank you Larry for making PERL possible for all
471       of us.
472
474       Copyright 2003 - 2008, Michael Robinton <michael@bizsystems.com>
475
476       LICENSE AND WARRANTY
477
478       This software is (c) Michael Robinton.  It can be used under the terms
479       of the perl artistic license provided  that proper credit for the work
480       of the  author is  preserved in  the form  of this  copyright  notice
481       and license for this module.
482
483       No warranty of any kind is  expressed or implied, by using it you
484       accept any and all the liability.
485

AUTHOR

487       Michael Robinton <michael@bizsystems.com>
488
489
490
491perl v5.12.0                      2009-06-09                           Util(3)
Impressum