1Util(3) User Contributed Perl Documentation Util(3)
2
6 NetAddr::IP::Util -- IPv4/6 and 128 bit number utilities
7
9 use NetAddr::IP::Util qw(
10 inet_aton
11 inet_ntoa
12 ipv6_aton
13 ipv6_n2x
14 ipv6_n2d
15 inet_any2n
16 hasbits
17 isIPv4
18 inet_n2dx
19 inet_n2ad
20 ipv4to6
21 mask4to6
22 ipanyto6
23 maskanyto6
24 ipv6to4
25 shiftleft
26 addconst
27 add128
28 sub128
29 notcontiguous
30 bin2bcd
31 bcd2bin
32 mode
33 );
34 use NetAddr::IP::Util qw(:all :inet :ipv4 :ipv6 :math)
36 :inet => inet_aton, inet_ntoa, ipv6_aton,
38 ipv6_n2x, ipv6_n2d, inet_any2n,
39 inet_n2dx, inet_n2ad, ipv4to6,
40 mask4to6, ipanyto6, maskanyto6,
41 ipv6to4
42 :ipv4 => inet_aton, inet_ntoa
44 :ipv6 => ipv6_aton, ipv6_n2x, ipv6_n2d,
46 inet_any2n, inet_n2dx, inet_n2ad
47 ipv4to6, mask4to6, ipanyto6,
48 maskanyto6, ipv6to4
49 :math => hasbits, isIPv4, addconst,
51 add128, sub128, notcontiguous,
52 bin2bcd, bcd2bin, shiftleft
53 $dotquad = inet_ntoa($netaddr);
55 $netaddr = inet_aton($dotquad);
56 $ipv6naddr = ipv6_aton($ipv6_text);
57 $hex_text = ipv6_n2x($ipv6naddr);
58 $dec_text = ipv6_n2d($ipv6naddr);
59 $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
60 $rv = hasbits($bits128);
61 $rv = isIPv4($bits128);
62 $dotquad or $hex_text = inet_n2dx($ipv6naddr);
63 $dotquad or $dec_text = inet_n2ad($ipv6naddr);
64 $ipv6naddr = ipv4to6($netaddr);
65 $ipv6naddr = mask4to6($netaddr);
66 $ipv6naddr = ipanyto6($netaddr);
67 $ipv6naddr = maskanyto6($netaddr);
68 $netaddr = ipv6to4($pv6naddr);
69 $bitsX2 = shiftleft($bits128,$n);
70 $carry = addconst($ipv6naddr,$signed_32con);
71 ($carry,$ipv6naddr)=addconst($ipv6naddr,$signed_32con);
72 $carry = add128($ipv6naddr1,$ipv6naddr2);
73 ($carry,$ipv6naddr)=add128($ipv6naddr1,$ipv6naddr2);
74 $carry = sub128($ipv6naddr1,$ipv6naddr2);
75 ($carry,$ipv6naddr)=sub128($ipv6naddr1,$ipv6naddr2);
76 ($spurious,$cidr) = notcontiguous($mask128);
77 $bcdtext = bin2bcd($bits128);
78 $bits128 = bcd2bin($bcdtxt);
79 $modetext = mode;
80
82 Un-tar the distribution in an appropriate directory and type:
83 perl Makefile.PL
85 make
86 make test
87 make install
88 NetAddr::IP::Util installs by default with its primary functions com‐
90 piled using Perl's XS extensions to build a 'C' library. If you do not
91 have a 'C' complier available or would like the slower Pure Perl ver‐
92 sion for some other reason, then type:
93 perl Makefile.PL -noxs
95 make
96 make test
97 make install
98
100 NetAddr::IP::Util provides a suite of tools for manipulating and con‐
101 verting IPv4 and IPv6 addresses into 128 bit string context and back to
102 text. The strings can be manipulated with Perl's logical operators:
103 and &
105 or ⎪
106 xor ^
107 in the same manner as 'vec' strings.
109 The IPv6 functions support all rfc1884 formats.
111 i.e. x:x:x:x:x:x:x:x:x
113 x:x:x:x:x:x:x:d.d.d.d
114 ::x:x:x
115 ::x:d.d.d.d
116 and so on...
117 * $dotquad = inet_ntoa($netaddr);
119 Convert a packed IPv4 network address to a dot-quad IP address.
120 input: packed network address
122 returns: IP address i.e. 10.4.12.123
123 * $netaddr = inet_aton($dotquad);
125 Convert a dot-quad IP address into an IPv4 packed network address.
126 input: IP address i.e. 192.5.16.32
128 returns: packed network address
129 * $ipv6addr = ipv6_aton($ipv6_text);
131 Takes an IPv6 address of the form described in rfc1884 and returns
132 a 128 bit binary RDATA string.
133 input: ipv6 text
135 returns: 128 bit RDATA string
136 * $hex_text = ipv6_n2x($ipv6addr);
138 Takes an IPv6 RDATA string and returns an 8 segment IPv6 hex
139 address
140 input: 128 bit RDATA string
142 returns: x:x:x:x:x:x:x:x
143 * $dec_text = ipv6_n2d($ipv6addr);
145 Takes an IPv6 RDATA string and returns a mixed hex - decimal IPv6
146 address with the 6 uppermost chunks in hex and the lower 32 bits in
147 dot-quad representation.
148 input: 128 bit RDATA string
150 returns: x:x:x:x:x:x:d.d.d.d
151 * $ipv6naddr = inet_any2n($dotquad or $ipv6_text);
153 This function converts a text IPv4 or IPv6 address in text format
154 in any standard notation into a 128 bit IPv6 string address. It
155 prefixes any dot-quad address (if found) with '::' and passes it to
156 ipv6_aton.
157 input: dot-quad or rfc1844 address
159 returns: 128 bit IPv6 string
160 * $rv = hasbits($bits128);
162 This function returns true if there are one's present in the 128
163 bit string and false if all the bits are zero.
164 i.e. if (hasbits($bits128)) {
166 &do_something;
167 }
168 or if (hasbits($bits128 & $mask128) {
170 &do_something;
171 }
172 This allows the implementation of logical functions of the form of:
174 if ($bits128 & $mask128) {
176 ...
177 input: 128 bit IPv6 string
179 returns: true if any bits are present
180 * $rv = isIPv4($bits128);
182 This function returns true if there are no on bits present in the
183 IPv6 portion of the 128 bit string and false otherwise.
184 * $dotquad or $hex_text = inet_n2dx($ipv6naddr);
186 This function does the right thing and returns the text for either
187 a dot-quad IPv4 or a hex notation IPv6 address.
188 input: 128 bit IPv6 string
190 returns: ddd.ddd.ddd.ddd
191 or x:x:x:x:x:x:x:x
192 * $dotquad or $dec_text = inet_n2ad($ipv6naddr);
194 This function does the right thing and returns the text for either
195 a dot-quad IPv4 or a hex::decimal notation IPv6 address.
196 input: 128 bit IPv6 string
198 returns: ddd.ddd.ddd.ddd
199 or x:x:x:x:x:x:ddd.ddd.ddd.dd
200 * $ipv6naddr = ipv4to6($netaddr);
202 Convert an ipv4 network address into an ipv6 network address.
203 input: 32 bit network address
205 returns: 128 bit network address
206 * $ipv6naddr = mask4to6($netaddr);
208 Convert an ipv4 network address/mask into an ipv6 network mask.
209 input: 32 bit network/mask address
211 returns: 128 bit network/mask address
212 NOTE: returns the high 96 bits as one's
214 * $ipv6naddr = ipanyto6($netaddr);
216 Similar to ipv4to6 except that this function takes either an IPv4
217 or IPv6 input and always returns a 128 bit IPv6 network address.
218 input: 32 or 128 bit network address
220 returns: 128 bit network address
221 * $ipv6naddr = maskanyto6($netaddr);
223 Similar to mask4to6 except that this function takes either an IPv4
224 or IPv6 netmask and always returns a 128 bit IPv6 netmask.
225 input: 32 or 128 bit network mask
227 returns: 128 bit network mask
228 * $netaddr = ipv6to4($pv6naddr);
230 Truncate the upper 96 bits of a 128 bit address and return the
231 lower 32 bits. Returns an IPv4 address as returned by inet_aton.
232 input: 128 bit network address
234 returns: 32 bit inet_aton network address
235 * $bitsXn = shiftleft($bits128,$n);
237 input: 128 bit string variable,
238 number of shifts [optional]
239 returns: bits X n shifts
240 NOTE: a single shift is performed
242 if $n is not specified
243 * addconst($ipv6naddr,$signed_32con);
245 Add a signed constant to a 128 bit string variable.
246 input: 128 bit IPv6 string,
248 signed 32 bit integer
249 returns: scalar carry
250 array (carry, result)
251 * add128($ipv6naddr1,$ipv6naddr2);
253 Add two 128 bit string variables.
254 input: 128 bit string var1,
256 128 bit string var2
257 returns: scalar carry
258 array (carry, result)
259 * sub128($ipv6naddr1,$ipv6naddr2);
261 Subtract two 128 bit string variables.
262 input: 128 bit string var1,
264 128 bit string var2
265 returns: scalar carry
266 array (carry, result)
267 Note: The carry from this operation is the result of adding the
269 one's complement of ARG2 +1 to the ARG1. It is logically NOT bor‐
270 row.
271 i.e. if ARG1 >= ARG2 then carry = 1
273 or if ARG1 < ARG2 then carry = 0
274 * ($spurious,$cidr) = notcontiguous($mask128);
276 This function counts the bit positions remaining in the mask when
277 the rightmost '0's are removed.
278 input: 128 bit netmask
280 returns true if there are spurious
281 zero bits remaining in the
282 mask, false if the mask is
283 contiguous one's,
284 128 bit cidr number
285 * $bcdtext = bin2bcd($bits128);
287 Convert a 128 bit binary string into binary coded decimal text dig‐
288 its.
289 input: 128 bit string variable
291 returns: string of bcd text digits
292 * $bits128 = bcd2bin($bcdtxt);
294 Convert a bcd text string to 128 bit string variable
295 input: string of bcd text digits
297 returns: 128 bit string variable
298 * $modetext = mode;
300 Returns the operating mode of this module.
301 input: none
303 returns: "Pure Perl"
304 or "CC XS"
305
307 # convert any textual IP address into a 128 bit vector
308 #
309 sub text2vec {
310 my($anyIP,$anyMask) = @_;
311 # not IPv4 bit mask
313 my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
314 my $vecip = inet_any2n($anyIP);
316 my $mask = inet_any2n($anyMask);
317 # extend mask bits for IPv4
319 my $bits = 128; # default
320 unless (hasbits($mask & $notiv4)) {
321 $mask ⎪= $notiv4;
322 $bits = 32;
323 }
324 return ($vecip, $mask, $bits);
325 }
326 ... alternate implementation, a little faster
328 sub text2vec {
330 my($anyIP,$anyMask) = @_;
331 # not IPv4 bit mask
333 my $notiv4 = ipv6_aton('FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::');
334 my $vecip = inet_any2n($anyIP);
336 my $mask = inet_any2n($anyMask);
337 # extend mask bits for IPv4
339 my $bits = 128; # default
340 if (isIPv4($mask)) {
341 $mask ⎪= $notiv4;
342 $bits = 32;
343 }
344 return ($vecip, $mask, $bits);
345 }
346 ... elsewhere
348 $nip = {
349 addr => $vecip,
350 mask => $mask,
351 bits => $bits,
352 };
353 # return network and broadcast addresses from IP and Mask
355 #
356 sub netbroad {
357 my($nip) = shift;
358 my $notmask = ~ $nip->{mask};
359 my $bcast = $nip->{addr} ⎪ $notmask;
360 my $network = $nip->{addr} & $nip->{mask};
361 return ($network, $broadcast);
362 }
363 # check if address is within a network
365 #
366 sub within {
367 my($nip,$net) = @_;
368 my $addr = $nip->{addr}
369 my($nw,$bc) = netbroad($net);
370 # arg1 >= arg2, sub128 returns true
371 return (sub128($addr,$nw) && sub128($bc,$addr))
372 ? 1 : 0;
373 }
374 # add a constant, wrapping at netblock boundries
376 # to subtract the constant, negate it before calling
377 # 'addwrap' since 'addconst' will extend the sign bits
378 #
379 sub addwrap {
380 my($nip,$const) = @_;
381 my $mask = $nip->{addr};
382 my $bits = $nip->{bits};
383 my $notmask = ~ $mask;
384 my $hibits = $addr & $mask;
385 my $addr = addconst($addr,$const);
386 my $wraponly = $addr & $notmask;
387 my $newip = {
388 addr => $hibits ⎪ $wraponly,
389 mask => $mask,
390 bits => $bits,
391 };
392 # bless $newip as appropriate
393 return $newip;
394 }
395
397 inet_aton
398 inet_ntoa
399 ipv6_aton
400 ipv6_n2x
401 ipv6_n2d
402 inet_any2n
403 hasbits
404 isIPv4
405 inet_n2dx
406 inet_n2ad
407 ipv4to6
408 mask4to6
409 ipanyto6
410 maskanyto6
411 ipv6to4
412 shiftleft
413 addconst
414 add128
415 sub128
416 notcontiguous
417 bin2bcd
418 bcd2bin
419 mode
420
422 Michael Robinton <michael@bizsystems.com>
423
425 The following functions are used in whole or in part as include files
426 to Util.xs. The copyright is include in the file.
427 file: function:
429 miniSocket.inc inet_aton, inet_ntoa
431 inet_aton, inet_ntoa are from the perl-5.8.0 release by Larry Wall,
433 copyright 1989-2002. inet_aton, inet_ntoa code is current through
434 perl-5.9.3 release. Thank you Larry for making PERL possible for all
435 of us.
436
438 Copyright 2003 - 2006, Michael Robinton <michael@bizsystems.com>
439 LICENSE AND WARRANTY
441 This software is (c) Michael Robinton. It can be used under the terms
443 of the perl artistic license provided that proper credit for the work
444 of the author is preserved in the form of this copyright notice
445 and license for this module.
446 No warranty of any kind is expressed or implied, by using it you
448 accept any and all the liability.
449
451 Michael Robinton <michael@bizsystems.com>
452perl v5.8.8 2006-08-14 Util(3)