.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Net::Works::Network 3pm" .TH Net::Works::Network 3pm "2019-01-15" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Works::Network \- An object representing a single IP address (4 or 6) subnet .SH "VERSION" .IX Header "VERSION" version 0.22 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Net::Works::Network; \& \& my $network = Net::Works::Network\->new_from_string( string => \*(Aq192.0.2.0/24\*(Aq ); \& print $network\->as_string(); # 192.0.2.0/24 \& print $network\->prefix_length(); # 24 \& print $network\->bits(); # 32 \& print $network\->version(); # 4 \& \& my $first_address = $network\->first(); \& print $first_address\->as_string(); # 192.0.2.0 \& \& my $last_address = $network\->last(); \& print $last_address\->as_string(); # 192.0.2.255 \& \& my $iterator = $network\->iterator(); \& while ( my $ip = $iterator\->() ) { print $ip . "\en"; } \& \& my $network_32 = Net::Works::Network\->new_from_string( string => \*(Aq192.0.2.4/32\*(Aq ); \& print $network_32\->max_prefix_length(); # 30 \& \& # All methods work with IPv4 and IPv6 subnets \& my $ipv6_network = Net::Works::Network\->new_from_string( string => \*(Aq2001:db8::/48\*(Aq ); \& \& my @subnets = Net::Works::Network\->range_as_subnets( \*(Aq192.0.2.1\*(Aq, \*(Aq192.0.2.32\*(Aq ); \& print $_\->as_string, "\en" for @subnets; \& # 192.0.2.1/32 \& # 192.0.2.2/31 \& # 192.0.2.4/30 \& # 192.0.2.8/29 \& # 192.0.2.16/28 \& # 192.0.2.32/32 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Objects of this class represent an \s-1IP\s0 address network. It can handle both IPv4 and IPv6 subnets. It provides various methods for getting information about the subnet. .PP For IPv6, it uses 128\-bit integers (via Math::Int128) to represent the numeric value of an address as needed. .SH "METHODS" .IX Header "METHODS" This class provides the following methods: .SS "Net::Works::Network\->new_from_string( ... )" .IX Subsection "Net::Works::Network->new_from_string( ... )" This method takes a \f(CW\*(C`string\*(C'\fR parameter and an optional \f(CW\*(C`version\*(C'\fR parameter. The \f(CW\*(C`string\*(C'\fR parameter should be a string representation of an \s-1IP\s0 address subnet, e.g., \*(L"192.0.2.0/24\*(R". .PP .Vb 4 \& my $network = Net::Works::Network\->new_from_string( \& string => \*(Aq192.0.2.0/24\*(Aq \& ); \& print $network\->as_string; # 192.0.2.0/24 .Ve .PP The \f(CW\*(C`version\*(C'\fR parameter should be either \f(CW4\fR or \f(CW6\fR, but you don't really need this unless you're trying to force a dotted quad to be interpreted as an IPv6 network or to a force an IPv6 address colon-separated hex number to be interpreted as an IPv4 network. .PP If you pass an IPv4 network but specify the version as \f(CW6\fR then we will add 96 to the netmask. .PP .Vb 5 \& my $network = Net::Works::Network\->new_from_string( \& string => \*(Aq192.0.2.0/24\*(Aq, \& version => 6, \& ); \& print $network\->as_string; # ::192.0.2.0/120 .Ve .SS "Net::Works::Network\->new_from_integer( ... )" .IX Subsection "Net::Works::Network->new_from_integer( ... )" This method takes an \f(CW\*(C`integer\*(C'\fR parameter, \f(CW\*(C`prefix_length\*(C'\fR parameter, and an optional \f(CW\*(C`version\*(C'\fR parameter. The \f(CW\*(C`integer\*(C'\fR parameter should be an integer representation of an \s-1IP\s0 within the subnet. The \f(CW\*(C`prefix_length\*(C'\fR parameter should be an integer between 0 and 32 for IPv4 or 0 and 128 for IPv6. The \f(CW\*(C`version\*(C'\fR parameter should be either \f(CW4\fR or \f(CW6\fR. .PP Note that if you are passing an IPv4 address that you want treated as an IPv6 address you need to manually add 96 to the \f(CW\*(C`prefix_length\*(C'\fR yourself. .ie n .SS "$network\->\fBas_string()\fP" .el .SS "\f(CW$network\fP\->\fBas_string()\fP" .IX Subsection "$network->as_string()" Returns a string representation of the network like \*(L"192.0.2.0/24\*(R" or \&\*(L"2001:db8::/48\*(R". The \s-1IP\s0 address in the string is the first address within the subnet. .ie n .SS "$network\->\fBversion()\fP" .el .SS "\f(CW$network\fP\->\fBversion()\fP" .IX Subsection "$network->version()" Returns a 4 or 6 to indicate whether this is an IPv4 or IPv6 network. .ie n .SS "$network\->\fBprefix_length()\fP" .el .SS "\f(CW$network\fP\->\fBprefix_length()\fP" .IX Subsection "$network->prefix_length()" Returns the length of the netmask as an integer. .ie n .SS "$network\->\fBbits()\fP" .el .SS "\f(CW$network\fP\->\fBbits()\fP" .IX Subsection "$network->bits()" Returns the number of bit of an address in the network, which is either 32 (IPv4) or 128 (IPv6). .ie n .SS "$network\->\fBmax_prefix_length()\fP" .el .SS "\f(CW$network\fP\->\fBmax_prefix_length()\fP" .IX Subsection "$network->max_prefix_length()" This returns the maximum possible numeric subnet that this network could fit in. In other words, the 192.0.2.0/28 subnet could be part of the 192.0.2.0/23 subnet, so this returns 23. .ie n .SS "$network\->\fBfirst()\fP" .el .SS "\f(CW$network\fP\->\fBfirst()\fP" .IX Subsection "$network->first()" Returns the first \s-1IP\s0 in the network as an Net::Works::Address object. .ie n .SS "$network\->\fBfirst_as_integer()\fP" .el .SS "\f(CW$network\fP\->\fBfirst_as_integer()\fP" .IX Subsection "$network->first_as_integer()" Returns the first \s-1IP\s0 in the network as an integer. This may be a Math::Int128 object. .ie n .SS "$network\->\fBlast()\fP" .el .SS "\f(CW$network\fP\->\fBlast()\fP" .IX Subsection "$network->last()" Returns the last \s-1IP\s0 in the network as an Net::Works::Address object. .ie n .SS "$network\->\fBlast_as_integer()\fP" .el .SS "\f(CW$network\fP\->\fBlast_as_integer()\fP" .IX Subsection "$network->last_as_integer()" Returns the last \s-1IP\s0 in the network as an integer. This may be a Math::Int128 object. .ie n .SS "$network\->\fBis_single_address()\fP" .el .SS "\f(CW$network\fP\->\fBis_single_address()\fP" .IX Subsection "$network->is_single_address()" Returns true if the network contains just a single address (/32 in IPv4 or /128 in IPv6). .ie n .SS "$network\->\fBiterator()\fP" .el .SS "\f(CW$network\fP\->\fBiterator()\fP" .IX Subsection "$network->iterator()" This returns an anonymous sub that returns one \s-1IP\s0 address in the range each time it's called. .PP For single address subnets (/32 or /128), this returns a single address. .PP When it has exhausted all the addresses in the network, it returns \f(CW\*(C`undef\*(C'\fR .ie n .SS "$network\->contains($address_or_network)" .el .SS "\f(CW$network\fP\->contains($address_or_network)" .IX Subsection "$network->contains($address_or_network)" This method accepts a single Net::Works::Address or Net::Works::Network object. It returns true if the given address or network is contained by the network it is called on. Note that a network always contains itself. .ie n .SS "$network\->\fBsplit()\fP" .el .SS "\f(CW$network\fP\->\fBsplit()\fP" .IX Subsection "$network->split()" This returns a list of two new network objects representing the original network split into two halves. For example, splitting \f(CW\*(C`192.0.2.0/24\*(C'\fR returns \&\f(CW\*(C`192.0.2.0/25\*(C'\fR and \f(CW\*(C`192.0.2.128/25\*(C'\fR. .PP If the original networks is a single address network (a /32 in IPv4 or /128 in IPv6) then this method returns an empty list. .ie n .SS "Net::Works::Network\->range_as_subnets( $first_address, $last_address, $version )" .el .SS "Net::Works::Network\->range_as_subnets( \f(CW$first_address\fP, \f(CW$last_address\fP, \f(CW$version\fP )" .IX Subsection "Net::Works::Network->range_as_subnets( $first_address, $last_address, $version )" Given two \s-1IP\s0 addresses as strings, this method breaks the range up into the largest subnets that include all the \s-1IP\s0 addresses in the range (including the two passed to this method). .PP This method also excludes any reserved subnets such as the \&\s-1RFC1918\s0 IPv4 private address space, \&\s-1RFC5735\s0 IPv4 special-use address space and \&\s-1RFC5156\s0 IPv6 special-use address space. .PP An overview can be found at the \s-1IANA\s0 IPv4 and IPv6 special-purpose address registries. .PP The networks currently treated as reserved are: .PP .Vb 10 \& 0.0.0.0/8 \& 10.0.0.0/8 \& 100.64.0.0/10 \& 127.0.0.0/8 \& 169.254.0.0/16 \& 172.16.0.0/12 \& 192.0.0.0/29 \& 192.0.2.0/24 \& 192.88.99.0/24 \& 192.168.0.0/16 \& 198.18.0.0/15 \& 198.51.100.0/24 \& 203.0.113.0/24 \& 224.0.0.0/4 \& 240.0.0.0/4 \& \& 100::/64 \& 2001::/23 \& 2001:db8::/32 \& fc00::/7 \& fe80::/10 \& ff00::/8 .Ve .PP This method works with both IPv4 and IPv6 addresses. You can pass an explicit version as the final argument. If you don't, we check whether either address contains a colon (:). If either of them does, we assume you want IPv6 subnets. .PP When given an IPv6 range that includes the first 32 bits of addresses (the IPv4 space), both IPv4 \fIand\fR IPv6 reserved networks are removed from the range. .SH "OVERLOADING" .IX Header "OVERLOADING" This class overloads comparison, allowing you to compare two objects and to sort them (either as numbers or strings). Objects are compared based on the first \s-1IP\s0 address in their networks, and then by prefix length if they have the same starting address. .PP It also overloads stringification to call the \f(CW\*(C`$network\->as_string()\*(C'\fR method. .SH "DEPRECATED METHODS AND ATTRIBUTES" .IX Header "DEPRECATED METHODS AND ATTRIBUTES" Prior to version 0.17, this package referred to the prefix length as mask length. The \f(CW\*(C`mask_length()\*(C'\fR and \f(CW\*(C`max_mask_length()\*(C'\fR methods are deprecated, and will probably start warning in a future release. In addition, passing a \&\f(CW\*(C`mask_length\*(C'\fR key to the \f(CW\*(C`new_from_integer()\*(C'\fR constructor has been replaced by \f(CW\*(C`prefix_length\*(C'\fR. The old key will continue to work for now but may start warning in a future release. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Dave Rolsky .IP "\(bu" 4 Greg Oschwald .IP "\(bu" 4 Olaf Alders .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2016 by MaxMind, Inc. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.