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