{ "content": [ { "type": "text", "text": "# NetAddr::IP (perldoc)\n\n## NAME\n\nNetAddr::IP - Manages IPv4 and IPv6 addresses and subnets\n\n## SYNOPSIS\n\nuse NetAddr::IP qw(\nCompact\nCoalesce\nZeros\nOnes\nV4mask\nV4net\nnetlimit\n:aton DEPRECATED\n:lower\n:upper\n:oldstorable\n:oldnth\n:rfc3021\n:nofqdn\n);\nNOTE: NetAddr::IP::Util has a full complement of network address\nutilities to convert back and forth between binary and text.\ninetaton, inetntoa, ipv6aton, ipv6ntoa\nipv6n2x, ipv6n2d inetany2d, inetn2dx,\ninetn2ad, inetanyto6, ipv6to4\nSee NetAddr::IP::Util\nmy $ip = new NetAddr::IP '127.0.0.1';\nor if you prefer\nmy $ip = NetAddr::IP->new('127.0.0.1);\nor from a packed IPv4 address\nmy $ip = newfromaton NetAddr::IP (inetaton('127.0.0.1'));\nor from an octal filtered IPv4 address\nmy $ip = newno NetAddr::IP '127.012.0.0';\nprint \"The address is \", $ip->addr, \" with mask \", $ip->mask, \"\\n\" ;\nif ($ip->within(new NetAddr::IP \"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\";\n* The 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###### DEPRECATED, will be remove in version 5 ############\n* To accept addresses in the format as returned by\ninetaton, invoke the module as:\nuse NetAddr::IP qw(:aton);\n###### USE newfromaton instead ##########################\n* To enable usage of legacy data files containing NetAddr::IP objects stored using the Storable\nmodule.\nuse NetAddr::IP qw(:oldstorable);\n* To compact many smaller subnets (see: \"$me->compact($addr1,$addr2,...)\"\n@compactedobjectlist = Compact(@objectlist)\n* Return a reference to list of \"NetAddr::IP\" subnets of $masklen mask length, when $number or\nmore addresses from @listofsubnets are found to be contained in said subnet.\n$arrayref = Coalesce($masklen, $number, @listofsubnets)\n* By default NetAddr::IP functions and methods return string IPv6 addresses in uppercase. To\nchange that to lowercase:\nNOTE: the AUGUST 2010 RFC5952 states:\n4.3. Lowercase\nThe characters \"a\", \"b\", \"c\", \"d\", \"e\", and \"f\" in an IPv6\naddress MUST be represented in lowercase.\nIt is recommended that all NEW applications using NetAddr::IP be invoked as shown on the next\nline.\nuse NetAddr::IP qw(:lower);\n* To ensure the current IPv6 string case behavior even if the default changes:\nuse NetAddr::IP qw(:upper);\n* To set a limit on the size of nets processed or returned by NetAddr::IP.\nSet the maximum number of nets beyond which NetAddr::IP will return an error as a power of 2\n(default 16 or 65536 nets). Each 216 consumes approximately 4 megs of memory. A 220 consumes\n64 megs of memory, A 224 consumes 1 gigabyte of memory.\nuse NetAddr::IP qw(netlimit);\nnetlimit 20;\nThe maximum netlimit allowed is 224. Attempts to set limits below the default of 16 or above\nthe maximum of 24 are ignored.\nReturns true on success, otherwise \"undef\".\n\n## DESCRIPTION\n\nThis module provides an object-oriented abstraction on top of IP addresses or IP subnets that\nallows for easy manipulations. Version 4.xx of NetAddr::IP will work with older versions of Perl\nand is compatible with Math::BigInt.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **INSTALLATION**\n- **DESCRIPTION** (3 subsections)\n- **EXPORTOK**\n- **HISTORY**\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", "section": "", "mode": "perldoc", "summary": "NetAddr::IP - Manages IPv4 and IPv6 addresses and subnets", "synopsis": "use NetAddr::IP qw(\nCompact\nCoalesce\nZeros\nOnes\nV4mask\nV4net\nnetlimit\n:aton DEPRECATED\n:lower\n:upper\n:oldstorable\n:oldnth\n:rfc3021\n:nofqdn\n);\nNOTE: NetAddr::IP::Util has a full complement of network address\nutilities to convert back and forth between binary and text.\ninetaton, inetntoa, ipv6aton, ipv6ntoa\nipv6n2x, ipv6n2d inetany2d, inetn2dx,\ninetn2ad, inetanyto6, ipv6to4\nSee NetAddr::IP::Util\nmy $ip = new NetAddr::IP '127.0.0.1';\nor if you prefer\nmy $ip = NetAddr::IP->new('127.0.0.1);\nor from a packed IPv4 address\nmy $ip = newfromaton NetAddr::IP (inetaton('127.0.0.1'));\nor from an octal filtered IPv4 address\nmy $ip = newno NetAddr::IP '127.012.0.0';\nprint \"The address is \", $ip->addr, \" with mask \", $ip->mask, \"\\n\" ;\nif ($ip->within(new NetAddr::IP \"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\";\n* The 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###### DEPRECATED, will be remove in version 5 ############\n* To accept addresses in the format as returned by\ninetaton, invoke the module as:\nuse NetAddr::IP qw(:aton);\n###### USE newfromaton instead ##########################\n* To enable usage of legacy data files containing NetAddr::IP objects stored using the Storable\nmodule.\nuse NetAddr::IP qw(:oldstorable);\n* To compact many smaller subnets (see: \"$me->compact($addr1,$addr2,...)\"\n@compactedobjectlist = Compact(@objectlist)\n* Return a reference to list of \"NetAddr::IP\" subnets of $masklen mask length, when $number or\nmore addresses from @listofsubnets are found to be contained in said subnet.\n$arrayref = Coalesce($masklen, $number, @listofsubnets)\n* By default NetAddr::IP functions and methods return string IPv6 addresses in uppercase. To\nchange that to lowercase:\nNOTE: the AUGUST 2010 RFC5952 states:\n4.3. Lowercase\nThe characters \"a\", \"b\", \"c\", \"d\", \"e\", and \"f\" in an IPv6\naddress MUST be represented in lowercase.\nIt is recommended that all NEW applications using NetAddr::IP be invoked as shown on the next\nline.\nuse NetAddr::IP qw(:lower);\n* To ensure the current IPv6 string case behavior even if the default changes:\nuse NetAddr::IP qw(:upper);\n* To set a limit on the size of nets processed or returned by NetAddr::IP.\nSet the maximum number of nets beyond which NetAddr::IP will return an error as a power of 2\n(default 16 or 65536 nets). Each 216 consumes approximately 4 megs of memory. A 220 consumes\n64 megs of memory, A 224 consumes 1 gigabyte of memory.\nuse NetAddr::IP qw(netlimit);\nnetlimit 20;\nThe maximum netlimit allowed is 224. Attempts to set limits below the default of 16 or above\nthe maximum of 24 are ignored.\nReturns true on success, otherwise \"undef\".", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "perl", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/perl/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 109, "subsections": [] }, { "name": "INSTALLATION", "lines": 16, "subsections": [] }, { "name": "DESCRIPTION", "lines": 7, "subsections": [ { "name": "Overloaded Operators", "lines": 85 }, { "name": "Serializing and Deserializing", "lines": 9 }, { "name": "Methods", "lines": 433 } ] }, { "name": "EXPORTOK", "lines": 13, "subsections": [] }, { "name": "HISTORY", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "WARRANTY", "lines": 3, "subsections": [] }, { "name": "COPYRIGHT", "lines": 31, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] } ], "sections": { "NAME": { "content": "NetAddr::IP - Manages IPv4 and IPv6 addresses and subnets\n", "subsections": [] }, "SYNOPSIS": { "content": "use NetAddr::IP qw(\nCompact\nCoalesce\nZeros\nOnes\nV4mask\nV4net\nnetlimit\n:aton DEPRECATED\n:lower\n:upper\n:oldstorable\n:oldnth\n:rfc3021\n:nofqdn\n);\n\nNOTE: NetAddr::IP::Util has a full complement of network address\nutilities to convert back and forth between binary and text.\n\ninetaton, inetntoa, ipv6aton, ipv6ntoa\nipv6n2x, ipv6n2d inetany2d, inetn2dx,\ninetn2ad, inetanyto6, ipv6to4\n\nSee NetAddr::IP::Util\n\nmy $ip = new NetAddr::IP '127.0.0.1';\nor if you prefer\nmy $ip = NetAddr::IP->new('127.0.0.1);\nor from a packed IPv4 address\nmy $ip = newfromaton NetAddr::IP (inetaton('127.0.0.1'));\nor from an octal filtered IPv4 address\nmy $ip = newno NetAddr::IP '127.012.0.0';\n\nprint \"The address is \", $ip->addr, \" with mask \", $ip->mask, \"\\n\" ;\n\nif ($ip->within(new NetAddr::IP \"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\n* The 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\n###### DEPRECATED, will be remove in version 5 ############\n\n* To accept addresses in the format as returned by\ninetaton, invoke the module as:\n\nuse NetAddr::IP qw(:aton);\n\n###### USE newfromaton instead ##########################\n\n* To enable usage of legacy data files containing NetAddr::IP objects stored using the Storable\nmodule.\n\nuse NetAddr::IP qw(:oldstorable);\n\n* To compact many smaller subnets (see: \"$me->compact($addr1,$addr2,...)\"\n\n@compactedobjectlist = Compact(@objectlist)\n\n* Return a reference to list of \"NetAddr::IP\" subnets of $masklen mask length, when $number or\nmore addresses from @listofsubnets are found to be contained in said subnet.\n\n$arrayref = Coalesce($masklen, $number, @listofsubnets)\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 be invoked as shown on the next\nline.\n\nuse NetAddr::IP qw(:lower);\n\n* To ensure the current IPv6 string case behavior even if the default changes:\n\nuse NetAddr::IP qw(:upper);\n\n* To set a limit on the size of nets processed or returned by NetAddr::IP.\n\nSet the maximum number of nets beyond which NetAddr::IP will return an error as a power of 2\n(default 16 or 65536 nets). Each 216 consumes approximately 4 megs of memory. A 220 consumes\n64 megs of memory, A 224 consumes 1 gigabyte of memory.\n\nuse NetAddr::IP qw(netlimit);\nnetlimit 20;\n\nThe maximum netlimit allowed is 224. Attempts to set limits below the default of 16 or above\nthe maximum of 24 are ignored.\n\nReturns true on success, otherwise \"undef\".\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 depends on NetAddr::IP::Util which installs by default with its primary functions\ncompiled using Perl's XS extensions to build a C library. If you do not have a C compiler\navailable 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. Version 4.xx of NetAddr::IP will work with older versions of Perl\nand is compatible with Math::BigInt.\n\nThe internal representation of all IP objects is in 128 bit IPv6 notation. IPv4 and IPv6 objects\nmay be freely mixed.\n", "subsections": [ { "name": "Overloaded Operators", "content": "Many operators have been overloaded, as described below:\n\nAssignment (\"=\")\nHas been optimized to copy one NetAddr::IP 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 '192.168.1.123';\nprint \"$ip\\n\";\n\nWill print the string 192.168.1.123/32.\n\nEquality\nYou can test for equality with either \"eq\" or \"==\". \"eq\" allows comparison with arbitrary\nstrings as well as NetAddr::IP objects. The following example:\n\nif (NetAddr::IP->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 \"==\" requires both operands to be NetAddr::IP objects.\n\nIn both cases, a true value is returned if the CIDR representation of the operands is equal.\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->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->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 objects address parts as\na 32 bit signed number.\n\nReturns undef if the difference is out of range.\n\n(See range restrictions on Addition above)\n\nAuto-increment\nAuto-incrementing a NetAddr::IP object causes the address part to be adjusted to the next\nhost address within the subnet. It will wrap at the broadcast address and start again from\nthe network address.\n\nAuto-decrement\nAuto-decrementing a NetAddr::IP object performs exactly the opposite of auto-incrementing\nit, as you would expect.\n" }, { "name": "Serializing and Deserializing", "content": "This module defines hooks to collaborate with Storable for serializing \"NetAddr::IP\" objects,\nthrough compact and human readable strings. You can revert to the old format by invoking this\nmodule as\n\nuse NetAddr::IP ':oldstorable';\n\nYou must do this if you have legacy data files containing NetAddr::IP objects stored using the\nStorable module.\n" }, { "name": "Methods", "content": "\"->new([$addr, [ $mask|IPv6 ]])\"\n\"->new6([$addr, [ $mask]])\"\n\"->newno([$addr, [ $mask]])\"\n\"->newfromaton($netaddr)\"\nnewcis and newcis6 are DEPRECATED\n\"->newcis(\"$addr $mask)\"\n\"->newcis6(\"$addr $mask)\"\nThe first two 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\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.\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\nTo accept addresses in that format, invoke the module as in\n\nuse NetAddr::IP ':aton'\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.n\nn.n.n/mm\nn.n.n.n\nn.n.n.n/mm 32 bit cidr notation\nn.n.n.n/m.m.m.m\nloopback, localhost, broadcast, any, default\nx.x.x.x/host\n0xABCDEF, 0b111111000101011110, (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 an empty string as the argument, returns 'undef'\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 NetAddr::IP\nobject to other components that expect an IP address. If the object is an ipV6 address or\nwas created using ->new6($ip) it will be reported in ipV6 hex format otherwise it will be\nreported 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 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 object in the same format as the \"inetaton()\"\nor \"ipv6aton\" function respectively. If the object was created using ->new6($ip), the\naddress returned will always be in ipV6 format, even for addresses in ipV4 address 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\"->prefix()\"\nReturns a scalar with the address and mask in ipV4 prefix representation. This is useful for\nsome programs, which expect its input to be in this format. This method will include the\nbroadcast address in the encoding.\n\n\"->nprefix()\"\nJust as \"->prefix()\", but does not include the broadcast address.\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 contest, 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 scalar context, will return a Math::BigInt representation of the address part\nof the 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 Math::BigInt representation of the\nnetmask.\n\n\"->wildcard()\"\nWhen called in a scalar context, returns the wildcard bits corresponding to the mask, in\ndotted-quad or ipV6 format as applicable.\n\nWhen called in an array context, returns a two-element array. The first element, is the\naddress part. The second element, is the wildcard translation of the mask.\n\n\"->short()\"\nReturns the address part in a short or compact notation.\n\n(ie, 127.0.0.1 becomes 127.1).\n\nWorks with both, V4 and V6.\n\n\"->canon()\"\nReturns the address part in canonical notation as a string. For ipV4, this is dotted quad,\nand is the same as the return value from \"->addr()\". For ipV6 it is as per RFC5952, and is\nthe same as the LOWER CASE value returned by \"->short()\".\n\n\"->full()\"\nReturns the address part in FULL notation for ipV4 and ipV6 respectively.\n\ni.e. for ipV4\n0000:0000:0000:0000:0000:0000:127.0.0.1\n\nfor ipV6\n0000:0000:0000:0000:0000:0000:0000:0000\n\nTo force ipV4 addresses into full ipV6 format use:\n\n\"->full6()\"\nReturns the address part in FULL ipV6 notation\n\n\"->full6m()\"\nReturns the mask part in FULL ipV6 notation\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\" objects.\n\n\"$me->within($other)\"\nThe complement of \"->contains()\". Returns true when $me is completely contained within\n$other.\n\nNote that $me and $other must be \"NetAddr::IP\" 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\"->splitref($bits,[optional $bits1,$bits2,...])\"\nReturns a reference to a list of objects, representing subnets of \"bits\" mask produced by\nsplitting the original object, which is left unchanged. Note that $bits must be longer than\nthe original mask in order for it to be splittable.\n\nERROR conditions:\n\n->splitref will DIE with the message 'netlimit exceeded'\nif the number of return objects exceeds 'netlimit'.\nSee function 'netlimit' above (default 216 or 65536 nets).\n\n->splitref returns undef when C or the (bits list)\nwill not fit within the original object.\n\n->splitref returns undef if a supplied ipV4, ipV6, or NetAddr\nmask in inappropriately formatted,\n\nbits may be a CIDR mask, a dot quad or ipV6 string or a NetAddr::IP object. If \"bits\" is\nmissing, the object is split for into all available addresses within the ipV4 or ipV6 object\n( auto-mask of CIDR 32, 128 respectively ).\n\nWith optional additional \"bits\" list, the original object is split into parts sized based on\nthe list. NOTE: a short list will replicate the last item. If the last item is too large to\nfor what remains of the object after splitting off the first parts of the list, a \"best\nfits\" list of remaining objects will be returned based on an increasing sort of the CIDR\nvalues of the \"bits\" list.\n\ni.e. my $ip = new NetAddr::IP('192.168.0.0/24');\nmy $objptr = $ip->split(28, 29, 28, 29, 26);\n\nhas split plan 28 29 28 29 26 26 26 28\nand returns this list of objects\n\n192.168.0.0/28\n192.168.0.16/29\n192.168.0.24/28\n192.168.0.40/29\n192.168.0.48/26\n192.168.0.112/26\n192.168.0.176/26\n192.168.0.240/28\n\nNOTE: that /26 replicates twice beyond the original request and /28 fills the remaining\nreturn object requirement.\n\n\"->rsplitref($bits,[optional $bits1,$bits2,...])\"\n\"->rsplitref\" is the same as \"->splitref\" above except that the split plan is applied to the\noriginal object in reverse order.\n\ni.e. my $ip = new NetAddr::IP('192.168.0.0/24');\nmy @objects = $ip->split(28, 29, 28, 29, 26);\n\nhas split plan 28 26 26 26 29 28 29 28\nand returns this list of objects\n\n192.168.0.0/28\n192.168.0.16/26\n192.168.0.80/26\n192.168.0.144/26\n192.168.0.208/29\n192.168.0.216/28\n192.168.0.232/29\n192.168.0.240/28\n\n\"->split($bits,[optional $bits1,$bits2,...])\"\nSimilar to \"->splitref\" above but returns the list rather than a list reference. You may not\nwant to use this if a large number of objects is expected.\n\n\"->rsplit($bits,[optional $bits1,$bits2,...])\"\nSimilar to \"->rsplitref\" above but returns the list rather than a list reference. You may\nnot want to use this if a large number of objects is expected.\n\n\"->hostenum()\"\nReturns the list of hosts within a subnet.\n\nERROR conditions:\n\n->hostenum will DIE with the message 'netlimit exceeded'\nif the number of return objects exceeds 'netlimit'.\nSee function 'netlimit' above (default 216 or 65536 nets).\n\n\"->hostenumref()\"\nFaster version of \"->hostenum()\", returning a reference to a list.\n\nNOTE: hostenum and hostenumref report zero (0) useable hosts in a /31 network. This is the\nbehavior expected prior to RFC 3021. To report 2 useable hosts for use in point-to-point\nnetworks, use :rfc3021 tag.\n\nuse NetAddr::IP qw(:rfc3021);\n\nThis will cause hostenum and hostenumref to return two (2) useable hosts in a /31 network.\n\n\"$me->compact($addr1, $addr2, ...)\"\n\"@compactedobjectlist = Compact(@objectlist)\"\nGiven a list of objects (including $me), this method will compact all the addresses and\nsubnets into the largest (ie, least specific) subnets possible that contain exactly all of\nthe given objects.\n\nNote that in versions prior to 3.02, if fed with the same IP subnets multiple times, these\nsubnets would be returned. From 3.02 on, a more \"correct\" approach has been adopted and only\none address would be returned.\n\nNote that $me and all $addr's must be \"NetAddr::IP\" objects.\n\n\"$me->compactref(\\@list)\"\n\"$compactedobjectlist = Compact(\\@list)\"\nAs usual, a faster version of \"->compact()\" that returns a reference to a list. Note that\nthis method takes a reference to a list instead.\n\nNote that $me must be a \"NetAddr::IP\" object.\n\n\"$me->coalesce($masklen, $number, @listofsubnets)\"\n\"$arrayref = Coalesce($masklen,$number,@listofsubnets)\"\nWill return a reference to list of \"NetAddr::IP\" subnets of $masklen mask length, when\n$number or more addresses from @listofsubnets are found to be contained in said subnet.\n\nSubnets from @listofsubnets with a mask shorter than $masklen are passed \"as is\" to the\nreturn list.\n\nSubnets from @listofsubnets with a mask longer than $masklen will be counted (actually,\nthe number of IP addresses is counted) towards $number.\n\nCalled as a method, the array will include $me.\n\nWARNING: the list of subnet must be the same type. i.e ipV4 or ipV6\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. See the README file for details.\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/31\nNetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31\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\n\"->re()\"\nReturns a Perl regular expression that will match an IP address within the given subnet.\nDefaults to ipV4 notation. Will return an ipV6 regex if the address in not in ipV4 space.\n\n\"->re6()\"\nReturns a Perl regular expression that will match an IP address within the given subnet.\nAlways returns an ipV6 regex.\n" } ] }, "EXPORTOK": { "content": "Compact\nCoalesce\nZeros\nOnes\nV4mask\nV4net\nnetlimit\n\nNOTES / BUGS ... FEATURES\nNetAddr::IP only runs in Pure Perl mode on Windows boxes because I don't have the resources or\nknow how to get the \"configure\" stuff working in the Windows environment. Volunteers WELCOME to\nport the \"C\" portion of this module to Windows.\n", "subsections": [] }, "HISTORY": { "content": "See the Changes file\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 - 2007, and (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": "perl(1) L, L,\nL\n", "subsections": [] } } } }