1Util(3) User Contributed Perl Documentation Util(3)
2
3
4
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
45 use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math)
46
47 :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
54 :ipv4 => inet_aton, inet_ntoa
55
56 :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
63 :math => hasbits, isIPv4, isNewIPv4, isAnyIPv4,
64 addconst, add128, sub128, notcontiguous,
65 bin2bcd, bcd2bin, shiftleft
66
67 $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
103 NetAddr::IP::Util::lower();
104 NetAddr::IP::Util::upper();
105
107 Un-tar the distribution in an appropriate directory and type:
108
109 perl Makefile.PL
110 make
111 make test
112 make install
113
114 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
119 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
129 and &
130 or |
131 xor ^
132 ~ compliment
133
134 in the same manner as 'vec' strings.
135
136 The IPv6 functions support all rfc1884 formats.
137
138 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
144 · $dotquad = inet_ntoa($netaddr);
145
146 Convert a packed IPv4 network address to a dot-quad IP address.
147
148 input: packed network address
149 returns: IP address i.e. 10.4.12.123
150
151 · $netaddr = inet_aton($dotquad);
152
153 Convert a dot-quad IP address into an IPv4 packed network address.
154
155 input: IP address i.e. 192.5.16.32
156 returns: packed network address
157
158 · $ipv6addr = ipv6_aton($ipv6_text);
159
160 Takes an IPv6 address of the form described in rfc1884 and returns
161 a 128 bit binary RDATA string.
162
163 input: ipv6 text
164 returns: 128 bit RDATA string
165
166 · $ipv6_text = ipv6_ntoa($ipv6naddr);
167
168 Convert a 128 bit binary IPv6 address to compressed rfc 1884 text
169 representation.
170
171 input: 128 bit RDATA string
172 returns: ipv6 text
173
174 · $hex_text = ipv6_n2x($ipv6addr);
175
176 Takes an IPv6 RDATA string and returns an 8 segment IPv6 hex
177 address
178
179 input: 128 bit RDATA string
180 returns: x:x:x:x:x:x:x:x
181
182 · $dec_text = ipv6_n2d($ipv6addr);
183
184 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
188 input: 128 bit RDATA string
189 returns: x:x:x:x:x:x:d.d.d.d
190
191 · $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
192
193 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
198 input: dot-quad or rfc1844 address
199 returns: 128 bit IPv6 string
200
201 · $rv = hasbits($bits128);
202
203 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
206 i.e. if (hasbits($bits128)) {
207 &do_something;
208 }
209
210 or if (hasbits($bits128 & $mask128) {
211 &do_something;
212 }
213
214 This allows the implementation of logical functions of the form of:
215
216 if ($bits128 & $mask128) {
217 ...
218
219 input: 128 bit IPv6 string
220 returns: true if any bits are present
221
222 · $ipv6naddr = inet_4map6($netaddr or $ipv6naddr
223
224 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
228 input: ipV4 netaddr
229 or ipV6 netaddr
230 returns: ipV6 netaddr
231
232 returns: undef on error
233
234 An ipV6 network address must be in one of the two compatible ipV4
235 mapped address spaces. i.e.
236
237 ::ffff::d.d.d.d or ::d.d.d.d
238
239 · $rv = isIPv4($bits128);
240
241 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
244 i.e. the address must be of the form - ::d.d.d.d
245
246 Note: this is an old and deprecated ipV4 compatible ipV6 address
247
248 · $rv = isNewIPv4($bits128);
249
250 This function return true if the IPv6 128 bit string is of the form
251
252 ::ffff::d.d.d.d
253
254 · $rv = isAnyIPv4($bits128);
255
256 This function return true if the IPv6 bit string is of the form
257
258 ::d.d.d.d or ::ffff::d.d.d.d
259
260 · $dotquad or $hex_text = inet_n2dx($ipv6naddr);
261
262 This function does the right thing and returns the text for either
263 a dot-quad IPv4 or a hex notation IPv6 address.
264
265 input: 128 bit IPv6 string
266 returns: ddd.ddd.ddd.ddd
267 or x:x:x:x:x:x:x:x
268
269 · $dotquad or $dec_text = inet_n2ad($ipv6naddr);
270
271 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
274 input: 128 bit IPv6 string
275 returns: ddd.ddd.ddd.ddd
276 or x:x:x:x:x:x:ddd.ddd.ddd.dd
277
278 · $netaddr = inet_pton($AF_family,$hex_text);
279
280 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
284 · $hex_text = inet_ntop($AF_family,$netaddr);
285
286 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
290 NOTE: inet_ntop ALWAYS returns lowercase characters.
291
292 · $hex_text = packzeros($hex_text);
293
294 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
299 · $ipv6naddr = ipv4to6($netaddr);
300
301 Convert an ipv4 network address into an IPv6 network address.
302
303 input: 32 bit network address
304 returns: 128 bit network address
305
306 · $ipv6naddr = mask4to6($netaddr);
307
308 Convert an ipv4 network address/mask into an ipv6 network mask.
309
310 input: 32 bit network/mask address
311 returns: 128 bit network/mask address
312
313 NOTE: returns the high 96 bits as one's
314
315 · $ipv6naddr = ipanyto6($netaddr);
316
317 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
320 input: 32 or 128 bit network address
321 returns: 128 bit network address
322
323 · $ipv6naddr = maskanyto6($netaddr);
324
325 Similar to mask4to6 except that this function takes either an IPv4
326 or IPv6 netmask and always returns a 128 bit IPv6 netmask.
327
328 input: 32 or 128 bit network mask
329 returns: 128 bit network mask
330
331 · $netaddr = ipv6to4($pv6naddr);
332
333 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
336 input: 128 bit network address
337 returns: 32 bit inet_aton network address
338
339 · $bitsXn = shiftleft($bits128,$n);
340
341 input: 128 bit string variable,
342 number of shifts [optional]
343 returns: bits X n shifts
344
345 NOTE: a single shift is performed
346 if $n is not specified
347
348 · addconst($ipv6naddr,$signed_32con);
349
350 Add a signed constant to a 128 bit string variable.
351
352 input: 128 bit IPv6 string,
353 signed 32 bit integer
354 returns: scalar carry
355 array (carry, result)
356
357 · add128($ipv6naddr1,$ipv6naddr2);
358
359 Add two 128 bit string variables.
360
361 input: 128 bit string var1,
362 128 bit string var2
363 returns: scalar carry
364 array (carry, result)
365
366 · sub128($ipv6naddr1,$ipv6naddr2);
367
368 Subtract two 128 bit string variables.
369
370 input: 128 bit string var1,
371 128 bit string var2
372 returns: scalar carry
373 array (carry, result)
374
375 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
379 i.e. if ARG1 >= ARG2 then carry = 1
380 or if ARG1 < ARG2 then carry = 0
381
382 · ($spurious,$cidr) = notcontiguous($mask128);
383
384 This function counts the bit positions remaining in the mask when
385 the rightmost '0's are removed.
386
387 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
394 · $bcdtext = bin2bcd($bits128);
395
396 Convert a 128 bit binary string into binary coded decimal text
397 digits.
398
399 input: 128 bit string variable
400 returns: string of bcd text digits
401
402 · $bits128 = bcd2bin($bcdtxt);
403
404 Convert a bcd text string to 128 bit string variable
405
406 input: string of bcd text digits
407 returns: 128 bit string variable
408
409 · $modetext = mode;
410
411 Returns the operating mode of this module.
412
413 input: none
414 returns: "Pure Perl"
415 or "CC XS"
416
417 · ($name,$aliases,$addrtype,$length,@addrs)=naip_gethostbyname(NAME);
418
419 Replacement for Perl's gethostbyname if Socket6 is available
420
421 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
425 In SCALAR context, returns the first netaddr.
426
427 This function ALWAYS returns an IPv6 address, even on IPv4 only
428 systems. IPv4 addresses are mapped into IPv6 space in the form:
429
430 ::FFFF:FFFF:d.d.d.d
431
432 This is NOT the expected result from Perl's gethostbyname2. It is
433 instead equivalent to:
434
435 On an IPv4 only system:
436 $ipv6naddr = ipv4to6 scalar ( gethostbyname( name ));
437
438 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
442 For a gethostbyname2 emulator that behave like Socket6, see:
443 Net::DNS::Dig
444
445 · $trueif = havegethostbyname2();
446
447 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
451 · NetAddr::IP::Util::lower();
452
453 Return IPv6 strings in lowercase.
454
455 · NetAddr::IP::Util::upper();
456
457 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
465 # not IPv4 bit mask
466 my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
467
468 my $vecip = inet_any2n($anyIP);
469 my $mask = inet_any2n($anyMask);
470
471 # 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
480 ... alternate implementation, a little faster
481
482 sub text2vec {
483 my($anyIP,$anyMask) = @_;
484
485 # not IPv4 bit mask
486 my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
487
488 my $vecip = inet_any2n($anyIP);
489 my $mask = inet_any2n($anyMask);
490
491 # 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
500
501 ... elsewhere
502 $nip = {
503 addr => $vecip,
504 mask => $mask,
505 bits => $bits,
506 };
507
508 # 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
518 # 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
529 # 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
552 # something more useful
553 # increment a /24 net to the NEXT net at the boundry
554
555 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
609 All rights reserved.
610
611 This program is free software; you can redistribute it and/or modify it
612 under the terms of either:
613
614 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
618 b) the "Artistic License" which comes with this distribution.
619
620 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
625 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
629 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
633 Free Software Foundation, Inc.
634 51 Franklin Street, Fifth Floor
635 Boston, MA 02110-1301 USA.
636
637 or visit their web page on the internet at:
638
639 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)
646
647
648
649perl v5.28.0 2015-08-17 Util(3)