Debian Codegraph @

Lite/Util/README

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