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_ntoa
14 ipv6_n2x
15 ipv6_n2d
16 inet_any2n
17 hasbits
18 isIPv4
19 isNewIPv4
20 isAnyIPv4
21 inet_n2dx
22 inet_n2ad
23 inet_pton
24 inet_ntop
25 inet_4map6
26 ipv4to6
27 mask4to6
28 ipanyto6
29 maskanyto6
30 ipv6to4
31 packzeros
32 shiftleft
33 addconst
34 add128
35 sub128
36 notcontiguous
37 bin2bcd
38 bcd2bin
39 mode
40 AF_INET
41 AF_INET6
42 naip_gethostbyname
43 );
44 use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math)
46 :inet => inet_aton, inet_ntoa, ipv6_aton
48 ipv6_ntoa, ipv6_n2x, ipv6_n2d,
49 inet_any2n, inet_n2dx, inet_n2ad,
50 inet_pton, inet_ntop, inet_4map6,
51 ipv4to6, mask4to6, ipanyto6, packzeros
52 maskanyto6, ipv6to4, naip_gethostbyname
53 :ipv4 => inet_aton, inet_ntoa
55 :ipv6 => ipv6_aton, ipv6_ntoa, ipv6_n2x,
57 ipv6_n2d, inet_any2n, inet_n2dx,
58 inet_n2ad, inet_pton, inet_ntop,
59 inet_4map6, ipv4to6, mask4to6,
60 ipanyto6, maskanyto6, ipv6to4,
61 packzeros, naip_gethostbyname
62 :math => hasbits, isIPv4, isNewIPv4, isAnyIPv4,
64 addconst, add128, sub128, notcontiguous,
65 bin2bcd, bcd2bin, shiftleft
66 $dotquad = inet_ntoa($netaddr);
68 $netaddr = inet_aton($dotquad);
69 $ipv6naddr = ipv6_aton($ipv6_text);
70 $ipv6_text = ipvt_ntoa($ipv6naddr);
71 $hex_text = ipv6_n2x($ipv6naddr);
72 $dec_text = ipv6_n2d($ipv6naddr);
73 $hex_text = packzeros($hex_text);
74 $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
75 $ipv6naddr = inet_4map6($netaddr or $ipv6naddr);
76 $rv = hasbits($bits128);
77 $rv = isIPv4($bits128);
78 $rv = isNewIPv4($bits128);
79 $rv = isAnyIPv4($bits128);
80 $dotquad or $hex_text = inet_n2dx($ipv6naddr);
81 $dotquad or $dec_text = inet_n2ad($ipv6naddr);
82 $netaddr = inet_pton($AF_family,$hex_text);
83 $hex_text = inet_ntop($AF_family,$netaddr);
84 $ipv6naddr = ipv4to6($netaddr);
85 $ipv6naddr = mask4to6($netaddr);
86 $ipv6naddr = ipanyto6($netaddr);
87 $ipv6naddr = maskanyto6($netaddr);
88 $netaddr = ipv6to4($pv6naddr);
89 $bitsX2 = shiftleft($bits128,$n);
90 $carry = addconst($ipv6naddr,$signed_32con);
91 ($carry,$ipv6naddr)=addconst($ipv6naddr,$signed_32con);
92 $carry = add128($ipv6naddr1,$ipv6naddr2);
93 ($carry,$ipv6naddr)=add128($ipv6naddr1,$ipv6naddr2);
94 $carry = sub128($ipv6naddr1,$ipv6naddr2);
95 ($carry,$ipv6naddr)=sub128($ipv6naddr1,$ipv6naddr2);
96 ($spurious,$cidr) = notcontiguous($mask128);
97 $bcdtext = bin2bcd($bits128);
98 $bits128 = bcd2bin($bcdtxt);
99 $modetext = mode;
100 ($name,$aliases,$addrtype,$length,@addrs)=naip_gethostbyname(NAME);
101 $trueif = havegethostbyname2();
102 NetAddr::IP::Util::lower();
104 NetAddr::IP::Util::upper();
105
107 Un-tar the distribution in an appropriate directory and type:
108 perl Makefile.PL
110 make
111 make test
112 make install
113 NetAddr::IP::Util installs by default with its primary functions
115 compiled using Perl's XS extensions to build a 'C' library. If you do
116 not have a 'C' complier available or would like the slower Pure Perl
117 version for some other reason, then type:
118 perl Makefile.PL -noxs
120 make
121 make test
122 make install
123
125 NetAddr::IP::Util provides a suite of tools for manipulating and
126 converting IPv4 and IPv6 addresses into 128 bit string context and back
127 to text. The strings can be manipulated with Perl's logical operators:
128 and &
130 or |
131 xor ^
132 ~ compliment
133 in the same manner as 'vec' strings.
135 The IPv6 functions support all rfc1884 formats.
137 i.e. x:x:x:x:x:x:x:x:x
139 x:x:x:x:x:x:x:d.d.d.d
140 ::x:x:x
141 ::x:d.d.d.d
142 and so on...
143 • $dotquad = inet_ntoa($netaddr);
145 Convert a packed IPv4 network address to a dot-quad IP address.
147 input: packed network address
149 returns: IP address i.e. 10.4.12.123
150 • $netaddr = inet_aton($dotquad);
152 Convert a dot-quad IP address into an IPv4 packed network address.
154 input: IP address i.e. 192.5.16.32
156 returns: packed network address
157 • $ipv6addr = ipv6_aton($ipv6_text);
159 Takes an IPv6 address of the form described in rfc1884 and returns
161 a 128 bit binary RDATA string.
162 input: ipv6 text
164 returns: 128 bit RDATA string
165 • $ipv6_text = ipv6_ntoa($ipv6naddr);
167 Convert a 128 bit binary IPv6 address to compressed rfc 1884 text
169 representation.
170 input: 128 bit RDATA string
172 returns: ipv6 text
173 • $hex_text = ipv6_n2x($ipv6addr);
175 Takes an IPv6 RDATA string and returns an 8 segment IPv6 hex
177 address
178 input: 128 bit RDATA string
180 returns: x:x:x:x:x:x:x:x
181 • $dec_text = ipv6_n2d($ipv6addr);
183 Takes an IPv6 RDATA string and returns a mixed hex - decimal IPv6
185 address with the 6 uppermost chunks in hex and the lower 32 bits in
186 dot-quad representation.
187 input: 128 bit RDATA string
189 returns: x:x:x:x:x:x:d.d.d.d
190 • $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
192 This function converts a text IPv4 or IPv6 address in text format
194 in any standard notation into a 128 bit IPv6 string address. It
195 prefixes any dot-quad address (if found) with '::' and passes it to
196 ipv6_aton.
197 input: dot-quad or rfc1844 address
199 returns: 128 bit IPv6 string
200 • $rv = hasbits($bits128);
202 This function returns true if there are one's present in the 128
204 bit string and false if all the bits are zero.
205 i.e. if (hasbits($bits128)) {
207 &do_something;
208 }
209 or if (hasbits($bits128 & $mask128) {
211 &do_something;
212 }
213 This allows the implementation of logical functions of the form of:
215 if ($bits128 & $mask128) {
217 ...
218 input: 128 bit IPv6 string
220 returns: true if any bits are present
221 • $ipv6naddr = inet_4map6($netaddr or $ipv6naddr
223 This function returns an ipV6 network address with the first 80
225 bits set to zero and the next 16 bits set to one, while the last 32
226 bits are filled with the ipV4 address.
227 input: ipV4 netaddr
229 or ipV6 netaddr
230 returns: ipV6 netaddr
231 returns: undef on error
233 An ipV6 network address must be in one of the two compatible ipV4
235 mapped address spaces. i.e.
236 ::ffff::d.d.d.d or ::d.d.d.d
238 • $rv = isIPv4($bits128);
240 This function returns true if there are no on bits present in the
242 IPv6 portion of the 128 bit string and false otherwise.
243 i.e. the address must be of the form - ::d.d.d.d
245 Note: this is an old and deprecated ipV4 compatible ipV6 address
247 • $rv = isNewIPv4($bits128);
249 This function return true if the IPv6 128 bit string is of the form
251 ::ffff::d.d.d.d
253 • $rv = isAnyIPv4($bits128);
255 This function return true if the IPv6 bit string is of the form
257 ::d.d.d.d or ::ffff::d.d.d.d
259 • $dotquad or $hex_text = inet_n2dx($ipv6naddr);
261 This function does the right thing and returns the text for either
263 a dot-quad IPv4 or a hex notation IPv6 address.
264 input: 128 bit IPv6 string
266 returns: ddd.ddd.ddd.ddd
267 or x:x:x:x:x:x:x:x
268 • $dotquad or $dec_text = inet_n2ad($ipv6naddr);
270 This function does the right thing and returns the text for either
272 a dot-quad IPv4 or a hex::decimal notation IPv6 address.
273 input: 128 bit IPv6 string
275 returns: ddd.ddd.ddd.ddd
276 or x:x:x:x:x:x:ddd.ddd.ddd.dd
277 • $netaddr = inet_pton($AF_family,$hex_text);
279 This function takes an IP address in IPv4 or IPv6 text format and
281 converts it into binary format. The type of IP address conversion
282 is controlled by the FAMILY argument.
283 • $hex_text = inet_ntop($AF_family,$netaddr);
285 This function takes and IP address in binary format and converts it
287 into text format. The type of IP address conversion is controlled
288 by the FAMILY argument.
289 NOTE: inet_ntop ALWAYS returns lowercase characters.
291 • $hex_text = packzeros($hex_text);
293 This function optimizes and rfc 1884 IPv6 hex address to reduce the
295 number of long strings of zero bits as specified in rfc 1884, 2.2
296 (2) by substituting :: for the first occurence of the longest
297 string of zeros in the address.
298 • $ipv6naddr = ipv4to6($netaddr);
300 Convert an ipv4 network address into an IPv6 network address.
302 input: 32 bit network address
304 returns: 128 bit network address
305 • $ipv6naddr = mask4to6($netaddr);
307 Convert an ipv4 network address/mask into an ipv6 network mask.
309 input: 32 bit network/mask address
311 returns: 128 bit network/mask address
312 NOTE: returns the high 96 bits as one's
314 • $ipv6naddr = ipanyto6($netaddr);
316 Similar to ipv4to6 except that this function takes either an IPv4
318 or IPv6 input and always returns a 128 bit IPv6 network address.
319 input: 32 or 128 bit network address
321 returns: 128 bit network address
322 • $ipv6naddr = maskanyto6($netaddr);
324 Similar to mask4to6 except that this function takes either an IPv4
326 or IPv6 netmask and always returns a 128 bit IPv6 netmask.
327 input: 32 or 128 bit network mask
329 returns: 128 bit network mask
330 • $netaddr = ipv6to4($pv6naddr);
332 Truncate the upper 96 bits of a 128 bit address and return the
334 lower 32 bits. Returns an IPv4 address as returned by inet_aton.
335 input: 128 bit network address
337 returns: 32 bit inet_aton network address
338 • $bitsXn = shiftleft($bits128,$n);
340 input: 128 bit string variable,
342 number of shifts [optional]
343 returns: bits X n shifts
344 NOTE: a single shift is performed
346 if $n is not specified
347 • addconst($ipv6naddr,$signed_32con);
349 Add a signed constant to a 128 bit string variable.
351 input: 128 bit IPv6 string,
353 signed 32 bit integer
354 returns: scalar carry
355 array (carry, result)
356 • add128($ipv6naddr1,$ipv6naddr2);
358 Add two 128 bit string variables.
360 input: 128 bit string var1,
362 128 bit string var2
363 returns: scalar carry
364 array (carry, result)
365 • sub128($ipv6naddr1,$ipv6naddr2);
367 Subtract two 128 bit string variables.
369 input: 128 bit string var1,
371 128 bit string var2
372 returns: scalar carry
373 array (carry, result)
374 Note: The carry from this operation is the result of adding the
376 one's complement of ARG2 +1 to the ARG1. It is logically NOT
377 borrow.
378 i.e. if ARG1 >= ARG2 then carry = 1
380 or if ARG1 < ARG2 then carry = 0
381 • ($spurious,$cidr) = notcontiguous($mask128);
383 This function counts the bit positions remaining in the mask when
385 the rightmost '0's are removed.
386 input: 128 bit netmask
388 returns true if there are spurious
389 zero bits remaining in the
390 mask, false if the mask is
391 contiguous one's,
392 128 bit cidr number
393 • $bcdtext = bin2bcd($bits128);
395 Convert a 128 bit binary string into binary coded decimal text
397 digits.
398 input: 128 bit string variable
400 returns: string of bcd text digits
401 • $bits128 = bcd2bin($bcdtxt);
403 Convert a bcd text string to 128 bit string variable
405 input: string of bcd text digits
407 returns: 128 bit string variable
408 • $modetext = mode;
410 Returns the operating mode of this module.
412 input: none
414 returns: "Pure Perl"
415 or "CC XS"
416 • ($name,$aliases,$addrtype,$length,@addrs)=naip_gethostbyname(NAME);
418 Replacement for Perl's gethostbyname if Socket6 is available
420 In ARRAY context, returns a list of five elements, the hostname or
422 NAME, a space separated list of C_NAMES, AF family, length of the
423 address structure, and an array of one or more netaddr's
424 In SCALAR context, returns the first netaddr.
426 This function ALWAYS returns an IPv6 address, even on IPv4 only
428 systems. IPv4 addresses are mapped into IPv6 space in the form:
429 ::FFFF:FFFF:d.d.d.d
431 This is NOT the expected result from Perl's gethostbyname2. It is
433 instead equivalent to:
434 On an IPv4 only system:
436 $ipv6naddr = ipv4to6 scalar ( gethostbyname( name ));
437 On a system with Socket6 and a working gethostbyname2:
439 $ipv6naddr = gethostbyname2( name, AF_INET6 );
440 and if that fails, the IPv4 conversion above.
441 For a gethostbyname2 emulator that behave like Socket6, see:
443 Net::DNS::Dig
444 • $trueif = havegethostbyname2();
446 This function returns TRUE if Socket6 has a functioning
448 gethostbyname2, otherwise it returns FALSE. See the comments above
449 about the behavior of naip_gethostbyname.
450 • NetAddr::IP::Util::lower();
452 Return IPv6 strings in lowercase.
454 • NetAddr::IP::Util::upper();
456 Return IPv6 strings in uppercase. This is the default.
458
460 # convert any textual IP address into a 128 bit vector
461 #
462 sub text2vec {
463 my($anyIP,$anyMask) = @_;
464 # not IPv4 bit mask
466 my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
467 my $vecip = inet_any2n($anyIP);
469 my $mask = inet_any2n($anyMask);
470 # extend mask bits for IPv4
472 my $bits = 128; # default
473 unless (hasbits($mask & $notiv4)) {
474 $mask |= $notiv4;
475 $bits = 32;
476 }
477 return ($vecip, $mask, $bits);
478 }
479 ... alternate implementation, a little faster
481 sub text2vec {
483 my($anyIP,$anyMask) = @_;
484 # not IPv4 bit mask
486 my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
487 my $vecip = inet_any2n($anyIP);
489 my $mask = inet_any2n($anyMask);
490 # extend mask bits for IPv4
492 my $bits = 128; # default
493 if (isIPv4($mask)) {
494 $mask |= $notiv4;
495 $bits = 32;
496 }
497 return ($vecip, $mask, $bits);
498 }
499 ... elsewhere
502 $nip = {
503 addr => $vecip,
504 mask => $mask,
505 bits => $bits,
506 };
507 # return network and broadcast addresses from IP and Mask
509 #
510 sub netbroad {
511 my($nip) = shift;
512 my $notmask = ~ $nip->{mask};
513 my $bcast = $nip->{addr} | $notmask;
514 my $network = $nip->{addr} & $nip->{mask};
515 return ($network, $broadcast);
516 }
517 # check if address is within a network
519 #
520 sub within {
521 my($nip,$net) = @_;
522 my $addr = $nip->{addr}
523 my($nw,$bc) = netbroad($net);
524 # arg1 >= arg2, sub128 returns true
525 return (sub128($addr,$nw) && sub128($bc,$addr))
526 ? 1 : 0;
527 }
528 # truely hard way to do $ip++
530 # add a constant, wrapping at netblock boundaries
531 # to subtract the constant, negate it before calling
532 # 'addwrap' since 'addconst' will extend the sign bits
533 #
534 sub addwrap {
535 my($nip,$const) = @_;
536 my $addr = $nip->{addr};
537 my $mask = $nip->{mask};
538 my $bits = $nip->{bits};
539 my $notmask = ~ $mask;
540 my $hibits = $addr & $mask;
541 $addr = addconst($addr,$const);
542 my $wraponly = $addr & $notmask;
543 my $newip = {
544 addr => $hibits | $wraponly,
545 mask => $mask,
546 bits => $bits,
547 };
548 # bless $newip as appropriate
549 return $newip;
550 }
551 # something more useful
553 # increment a /24 net to the NEXT net at the boundry
554 my $nextnet = 256; # for /24
556 LOOP:
557 while (...continuing) {
558 your code....
559 ...
560 my $lastip = $ip-copy();
561 $ip++;
562 if ($ip < $lastip) { # host part wrapped?
563 # discard carry
564 (undef, $ip->{addr} = addconst($ip->{addr}, $nextnet);
565 }
566 next LOOP;
567 }
568
570 inet_aton
571 inet_ntoa
572 ipv6_aton
573 ipv6_ntoa
574 ipv6_n2x
575 ipv6_n2d
576 inet_any2n
577 hasbits
578 isIPv4
579 isNewIPv4
580 isAnyIPv4
581 inet_n2dx
582 inet_n2ad
583 inet_pton
584 inet_ntop
585 inet_4map6
586 ipv4to6
587 mask4to6
588 ipanyto6
589 maskanyto6
590 ipv6to4
591 packzeros
592 shiftleft
593 addconst
594 add128
595 sub128
596 notcontiguous
597 bin2bcd
598 bcd2bin
599 mode
600 naip_gethostbyname
601 havegethostbyname2
602
604 Michael Robinton <michael@bizsystems.com>
605
607 Copyright 2003 - 2014, Michael Robinton <michael@bizsystems.com>
608 All rights reserved.
610 This program is free software; you can redistribute it and/or modify it
612 under the terms of either:
613 a) the GNU General Public License as published by the Free
615 Software Foundation; either version 2, or (at your option) any
616 later version, or
617 b) the "Artistic License" which comes with this distribution.
619 This program is distributed in the hope that it will be useful, but
621 WITHOUT ANY WARRANTY; without even the implied warranty of
622 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the
623 GNU General Public License or the Artistic License for more details.
624 You should have received a copy of the Artistic License with this
626 distribution, in the file named "Artistic". If not, I'll be glad to
627 provide one.
628 You should also have received a copy of the GNU General Public License
630 along with this program in the file named "Copying". If not, write to
631 the
632 Free Software Foundation, Inc.
634 51 Franklin Street, Fifth Floor
635 Boston, MA 02110-1301 USA.
636 or visit their web page on the internet at:
638 http://www.gnu.org/copyleft/gpl.html.
640
642 Michael Robinton <michael@bizsystems.com>
643
645 NetAddr::IP(3), NetAddr::IP::Lite(3), NetAddr::IP::InetBase(3)
646perl v5.32.1 2021-01-27 Util(3)