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.02 of Net::IPv6Addr corresponding to git
10       commit f9065cb7b044da442df16443d65593a5a3fc6baa
11       <https://github.com/benkasminbullock/net-
12       ipv6addr/commit/f9065cb7b044da442df16443d65593a5a3fc6baa> released on
13       Wed Mar 31 11:11:47 2021 +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.02/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.02/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.02/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.02/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.02/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.02/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.02/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.02/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.02/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.02/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.02/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.02/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.02/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.02, "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       Math::BigInt
545           This is used by "to_bigint" and "from_bigint".
546
547   Reverse dependencies
548       Search grep.cpan.me for uses of this module
549       <http://grep.cpan.me/?q=Net%3A%3AIPv6Addr%5Cb>
550

HISTORY

649       This module was originally written by Tony Monroe in 2001 to simplify
650       the task of maintaining DNS records after he set himself up with
651       Freenet6.
652
653       In 2017 the module was adopted by Ben Bullock with the help of Neil
654       Bowers as part of "CPAN day". Significant changes to the module since
655       then include the following:
656
657       1.02
658           Net::IPv4Addr dependence removed. This module suffered from the
659           "octal bug". This module had only been used to validate ipv4
660           addresses and was easy to remove.
661
662           Math::Base85 dependence removed. This module is only needed to
663           support the April Fool's joke method of IPv6 addresses, so if the
664           user doesn't already have Math::Base85, the module now disables
665           support for the April Fool addresses.
666
667       1.0 Checking of base 85 addresses and prefixes was made stricter in
668           response to user complaints.
669
670       0.95
671           The "from_bigint" method was added and the documentation updated to
672           reflect the current internet standards.
673
674           The restriction on mixed address inputs removed in "0.92" was also
675           removed in the output routines "to_string_ipv4" and
676           "to_string_ipv4_compressed".
677
678       0.92
679           The valid format consisting of a compressed-but-non-zero six-
680           element IPv6 followed by an IPv4, such as
681           "fe80::204:61ff:254.157.241.86", is accepted by the module.
682
683       0.9 "in_network" and "in_network_of_size" were fixed to allow more
684           kinds of previxes.
685
686       0.8 Exporting of some functions was added. Prior to this, everything
687           had to be done fully-qualified, as in
688           "Net::IPv6Addr::to_string_compressed".
689

AUTHOR

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

LICENSE

705       This distribution is copyright (c) 2001-2002 Tony Monroe.  All rights
706       reserved.  This software is distributed under the same license terms as
707       Perl itself.  This software comes with NO WARRANTIES WHATSOEVER,
708       express, implied, or otherwise.
709
710
711
712perl v5.36.0                      2023-01-20                  Net::IPv6Addr(3)