1Util(3) User Contributed Perl Documentation Util(3)
2
6 NetAddr::IP::Util -- IPv4/6 and 128 bit number utilities
7
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 use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math)
36 :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 :ipv4 => inet_aton, inet_ntoa
44 :ipv6 => ipv6_aton, ipv6_n2x, ipv6_n2d,
46 inet_any2n, inet_n2dx, inet_n2ad
47 ipv4to6, mask4to6, ipanyto6,
48 maskanyto6, ipv6to4
49 :math => hasbits, isIPv4, addconst,
51 add128, sub128, notcontiguous,
52 bin2bcd, bcd2bin, shiftleft
53 $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 NetAddr::IP::Util::lower();
82 NetAddr::IP::Util::upper();
83
85 Un-tar the distribution in an appropriate directory and type:
86 perl Makefile.PL
88 make
89 make test
90 make install
91 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 perl Makefile.PL -noxs
98 make
99 make test
100 make install
101
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 and &
108 or |
109 xor ^
110 ~ compliment
111 in the same manner as 'vec' strings.
113 The IPv6 functions support all rfc1884 formats.
115 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 · $dotquad = inet_ntoa($netaddr);
123 Convert a packed IPv4 network address to a dot-quad IP address.
125 input: packed network address
127 returns: IP address i.e. 10.4.12.123
128 · $netaddr = inet_aton($dotquad);
130 Convert a dot-quad IP address into an IPv4 packed network address.
132 input: IP address i.e. 192.5.16.32
134 returns: packed network address
135 · $ipv6addr = ipv6_aton($ipv6_text);
137 Takes an IPv6 address of the form described in rfc1884 and returns
139 a 128 bit binary RDATA string.
140 input: ipv6 text
142 returns: 128 bit RDATA string
143 · $hex_text = ipv6_n2x($ipv6addr);
145 Takes an IPv6 RDATA string and returns an 8 segment IPv6 hex
147 address
148 input: 128 bit RDATA string
150 returns: x:x:x:x:x:x:x:x
151 · $dec_text = ipv6_n2d($ipv6addr);
153 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 input: 128 bit RDATA string
159 returns: x:x:x:x:x:x:d.d.d.d
160 · $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
162 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 input: dot-quad or rfc1844 address
169 returns: 128 bit IPv6 string
170 · $rv = hasbits($bits128);
172 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 i.e. if (hasbits($bits128)) {
177 &do_something;
178 }
179 or if (hasbits($bits128 & $mask128) {
181 &do_something;
182 }
183 This allows the implementation of logical functions of the form of:
185 if ($bits128 & $mask128) {
187 ...
188 input: 128 bit IPv6 string
190 returns: true if any bits are present
191 · $rv = isIPv4($bits128);
193 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 · $dotquad or $hex_text = inet_n2dx($ipv6naddr);
198 This function does the right thing and returns the text for either
200 a dot-quad IPv4 or a hex notation IPv6 address.
201 input: 128 bit IPv6 string
203 returns: ddd.ddd.ddd.ddd
204 or x:x:x:x:x:x:x:x
205 · $dotquad or $dec_text = inet_n2ad($ipv6naddr);
207 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 input: 128 bit IPv6 string
212 returns: ddd.ddd.ddd.ddd
213 or x:x:x:x:x:x:ddd.ddd.ddd.dd
214 · $ipv6naddr = ipv4to6($netaddr);
216 Convert an ipv4 network address into an ipv6 network address.
218 input: 32 bit network address
220 returns: 128 bit network address
221 · $ipv6naddr = mask4to6($netaddr);
223 Convert an ipv4 network address/mask into an ipv6 network mask.
225 input: 32 bit network/mask address
227 returns: 128 bit network/mask address
228 NOTE: returns the high 96 bits as one's
230 · $ipv6naddr = ipanyto6($netaddr);
232 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 input: 32 or 128 bit network address
237 returns: 128 bit network address
238 · $ipv6naddr = maskanyto6($netaddr);
240 Similar to mask4to6 except that this function takes either an IPv4
242 or IPv6 netmask and always returns a 128 bit IPv6 netmask.
243 input: 32 or 128 bit network mask
245 returns: 128 bit network mask
246 · $netaddr = ipv6to4($pv6naddr);
248 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 input: 128 bit network address
253 returns: 32 bit inet_aton network address
254 · $bitsXn = shiftleft($bits128,$n);
256 input: 128 bit string variable,
258 number of shifts [optional]
259 returns: bits X n shifts
260 NOTE: a single shift is performed
262 if $n is not specified
263 · addconst($ipv6naddr,$signed_32con);
265 Add a signed constant to a 128 bit string variable.
267 input: 128 bit IPv6 string,
269 signed 32 bit integer
270 returns: scalar carry
271 array (carry, result)
272 · add128($ipv6naddr1,$ipv6naddr2);
274 Add two 128 bit string variables.
276 input: 128 bit string var1,
278 128 bit string var2
279 returns: scalar carry
280 array (carry, result)
281 · sub128($ipv6naddr1,$ipv6naddr2);
283 Subtract two 128 bit string variables.
285 input: 128 bit string var1,
287 128 bit string var2
288 returns: scalar carry
289 array (carry, result)
290 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 i.e. if ARG1 >= ARG2 then carry = 1
296 or if ARG1 < ARG2 then carry = 0
297 · ($spurious,$cidr) = notcontiguous($mask128);
299 This function counts the bit positions remaining in the mask when
301 the rightmost '0's are removed.
302 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 · $bcdtext = bin2bcd($bits128);
311 Convert a 128 bit binary string into binary coded decimal text
313 digits.
314 input: 128 bit string variable
316 returns: string of bcd text digits
317 · $bits128 = bcd2bin($bcdtxt);
319 Convert a bcd text string to 128 bit string variable
321 input: string of bcd text digits
323 returns: 128 bit string variable
324 · $modetext = mode;
326 Returns the operating mode of this module.
328 input: none
330 returns: "Pure Perl"
331 or "CC XS"
332 · NetAddr::IP::Util::lower();
334 Return IPv6 strings in lowercase.
336 · NetAddr::IP::Util::upper();
338 Return IPv6 strings in uppercase. This is the default.
340
342 # convert any textual IP address into a 128 bit vector
343 #
344 sub text2vec {
345 my($anyIP,$anyMask) = @_;
346 # not IPv4 bit mask
348 my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
349 my $vecip = inet_any2n($anyIP);
351 my $mask = inet_any2n($anyMask);
352 # 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 ... alternate implementation, a little faster
363 sub text2vec {
365 my($anyIP,$anyMask) = @_;
366 # not IPv4 bit mask
368 my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
369 my $vecip = inet_any2n($anyIP);
371 my $mask = inet_any2n($anyMask);
372 # 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 ... elsewhere
384 $nip = {
385 addr => $vecip,
386 mask => $mask,
387 bits => $bits,
388 };
389 # 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 # 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 # 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
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
458 Michael Robinton <michael@bizsystems.com>
459
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 file: function:
465 miniSocket.inc inet_aton, inet_ntoa
467 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 LICENSE AND WARRANTY
477 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 No warranty of any kind is expressed or implied, by using it you
484 accept any and all the liability.
485
487 Michael Robinton <michael@bizsystems.com>
488perl v5.10.1 2009-06-09 Util(3)