{ "content": [ { "type": "text", "text": "# NetAddr::IP::Lite (perldoc)\n\n## NAME\n\nNetAddr::IP::Lite - Manages IPv4 and IPv6 addresses and subnets\n\n## SYNOPSIS\n\nuse NetAddr::IP::Lite qw(\nZeros\nOnes\nV4mask\nV4net\n:aton DEPRECATED !\n:oldnth\n:upper\n:lower\n:nofqdn\n);\nmy $ip = new NetAddr::IP::Lite '127.0.0.1';\nor if your prefer\nmy $ip = NetAddr::IP::Lite->new('127.0.0.1);\nor from a packed IPv4 address\nmy $ip = newfromaton NetAddr::IP::Lite (inetaton('127.0.0.1'));\nor from an octal filtered IPv4 address\nmy $ip = newno NetAddr::IP::Lite '127.012.0.0';\nprint \"The address is \", $ip->addr, \" with mask \", $ip->mask, \"\\n\" ;\nif ($ip->within(new NetAddr::IP::Lite \"127.0.0.0\", \"255.0.0.0\")) {\nprint \"Is a loopback address\\n\";\n}\n# This prints 127.0.0.1/32\nprint \"You can also say $ip...\\n\";\nThe following four functions return ipV6 representations of:\n:: = Zeros();\nFFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones();\nFFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask();\n::FFFF:FFFF = V4net();\nWill also return an ipV4 or ipV6 representation of a\nresolvable Fully Qualified Domanin Name (FQDN).\n\n## DESCRIPTION\n\nThis module provides an object-oriented abstraction on top of IP addresses or IP subnets, that\nallows for easy manipulations. Most of the operations of NetAddr::IP are supported. This module\nwill work with older versions of Perl and is compatible with Math::BigInt.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **INSTALLATION**\n- **DESCRIPTION** (2 subsections)\n- **EXPORTOK**\n- **AUTHORS**\n- **WARRANTY**\n- **COPYRIGHT**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "NetAddr::IP::Lite", "section": "", "mode": "perldoc", "summary": "NetAddr::IP::Lite - Manages IPv4 and IPv6 addresses and subnets", "synopsis": "use NetAddr::IP::Lite qw(\nZeros\nOnes\nV4mask\nV4net\n:aton DEPRECATED !\n:oldnth\n:upper\n:lower\n:nofqdn\n);\nmy $ip = new NetAddr::IP::Lite '127.0.0.1';\nor if your prefer\nmy $ip = NetAddr::IP::Lite->new('127.0.0.1);\nor from a packed IPv4 address\nmy $ip = newfromaton NetAddr::IP::Lite (inetaton('127.0.0.1'));\nor from an octal filtered IPv4 address\nmy $ip = newno NetAddr::IP::Lite '127.012.0.0';\nprint \"The address is \", $ip->addr, \" with mask \", $ip->mask, \"\\n\" ;\nif ($ip->within(new NetAddr::IP::Lite \"127.0.0.0\", \"255.0.0.0\")) {\nprint \"Is a loopback address\\n\";\n}\n# This prints 127.0.0.1/32\nprint \"You can also say $ip...\\n\";\nThe following four functions return ipV6 representations of:\n:: = Zeros();\nFFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones();\nFFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask();\n::FFFF:FFFF = V4net();\nWill also return an ipV4 or ipV6 representation of a\nresolvable Fully Qualified Domanin Name (FQDN).", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "IP", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/IP/3/json" }, { "name": "Util", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/Util/3/json" }, { "name": "InetBase", "section": "3", "url": "https://www.chedong.com/phpMan.php/man/InetBase/3/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 39, "subsections": [] }, { "name": "INSTALLATION", "lines": 16, "subsections": [] }, { "name": "DESCRIPTION", "lines": 28, "subsections": [ { "name": "Overloaded Operators", "lines": 85 }, { "name": "Methods", "lines": 269 } ] }, { "name": "EXPORTOK", "lines": 10, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "WARRANTY", "lines": 3, "subsections": [] }, { "name": "COPYRIGHT", "lines": 32, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "NetAddr::IP::Lite - Manages IPv4 and IPv6 addresses and subnets\n", "subsections": [] }, "SYNOPSIS": { "content": "use NetAddr::IP::Lite qw(\nZeros\nOnes\nV4mask\nV4net\n:aton DEPRECATED !\n:oldnth\n:upper\n:lower\n:nofqdn\n);\n\nmy $ip = new NetAddr::IP::Lite '127.0.0.1';\nor if your prefer\nmy $ip = NetAddr::IP::Lite->new('127.0.0.1);\nor from a packed IPv4 address\nmy $ip = newfromaton NetAddr::IP::Lite (inetaton('127.0.0.1'));\nor from an octal filtered IPv4 address\nmy $ip = newno NetAddr::IP::Lite '127.012.0.0';\n\nprint \"The address is \", $ip->addr, \" with mask \", $ip->mask, \"\\n\" ;\n\nif ($ip->within(new NetAddr::IP::Lite \"127.0.0.0\", \"255.0.0.0\")) {\nprint \"Is a loopback address\\n\";\n}\n\n# This prints 127.0.0.1/32\nprint \"You can also say $ip...\\n\";\n\nThe following four functions return ipV6 representations of:\n\n:: = Zeros();\nFFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones();\nFFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask();\n::FFFF:FFFF = V4net();\n\nWill also return an ipV4 or ipV6 representation of a\nresolvable Fully Qualified Domanin Name (FQDN).\n", "subsections": [] }, "INSTALLATION": { "content": "Un-tar the distribution in an appropriate directory and type:\n\nperl Makefile.PL\nmake\nmake test\nmake install\n\nNetAddr::IP::Lite depends on NetAddr::IP::Util which installs by default with its primary\nfunctions compiled using Perl's XS extensions to build a 'C' library. If you do not have a 'C'\ncompiler available or would like the slower Pure Perl version for some other reason, then type:\n\nperl Makefile.PL -noxs\nmake\nmake test\nmake install\n", "subsections": [] }, "DESCRIPTION": { "content": "This module provides an object-oriented abstraction on top of IP addresses or IP subnets, that\nallows for easy manipulations. Most of the operations of NetAddr::IP are supported. This module\nwill work with older versions of Perl and is compatible with Math::BigInt.\n\n* By default NetAddr::IP functions and methods return string IPv6 addresses in uppercase. To\nchange that to lowercase:\n\nNOTE: the AUGUST 2010 RFC5952 states:\n\n4.3. Lowercase\n\nThe characters \"a\", \"b\", \"c\", \"d\", \"e\", and \"f\" in an IPv6\naddress MUST be represented in lowercase.\n\nIt is recommended that all NEW applications using NetAddr::IP::Lite be invoked as shown on the\nnext line.\n\nuse NetAddr::IP::Lite qw(:lower);\n\n* To ensure the current IPv6 string case behavior even if the default changes:\n\nuse NetAddr::IP::Lite qw(:upper);\n\nThe internal representation of all IP objects is in 128 bit IPv6 notation. IPv4 and IPv6 objects\nmay be freely mixed.\n\nThe supported operations are described below:\n", "subsections": [ { "name": "Overloaded Operators", "content": "Assignment (\"=\")\nHas been optimized to copy one NetAddr::IP::Lite object to another very quickly.\n\n\"->copy()\"\nThe assignment (\"=\") operation is only put in to operation when the copied object is further\nmutated by another overloaded operation. See overload SPECIAL SYMBOLS FOR \"use overload\" for\ndetails.\n\n\"->copy()\" actually creates a new object when called.\n\nStringification\nAn object can be used just as a string. For instance, the following code\n\nmy $ip = new NetAddr::IP::Lite '192.168.1.123';\nprint \"$ip\\n\";\n\nWill print the string 192.168.1.123/32.\n\nmy $ip = new6 NetAddr::IP::Lite '192.168.1.123';\nprint \"$ip\\n\";\n\nWill print the string 0:0:0:0:0:0:C0A8:17B/128\n\nEquality\nYou can test for equality with either \"eq\", \"ne\", \"==\" or \"!=\". \"eq\", \"ne\" allows the\ncomparison with arbitrary strings as well as NetAddr::IP::Lite objects. The following\nexample:\n\nif (NetAddr::IP::Lite->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')\n{ print \"Yes\\n\"; }\n\nWill print out \"Yes\".\n\nComparison with \"==\" and \"!=\" requires both operands to be NetAddr::IP::Lite objects.\n\nComparison via >, <, >=, <=, <=> and \"cmp\"\nInternally, all network objects are represented in 128 bit format. The numeric\nrepresentation of the network is compared through the corresponding operation. Comparisons\nare tried first on the address portion of the object and if that is equal then the NUMERIC\ncidr portion of the masks are compared. This leads to the counterintuitive result that\n\n/24 > /16\n\nComparison should not be done on netaddr objects with different CIDR as this may produce\nindeterminate - unexpected results, rather the determination of which netblock is larger or\nsmaller should be done by comparing\n\n$ip1->masklen <=> $ip2->masklen\n\nAddition of a constant (\"+\")\nAdd a 32 bit signed constant to the address part of a NetAddr object. This operation changes\nthe address part to point so many hosts above the current objects start address. For\ninstance, this code:\n\nprint NetAddr::IP::Lite->new('127.0.0.1/8') + 5;\n\nwill output 127.0.0.6/8. The address will wrap around at the broadcast back to the network\naddress. This code:\n\nprint NetAddr::IP::Lite->new('10.0.0.1/24') + 255;\n\noutputs 10.0.0.0/24.\n\nReturns the the unchanged object when the constant is missing or out of range.\n\n2147483647 <= constant >= -2147483648\n\nSubtraction of a constant (\"-\")\nThe complement of the addition of a constant.\n\nDifference (\"-\")\nReturns the difference between the address parts of two NetAddr::IP::Lite objects address\nparts as a 32 bit signed number.\n\nReturns undef if the difference is out of range.\n\nAuto-increment\nAuto-incrementing a NetAddr::IP::Lite object causes the address part to be adjusted to the\nnext host address within the subnet. It will wrap at the broadcast address and start again\nfrom the network address.\n\nAuto-decrement\nAuto-decrementing a NetAddr::IP::Lite object performs exactly the opposite of\nauto-incrementing it, as you would expect.\n" }, { "name": "Methods", "content": "\"->new([$addr, [ $mask|IPv6 ]])\"\n\"->new6([$addr, [ $mask]])\"\n\"->new6FFFF([$addr, [ $mask]])\"\n\"->newno([$addr, [ $mask]])\"\n\"->newfromaton($netaddr)\"\nnewcis and newcis6 are DEPRECATED\n\"->newcis(\"$addr $mask)\"\n\"->newcis6(\"$addr $mask)\"\nThe first three methods create a new address with the supplied address in $addr and an\noptional netmask $mask, which can be omitted to get a /32 or /128 netmask for IPv4 / IPv6\naddresses respectively.\n\nnew6FFFF specifically returns an IPv4 address in IPv6 format according to RFC4291\n\nnew6 ::xxxx:xxxx\nnew6FFFF ::FFFF:xxxx:xxxx\n\nThe third method \"newno\" is exclusively for IPv4 addresses and filters improperly formatted\ndot quad strings for leading 0's that would normally be interpreted as octal format by\nNetAddr per the specifications for inetaton.\n\nnewfromaton takes a packed IPv4 address and assumes a /32 mask. This function replaces the\nDEPRECATED :aton functionality which is fundamentally broken.\n\nThe last two methods newcis and newcis6 differ from new and new6 only in that they except\nthe common Cisco address notation for address/mask pairs with a space as a separator instead\nof a slash (/)\n\nThese methods are DEPRECATED because the functionality is now included in the other \"new\"\nmethods\n\ni.e. ->newcis('1.2.3.0 24')\nor\n->newcis6('::1.2.3.0 120')\n\n\"->new6\" and \"->newcis6\" mark the address as being in ipV6 address space even if the format\nwould suggest otherwise.\n\ni.e. ->new6('1.2.3.4') will result in ::102:304\n\naddresses submitted to ->new in ipV6 notation will\nremain in that notation permanently. i.e.\n->new('::1.2.3.4') will result in ::102:304\nwhereas new('1.2.3.4') would print out as 1.2.3.4\n\nSee \"STRINGIFICATION\" below.\n\n$addr can be almost anything that can be resolved to an IP address in all the notations I\nhave seen over time. It can optionally contain the mask in CIDR notation. If the OPTIONAL\nperl module Socket6 is available in the local library it will autoload and ipV6 host6 names\nwill be resolved as well as ipV4 hostnames.\n\nprefix notation is understood, with the limitation that the range specified by the prefix\nmust match with a valid subnet.\n\nAddresses in the same format returned by \"inetaton\" or \"gethostbyname\" can also be\nunderstood, although no mask can be specified for them. The default is to not attempt to\nrecognize this format, as it seems to be seldom used.\n\n###### DEPRECATED, will be remove in version 5 ############ To accept addresses in that\nformat, invoke the module as in\n\nuse NetAddr::IP::Lite ':aton'\n\n###### USE newfromaton instead ##########################\n\nIf called with no arguments, 'default' is assumed.\n\nIf called with an empty string as the argument, returns 'undef'\n\n$addr can be any of the following and possibly more...\n\nn.n\nn.n/mm\nn.n mm\nn.n.n\nn.n.n/mm\nn.n.n mm\nn.n.n.n\nn.n.n.n/mm 32 bit cidr notation\nn.n.n.n mm\nn.n.n.n/m.m.m.m\nn.n.n.n m.m.m.m\nloopback, localhost, broadcast, any, default\nx.x.x.x/host\n0xABCDEF, 0b111111000101011110, (or a bcd number)\na netaddr as returned by 'inetaton'\n\nAny RFC1884 notation\n\n::n.n.n.n\n::n.n.n.n/mmm 128 bit cidr notation\n::n.n.n.n/::m.m.m.m\n::x:x\n::x:x/mmm\nx:x:x:x:x:x:x:x\nx:x:x:x:x:x:x:x/mmm\nx:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation\nloopback, localhost, unspecified, any, default\n::x:x/host\n0xABCDEF, 0b111111000101011110 within the limits\nof perl's number resolution\n123456789012 a 'big' bcd number (bigger than perl likes)\nand Math::BigInt\n\nA Fully Qualified Domain Name which returns an ipV4 address or an ipV6 address, embodied in\nthat order. This previously undocumented feature may be disabled with:\n\nuse NetAddr::IP::Lite ':nofqdn';\n\nIf called with no arguments, 'default' is assumed.\n\nIf called with and empty string as the argument, 'undef' is returned;\n\n\"->broadcast()\"\nReturns a new object referring to the broadcast address of a given subnet. The broadcast\naddress has all ones in all the bit positions where the netmask has zero bits. This is\nnormally used to address all the hosts in a given subnet.\n\n\"->network()\"\nReturns a new object referring to the network address of a given subnet. A network address\nhas all zero bits where the bits of the netmask are zero. Normally this is used to refer to\na subnet.\n\n\"->addr()\"\nReturns a scalar with the address part of the object as an IPv4 or IPv6 text string as\nappropriate. This is useful for printing or for passing the address part of the\nNetAddr::IP::Lite object to other components that expect an IP address. If the object is an\nipV6 address or was created using ->new6($ip) it will be reported in ipV6 hex format\notherwise it will be reported in dot quad format only if it resides in ipV4 address space.\n\n\"->mask()\"\nReturns a scalar with the mask as an IPv4 or IPv6 text string as described above.\n\n\"->masklen()\"\nReturns a scalar the number of one bits in the mask.\n\n\"->bits()\"\nReturns the width of the address in bits. Normally 32 for v4 and 128 for v6.\n\n\"->version()\"\nReturns the version of the address or subnet. Currently this can be either 4 or 6.\n\n\"->cidr()\"\nReturns a scalar with the address and mask in CIDR notation. A NetAddr::IP::Lite object\n*stringifies* to the result of this function. (see comments about ->new6() and ->addr() for\noutput formats)\n\n\"->aton()\"\nReturns the address part of the NetAddr::IP::Lite object in the same format as the\n\"inetaton()\" or \"ipv6aton\" function respectively. If the object was created using\n->new6($ip), the address returned will always be in ipV6 format, even for addresses in ipV4\naddress space.\n\n\"->range()\"\nReturns a scalar with the base address and the broadcast address separated by a dash and\nspaces. This is called range notation.\n\n\"->numeric()\"\nWhen called in a scalar context, will return a numeric representation of the address part of\nthe IP address. When called in an array context, it returns a list of two elements. The\nfirst element is as described, the second element is the numeric representation of the\nnetmask.\n\nThis method is essential for serializing the representation of a subnet.\n\n\"->bigint()\"\nWhen called in a scalar context, will return a Math::BigInt representation of the address\npart of the IP address. When called in an array contest, it returns a list of two elements.\nThe first element is as described, the second element is the Math::BigInt representation of\nthe netmask.\n\n\"$me->contains($other)\"\nReturns true when $me completely contains $other. False is returned otherwise and \"undef\" is\nreturned if $me and $other are not both \"NetAddr::IP::Lite\" objects.\n\n\"$me->within($other)\"\nThe complement of \"->contains()\". Returns true when $me is completely contained within\n$other, undef if $me and $other are not both \"NetAddr::IP::Lite\" objects.\n\nC->isrfc1918()>\nReturns true when $me is an RFC 1918 address.\n\n10.0.0.0 - 10.255.255.255 (10/8 prefix)\n172.16.0.0 - 172.31.255.255 (172.16/12 prefix)\n192.168.0.0 - 192.168.255.255 (192.168/16 prefix)\n\n\"->islocal()\"\nReturns true when $me is a local network address.\n\ni.e. ipV4 127.0.0.0 - 127.255.255.255\nor ipV6 === ::1\n\n\"->first()\"\nReturns a new object representing the first usable IP address within the subnet (ie, the\nfirst host address).\n\n\"->last()\"\nReturns a new object representing the last usable IP address within the subnet (ie, one less\nthan the broadcast address).\n\n\"->nth($index)\"\nReturns a new object representing the *n*-th usable IP address within the subnet (ie, the\n*n*-th host address). If no address is available (for example, when the network is too small\nfor $index hosts), \"undef\" is returned.\n\nVersion 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite implements \"->nth($index)\"\nand \"->num()\" exactly as the documentation states. Previous versions behaved slightly\ndifferently and not in a consistent manner.\n\nTo use the old behavior for \"->nth($index)\" and \"->num()\":\n\nuse NetAddr::IP::Lite qw(:oldnth);\n\nold behavior:\nNetAddr::IP->new('10/32')->nth(0) == undef\nNetAddr::IP->new('10/32')->nth(1) == undef\nNetAddr::IP->new('10/31')->nth(0) == undef\nNetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31\nNetAddr::IP->new('10/30')->nth(0) == undef\nNetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30\nNetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30\nNetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30\n\nNote that in each case, the broadcast address is represented in the output set and that the\n'zero'th index is alway undef except for a point-to-point /31 or /127 network where there\nare exactly two addresses in the network.\n\nnew behavior:\nNetAddr::IP->new('10/32')->nth(0) == 10.0.0.0/32\nNetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32\nNetAddr::IP->new('10/31')->nth(0) == 10.0.0.0/32\nNetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/32\nNetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30\nNetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30\nNetAddr::IP->new('10/30')->nth(2) == undef\n\nNote that a /32 net always has 1 usable address while a /31 has exactly two usable addresses\nfor point-to-point addressing. The first index (0) returns the address immediately following\nthe network address except for a /31 or /127 when it return the network address.\n\n\"->num()\"\nAs of version 4.42 of NetAddr::IP and version 1.27 of NetAddr::IP::Lite a /31 and /127 with\nreturn a net num value of 2 instead of 0 (zero) for point-to-point networks.\n\nVersion 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite return the number of\nusable IP addresses within the subnet, not counting the broadcast or network address.\n\nPrevious versions worked only for ipV4 addresses, returned a maximum span of 232 and\nreturned the number of IP addresses not counting the broadcast address. (one greater than\nthe new behavior)\n\nTo use the old behavior for \"->nth($index)\" and \"->num()\":\n\nuse NetAddr::IP::Lite qw(:oldnth);\n\nWARNING:\n\nNetAddr::IP will calculate and return a numeric string for network ranges as large as\n2128. These values are TEXT strings and perl can treat them as integers for numeric\ncalculations.\n\nPerl on 32 bit platforms only handles integer numbers up to 232 and on 64 bit platforms to\n264.\n\nIf you wish to manipulate numeric strings returned by NetAddr::IP that are larger than 232\nor 264, respectively, you must load additional modules such as Math::BigInt, bignum or\nsome similar package to do the integer math.\n" } ] }, "EXPORTOK": { "content": "Zeros\nOnes\nV4mask\nV4net\n:aton DEPRECATED\n:oldnth\n:upper\n:lower\n:nofqdn\n", "subsections": [] }, "AUTHORS": { "content": "Luis E. Muñoz , Michael Robinton \n", "subsections": [] }, "WARRANTY": { "content": "This software comes with the same warranty as perl itself (ie, none), so by using it you accept\nany and all the liability.\n", "subsections": [] }, "COPYRIGHT": { "content": "This software is (c) Luis E. Muñoz, 1999 - 2005\nand (c) Michael Robinton, 2006 - 2014.\n\nAll rights reserved.\n\nThis program is free software; you can redistribute it and/or modify it under the terms of\neither:\n\na) the GNU General Public License as published by the Free\nSoftware Foundation; either version 2, or (at your option) any\nlater version, or\n\nb) the \"Artistic License\" which comes with this distribution.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;\nwithout even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See\neither the GNU General Public License or the Artistic License for more details.\n\nYou should have received a copy of the Artistic License with this distribution, in the file\nnamed \"Artistic\". If not, I'll be glad to provide one.\n\nYou should also have received a copy of the GNU General Public License along with this program\nin the file named \"Copying\". If not, write to the\n\nFree Software Foundation, Inc.,\n51 Franklin Street, Fifth Floor\nBoston, MA 02110-1301 USA\n\nor visit their web page on the internet at:\n\nhttp://www.gnu.org/copyleft/gpl.html.\n", "subsections": [] }, "SEE ALSO": { "content": "NetAddr::IP(3), NetAddr::IP::Util(3), NetAddr::IP::InetBase(3)\n", "subsections": [] } } } }