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 0.96 of Net::IPv6Addr corresponding to git
10       commit 64f42c10634b707ccd482644a0fae855d488d5d6
11       <https://github.com/benkasminbullock/net-
12       ipv6addr/commit/64f42c10634b707ccd482644a0fae855d488d5d6> released on
13       Sat Oct 6 15:05:27 2018 +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-0.96/examples/synopsis.pl> in the distribution.)
29

DESCRIPTION

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

EXPORTS

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

DEPENDENCIES

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

HISTORY

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

AUTHOR

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

LICENSE

698       This distribution is copyright (c) 2001-2002 Tony Monroe.  All rights
699       reserved.  This software is distributed under the same license terms as
700       Perl itself.  This software comes with NO WARRANTIES WHATSOEVER,
701       express, implied, or otherwise.
702
703
704
705perl v5.28.0                      2018-10-06                  Net::IPv6Addr(3)