.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Paranoid::Network 3pm"
.TH Paranoid::Network 3pm "2012-05-29" "perl v5.14.2" "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"
Paranoid::Network \- Network functions for paranoid programs
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Id:\fR Network.pm,v 0.68 2012/05/29 21:38:19 acorliss Exp $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Paranoid::Network;
\&
\&  $rv  = ipInNetwork($ip, @networks);
\&  $rv  = hostInDomain($host, @domains);
\&  @ips = extractIP($string1, $string2);
\&  $rv = netIntersect( $cidr1, $cidr2 );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This modules contains functions that may be useful for network operations.
IPv6 is supported out of the box starting with Perl 5.14.  Earlier versions of
Perl will require \fISocket6\fR\|(3) installed as well.  If it is available this
module will use it automatically.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
.SS "ipInNetwork"
.IX Subsection "ipInNetwork"
.Vb 1
\&  $rv = ipInNetwork($ip, @networks);
.Ve
.PP
This function checks the passed \s-1IP\s0 against each of the networks 
or IPs in the list and returns true if there's a match.  The list of networks
can be either individual \s-1IP\s0 address or network addresses in \s-1CIDR\s0 notation or
with full netmasks:
.PP
.Vb 3
\&  @networks = qw(127.0.0.1 
\&                 192.168.0.0/24 
\&                 172.16.12.0/255.255.240.0);
.Ve
.PP
IPv6 is supported if the \fISocket6\fR\|(3) module is installed or you're running
Perl 5.14 or higher.  This routine will select the appropriate address family 
based on the \s-1IP\s0 you're testing and filter out the opposing address family in 
the list.
.PP
\&\fB\s-1NOTE:\s0\fR  IPv4 addresses encoded as IPv6 addresses, e.g.:
.PP
.Vb 1
\&  ::ffff:192.168.0.5
.Ve
.PP
are supported, however an \s-1IP\s0 address submitted in this format as the \s-1IP\s0 to
test for will be converted to a pure IPv4 address and compared only against
the IPv4 networks.  This is meant as a convenience to the developer supporting
dual-stack systems to avoid having to list IPv4 networks in the array twice
like so:
.PP
.Vb 1
\&  ::ffff:192.168.0.0/120, 192.168.0.0/24
.Ve
.PP
Just list IPv4 as IPv4, IPv6 as IPv6, and this routine will convert
IPv6\-encoded IPv4 addresses automatically.  This would make the following test
return a true value:
.PP
.Vb 1
\&  ipInNetwork( \*(Aq::ffff:192.168.0.5\*(Aq, \*(Aq192.168.0.0/24\*(Aq );
.Ve
.PP
but
.PP
.Vb 1
\&  ipInNetwork( \*(Aq::ffff:192.168.0.5\*(Aq, \*(Aq::ffff:192.168.0.0/120\*(Aq );
.Ve
.PP
return a false value.  This may seem counter intuitive, but it simplifies
things in (my alternate) reality.
.PP
Please note that this automatic conversion only applies to the \fB\s-1IP\s0\fR argument,
not to any member of the network array.
.SS "hostInDomain"
.IX Subsection "hostInDomain"
.Vb 1
\&  $rv = hostInDomain($host, @domains);
.Ve
.PP
This function checks the passed hostname (fully qualified) against each 
of the domains in the list and returns true if there's a match.  None of the
domains should have the preceding '.' (i.e., 'foo.com' rather than 
\&'.foo.com').
.SS "extractIPs"
.IX Subsection "extractIPs"
.Vb 1
\&    @ips = extractIP($string1, $string2);
.Ve
.PP
This function extracts \s-1IP\s0 addresses from arbitrary text.  If you have
\&\fISocket6\fR\|(3) installed or running Perl 5.14 or higher it will extract 
IPv6 addresses as well as IPv4 addresses.  This extracts only \s-1IP\s0 
addresses, not network addresses in \s-1CIDR\s0 or dotted octet
notation.  In the case of the latter the netmask will be extracted as an
additional address.
.PP
\&\fB\s-1NOTE:\s0\fR in the interest of performance this function does only rough regex
extraction of IP-looking candidates, then runs them through \fBinet_aton\fR (for
IPv4) and \fBinet_pton\fR (for IPv6) to see if they successfully convert.  Even
with the overhead of \fBParanoid\fR (with debugging and \fIloadModule\fR calls for
Socket6 and what-not) it seems that this is an order of a magnitude faster
than doing a pure regex extraction & validation of IPv6 addresses.
.PP
\&\fB\s-1NOTE:\s0\fR Like the \fBipInNetwork\fR function we filter out IPv4 addresses encoded
as IPv6 addresses since that address is already returned as a pure IPv4
address.
.SS "netIntersect"
.IX Subsection "netIntersect"
.Vb 1
\&  $rv = netIntersect( $cidr1, $cidr2 );
.Ve
.PP
This function is an IPv4/IPv6 agnostic wrapper for the \fBipv{4,6}NetIntersect\fR
functions provided by Paranoid::Network::IPv{4,6} modules.  The return
value from which ever function called is passed on directly.  Passing this
function non-IP or undefined values simply returns a zero.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "o" 4
.IX Item "o"
Paranoid
.IP "o" 4
.IX Item "o"
Paranoid::Network::Socket
.IP "o" 4
.IX Item "o"
Paranoid::Network::IPv4
.IP "o" 4
.IX Item "o"
Paranoid::Network::IPv6
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
.SH "AUTHOR"
.IX Header "AUTHOR"
Arthur Corliss (corliss@digitalmages.com)
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This software is licensed under the same terms as Perl, itself. 
Please see http://dev.perl.org/licenses/ for more information.
.PP
(c) 2005, Arthur Corliss (corliss@digitalmages.com)