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_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

INSTALLATION

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

DESCRIPTION

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
451NetAddr::IP::Util::lower();
452
453           Return IPv6 strings in lowercase.
454
455NetAddr::IP::Util::upper();
456
457           Return IPv6 strings in uppercase.  This is the default.
458

EXAMPLES

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

EXPORT_OK

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

AUTHOR

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

AUTHOR

642       Michael Robinton <michael@bizsystems.com>
643

SEE ALSO

645       NetAddr::IP(3), NetAddr::IP::Lite(3), NetAddr::IP::InetBase(3)
646
647
648
649perl v5.32.1                      2021-01-27                           Util(3)
Impressum