Net::IPv6Addr(3pm)

1Net::IPv6Addr(3)      User Contributed Perl Documentation     Net::IPv6Addr(3)
2
3
4

NAME

6       Net::IPv6Addr - Check and manipulate IPv6 addresses
7

VERSION

9       This documents version 1.01 of Net::IPv6Addr corresponding to git
10       commit 9002d5c714a91a7dc53c157af7f9a86e06c8616d
11       <https://github.com/benkasminbullock/net-
12       ipv6addr/commit/9002d5c714a91a7dc53c157af7f9a86e06c8616d> released on
13       Sat Jun 20 13:23:08 2020 +0900.
14

SYNOPSIS

16           use Net::IPv6Addr;
17           my $addr = "dead:beef:cafe:babe::f0ad";
18           Net::IPv6Addr::ipv6_parse($addr);
19           my $x = Net::IPv6Addr->new($addr);
20           print $x->to_string_preferred(), "\n";
21
22       produces output
23
24           dead:beef:cafe:babe:0:0:0:f0ad
25
26       (This example is included as synopsis.pl
27       <https://fastapi.metacpan.org/source/BKB/Net-
28       IPv6Addr-1.01/examples/synopsis.pl> in the distribution.)
29

DESCRIPTION

31       "Net::IPv6Addr" checks whether strings contain valid IPv6 addresses,
32       and converts IPv6 addresses into various formats.
33
34       All of "new", "is_ipv6", and "ipv6_parse" can process the following
35       formats:
36
37       Preferred form: x:x:x:x:x:x:x:x
38           "2001:db8:0:0:0:ff00:42:8329"
39
40           This is the form described as the "preferred form" in section 2.2
41           of "RFC1884" et al. Output with "to_string_preferred".
42
43       Compressed form with double colon: x::x etc.
44           "2001:db8::ff00:42:8329"
45
46           This is the "canonical text representation format" of "RFC5952".
47           Output with "to_string_compressed".
48
49       Mixed IPv4/IPv6 format: x:x:x:x:x:x:d.d.d.d
50           "2001:db8:0:0:0:ff00:0.66.131.41"
51
52           Output with "to_string_ipv4".
53
54       Mixed IPv4/IPv6 with compression: x::x:d.d.d.d, etc.
55           "2001:db8::ff00:0.66.131.41"
56
57           Output with "to_string_ipv4_compressed".
58
59       Big integers
60           An IPv6 can be changed to a Math::BigInt object or a digit string
61           using "to_bigint". Big integers can also be input with
62           "from_bigint".
63
64       Base-85-encoded: [0-9A-Za-z!#$%&()*+;<=>?@^_`{|}~-]{20}
65           "9R}vSQ9RqiCvG6zn?Zyh"
66
67           This encoding was given in "RFC1924" as an April Fool's joke.
68           Output with "to_string_base85".
69
70       In addition, the following formats can be output:
71
72       Arrays
73           An IPv6 can be processed into its component pieces with "to_array"
74           or "to_intarray".
75
76       Reverse-address pointer
77           An IPv6 can be processed into its reverse-address pointer, as
78           defined by "RFC1886", using "to_string_ip6_int".
79

METHODS AND FUNCTIONS

81       The methods and functions are listed in alphabetical order. All except
82       "new" serve as both object methods and standalone functions.
83
84   from_bigint
85           use Net::IPv6Addr 'from_bigint';
86           print from_bigint ('12345678901234567890')->to_string_compressed ();
87
88       produces output
89
90           ::ab54:a98c:eb1f:ad2
91
92       (This example is included as from-bigint.pl
93       <https://fastapi.metacpan.org/source/BKB/Net-
94       IPv6Addr-1.01/examples/from-bigint.pl> in the distribution.)
95
96       Given a string or a Math::BigInt object containing a number, this
97       converts it into a Net::IPv6Addr object.
98
99       Parameters
100
101       A string or a Math::BigInt object. If the input is a scalar, it's
102       converted into a Math::BigInt object.
103
104       Returns
105
106       A Net::IPv6Addr object
107
108       Notes
109
110       Invalid input will generate an exception.
111
112       This function was added in "0.95".
113
114   in_network
115           use Net::IPv6Addr;
116           my $obj = Net::IPv6Addr->new ('dead:beef:cafe:babe:dead:beef:cafe:babe');
117           if ($obj->in_network ('dead:beef:ca0::/21')) {
118               print $obj->to_string_compressed, " is in network.\n";
119           }
120
121       produces output
122
123           dead:beef:cafe:babe:dead:beef:cafe:babe is in network.
124
125       (This example is included as inet.pl
126       <https://fastapi.metacpan.org/source/BKB/Net-
127       IPv6Addr-1.01/examples/inet.pl> in the distribution.)
128
129       Parameters
130
131       If used as an object method, a network and its size in bits
132
133           my $ok = $x->in_network ("aa:bb:cc:dd::", 64);
134
135       If used as a subroutine, an IPv6 address string in any format, followed
136       by a network address string and its size in bits.
137
138           my $addr = 'fd00::54:20c:29fe:fe14:ab4b';
139           my $ok = Net::IPv6Addr::in_network ($addr, "aa:bb:cc:dd::", 64);
140
141       The network size may also be given with the / notation after the
142       network address string:
143
144           my $ok = $x->in_network("aa:bb:cc:dd::/64");
145
146       Returns
147
148       A true value if the address $x is a member of the network given as the
149       argument, or false otherwise.
150
151       Notes
152
153       Invalid input will generate an exception.
154
155       Prior to version "0.9", this did not work correctly unless the net size
156       was a multiple of sixteen.
157
158   in_network_of_size
159           use Net::IPv6Addr 'in_network_of_size';
160           my $obj = in_network_of_size ('dead:beef:cafe:babe:dead:beef:cafe:babe', 42);
161           print $obj->to_string_compressed ();
162
163       produces output
164
165           dead:beef:cac0::
166
167       (This example is included as inos.pl
168       <https://fastapi.metacpan.org/source/BKB/Net-
169       IPv6Addr-1.01/examples/inos.pl> in the distribution.)
170
171       Given an input IPv6 address $x, this returns the $n most-significant
172       bits of $x as a new Net::IPv6Addr object.
173
174       Parameters
175
176       If used as an object method, network size in bits:
177
178           my $obj = $x->in_network_of_size (64);
179
180       If used as a subroutine, an IPv6 address string in any format and a
181       network size in bits:
182
183           my $obj = in_network_of_size ($addr, 64);
184
185       Network size may also be given with "/" notation:
186
187           my $obj = in_network_of_size ("$addr/64");
188
189       Returns
190
191       The $n most-significant bits of $x as a new Net::IPv6Addr object.
192
193       Notes
194
195       Invalid input will generate an exception.
196
197       Prior to version "0.9", this did not work correctly unless the net size
198       was a multiple of sixteen.
199
200   ipv6_chkip
201           my $niok = ipv6_chkip ('dead:beef:cafe:babe::f0ad');
202
203       Parameters
204
205       An IPv6 address string, without a prefix.
206
207       Returns
208
209       A true value (a code reference for the parser for this IP) if it's a
210       valid address; a false value ("undef") if not.
211
212   ipv6_parse
213           my ($ni, $pl) = ipv6_parse ('dead:beef:cafe:babe::f0ad');
214
215       Parameters
216
217       Either a string containing an IPv6 address string, which may also
218       include a "/" character and a numeric prefix length,
219
220           my ($x, $y) = ipv6_parse ("a::/24");
221
222       or an IPv6 address string, with an optional second argument consisting
223       of a numeric prefix length:
224
225           my ($x, $y) = ipv6_parse('a::', '24');
226
227       Returns
228
229       Called in array context, the return value is a list consisting of the
230       address string and the prefix, if it parses correctly. Called in scalar
231       context, the address and prefix are concatenated with "/".
232
233       Notes
234
235       Throws an exception on malformed input.
236
237   is_ipv6
238           my $niok = is_ipv6 ('dead:beef:cafe:babe::f0ad');
239
240       Parameters
241
242       Identical to "ipv6_parse".
243
244       Returns
245
246       This returns the return value of "ipv6_parse", called in scalar
247       context, if it does parse out correctly, otherwise it returns "undef".
248       Unlike "ipv6_parse", "is_ipv6" does not throw exceptions.
249
250   new
251           my $ni = Net::IPv6Addr->new ('dead:beef:cafe:babe::f0ad');
252
253       Create a new Net::IPv6Addr object from a string. Internally, the object
254       is a blessed array reference containing the eight parts of the address
255       as integers.
256
257       Parameters
258
259       A string to be interpreted as an IPv6 address.
260
261       Returns
262
263       A "Net::IPv6Addr" object if successful.
264
265       Notes
266
267       Throws an exception if the string isn't a valid address.
268
269   to_array
270           use Net::IPv6Addr 'to_array';
271           my @int = to_array ('dead::beef');
272           my $ipobj = Net::IPv6Addr->new ('dead::beef');
273           my @int2 = $ipobj->to_array ();
274           print "@int\n@int2\n";
275
276       produces output
277
278           dead 0000 0000 0000 0000 0000 0000 beef
279           dead 0000 0000 0000 0000 0000 0000 beef
280
281       (This example is included as array.pl
282       <https://fastapi.metacpan.org/source/BKB/Net-
283       IPv6Addr-1.01/examples/array.pl> in the distribution.)
284
285       Convert an IPv6 address into an array of eight hexadecimal numbers.
286
287       Parameters
288
289       If used as an object method, none; if used as a subroutine, an IPv6
290       address string in any format.
291
292       Returns
293
294       An array [0..7] of 16-bit hexadecimal numbers (strings).
295
296       Notes
297
298       Invalid input will generate an exception.
299
300       See also "to_intarray" and "to_bigint".
301
302   to_bigint
303           use Net::IPv6Addr 'to_bigint';
304           my $int = to_bigint ('dead::beef');
305           my $ipobj = Net::IPv6Addr->new ('dead::beef');
306           my $int2 = $ipobj->to_bigint ();
307           print "$int\n$int2\n";
308
309       produces output
310
311           295986882420777848964380943247191621359
312           295986882420777848964380943247191621359
313
314       (This example is included as bigint.pl
315       <https://fastapi.metacpan.org/source/BKB/Net-
316       IPv6Addr-1.01/examples/bigint.pl> in the distribution.)
317
318       Convert an IPv6 address into a Math::BigInt object containing the IP
319       address as a single number.
320
321       Parameters
322
323       If used as an object method, none; if used as a subroutine, an IPv6
324       address string in any format.
325
326       Returns
327
328       The BigInt representation of the given IPv6 address.
329
330       Notes
331
332       Invalid input will generate an exception.
333
334       See also "from_bigint", "to_intarray" and "to_array".
335
336   to_intarray
337           use Net::IPv6Addr 'to_array';
338           my @int = to_array ('dead::beef');
339           my $ipobj = Net::IPv6Addr->new ('dead::beef');
340           my @int2 = $ipobj->to_array ();
341           print "@int\n@int2\n";
342
343       produces output
344
345           dead 0000 0000 0000 0000 0000 0000 beef
346           dead 0000 0000 0000 0000 0000 0000 beef
347
348       (This example is included as array.pl
349       <https://fastapi.metacpan.org/source/BKB/Net-
350       IPv6Addr-1.01/examples/array.pl> in the distribution.)
351
352       Convert an IPv6 address into an array of eight integer numbers.
353
354       Parameters
355
356       If used as an object method, none; if used as a subroutine, an IPv6
357       address string in any format.
358
359       Returns
360
361       An array [0..7] of numbers.
362
363       Notes
364
365       Invalid input will generate an exception.
366
367       See also "to_array" and "to_bigint".
368
369   to_string_base85
370       Parameters
371
372       If used as an object method, none; if used as a subroutine, an IPv6
373       address string in any format.
374
375       Returns
376
377       The IPv6 address in the style detailed by "RFC1924".
378
379       Notes
380
381       Invalid input will generate an exception.
382
383       The base 85 encoding described in "RFC1924" was an April Fool's joke.
384
385   to_string_compressed
386           use Net::IPv6Addr 'to_string_compressed';
387           print to_string_compressed ('dead:beef:0000:0000:0000:0000:cafe:babe');
388
389       produces output
390
391           dead:beef::cafe:babe
392
393       (This example is included as compressed.pl
394       <https://fastapi.metacpan.org/source/BKB/Net-
395       IPv6Addr-1.01/examples/compressed.pl> in the distribution.)
396
397       This provides the "canonical text representation format" of "RFC5952".
398
399       Parameters
400
401       If used as an object method, none; if used as a subroutine, an IPv6
402       address string in any format.
403
404       Returns
405
406       The IPv6 address in the "compressed" ("RFC1884" et al.) or "canonical"
407       ("RFC5952") format. Hexadecimal numbers are reduced to lower case,
408       consecutive zero elements are reduced to double colons, and leading
409       zeros are removed from strings of hexadecimal digits. All treatment of
410       ambiguities is as per RFC5952. (See t/rfc5952.t
411       <https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.01/t/rfc5952.t>
412       for tests.)
413
414       Notes
415
416       Invalid input will generate an exception.
417
418   to_string_ip6_int
419           use Net::IPv6Addr 'to_string_ip6_int';
420           my $s = to_string_ip6_int ('dead::beef');
421           my $ipobj = Net::IPv6Addr->new ('dead::beef');
422           my $s2 = $ipobj->to_string_ip6_int ();
423           print "$s\n$s2\n";
424
425       produces output
426
427           f.e.e.b.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.a.e.d.IP6.INT.
428           f.e.e.b.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.d.a.e.d.IP6.INT.
429
430       (This example is included as string-ip6-int.pl
431       <https://fastapi.metacpan.org/source/BKB/Net-
432       IPv6Addr-1.01/examples/string-ip6-int.pl> in the distribution.)
433
434       Parameters
435
436       If used as an object method, none; if used as a subroutine, an IPv6
437       address string in any format.
438
439       Returns
440
441       The reverse-address pointer as defined by "RFC1886".
442
443       Notes
444
445       Invalid input will generate an exception.
446
447       The reverse process of converting these into Net::IPv6Addr objects is
448       not supported.
449
450   to_string_ipv4
451           use Net::IPv6Addr ':all';
452           print to_string_ipv4_compressed ('dead:beef:0:3:2:1:cafe:babe');
453
454       produces output
455
456           dead:beef::3:2:1:202.254.186.190
457
458       (This example is included as to-string-ipv4.pl
459       <https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.01/examples/to-
460       string-ipv4.pl> in the distribution.)
461
462       Parameters
463
464       If used as an object method, none; if used as a subroutine, an IPv6
465       address string in any format.
466
467       Returns
468
469       The IPv6 address in the IPv4 format detailed by "RFC1884" et al.
470
471       Notes
472
473       When used as a subroutine, invalid input will generate an exception.
474
475       From version "0.95", this allows any IPv6 address to be produced, not
476       just the restricted forms allowed previously.
477
478   to_string_ipv4_compressed
479           use Net::IPv6Addr ':all';
480           print to_string_ipv4_compressed ('dead:beef:0:3:2:1:cafe:babe');
481
482       produces output
483
484           dead:beef::3:2:1:202.254.186.190
485
486       (This example is included as to-string-ipv4-comp.pl
487       <https://fastapi.metacpan.org/source/BKB/Net-IPv6Addr-1.01/examples/to-
488       string-ipv4-comp.pl> in the distribution.)
489
490       Parameters
491
492       If used as an object method, none; if used as a subroutine, an IPv6
493       address string in any format.
494
495       Returns
496
497       The IPv6 address in the compressed IPv4 format detailed by "RFC1884" et
498       al.
499
500       Notes
501
502       When used as a subroutine, invalid input will generate an exception.
503
504       From version "0.95", this allows any IPv6 address to be produced, not
505       just the restricted forms allowed previously.
506
507   to_string_preferred
508           use Net::IPv6Addr 'to_string_preferred';
509           print to_string_preferred ('dead:beef:cafe:babe::f0ad');
510
511       produces output
512
513           dead:beef:cafe:babe:0:0:0:f0ad
514
515       (This example is included as preferred.pl
516       <https://fastapi.metacpan.org/source/BKB/Net-
517       IPv6Addr-1.01/examples/preferred.pl> in the distribution.)
518
519       Parameters
520
521       If used as an object method, none; if used as a subroutine, an IPv6
522       address string in any format.
523
524       Returns
525
526       The IPv6 address, formatted in the "preferred" way (as detailed by
527       "RFC1884" et al).
528
529       Notes
530
531       Invalid input will generate an exception.
532

EXPORTS

534       As of version 1.01, "from_bigint", "in_network", "in_network_of_size",
535       "ipv6_chkip", "ipv6_parse", "is_ipv6", "to_array", "to_bigint",
536       "to_intarray", "to_string_base85", "to_string_compressed",
537       "to_string_ip6_int", "to_string_ipv4", "to_string_ipv4_compressed",
538       "to_string_preferred" may be exported on demand. All the exported
539       functions may be exported using
540
541           use Net::IPv6Addr ':all';
542

DEPENDENCIES

544       Net::IPv4Addr
545           This is used to parse IPv4 addresses.
546
547       Math::Base85
548           This is used to parse "RFC1924" (April Fool's) addresses.
549
550       Math::BigInt
551           This is used by the "RFC1924" (April Fool's) address routines and
552           by "to_bigint" and "from_bigint".
553
554   Reverse dependencies
555       Search grep.cpan.me for uses of this module
556       <http://grep.cpan.me/?q=Net%3A%3AIPv6Addr%5Cb>
557

HISTORY

656       This module was originally written by Tony Monroe in 2001 to simplify
657       the task of maintaining DNS records after he set himself up with
658       Freenet6.
659
660       In 2017 the module was adopted by Ben Bullock with the help of Neil
661       Bowers as part of "CPAN day". Significant changes to the module since
662       then include the following:
663
664       1.0 Checking of base 85 addresses and prefixes was made stricter in
665           response to user complaints.
666
667       0.95
668           The "from_bigint" method was added and the documentation updated to
669           reflect the current internet standards.
670
671           The restriction on mixed address inputs removed in "0.92" was also
672           removed in the output routines "to_string_ipv4" and
673           "to_string_ipv4_compressed".
674
675       0.92
676           The valid format consisting of a compressed-but-non-zero six-
677           element IPv6 followed by an IPv4, such as
678           "fe80::204:61ff:254.157.241.86", is accepted by the module.
679
680       0.9 "in_network" and "in_network_of_size" were fixed to allow more
681           kinds of previxes.
682
683       0.8 Exporting of some functions was added. Prior to this, everything
684           had to be done fully-qualified, as in
685           "Net::IPv6Addr::to_string_compressed".
686

AUTHOR

688       Tony Monroe(*)
689
690       The module's interface resembles Net::IPv4Addr by Francis J. Lacoste
691       <francis dot lacoste at iNsu dot COM>.
692
693       Some fixes and subroutines from Jyrki Soini <jyrki dot soini at sonera
694       dot com>.
695
696       (*) The current module maintainer (BKB) does not have any contact
697       information for Tony Monroe. Those wishing to contact him can do so via
698       Neil Bowers (see his CPAN user page for contact details
699       <https://metacpan.org/author/NEILB>).
700

LICENSE

702       This distribution is copyright (c) 2001-2002 Tony Monroe.  All rights
703       reserved.  This software is distributed under the same license terms as
704       Perl itself.  This software comes with NO WARRANTIES WHATSOEVER,
705       express, implied, or otherwise.
706
707
708
709perl v5.32.0                      2020-07-28                  Net::IPv6Addr(3)