WWWWWW

Current Directory: /usr/local/share/man/man3
Viewing File: /usr/local/share/man/man3/Net::CIDR::Lite.3pm
.\" Automatically generated by Pod::Man 4.11 (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 "Lite 3"
.TH Lite 3 "2021-04-04" "perl v5.26.3" "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::CIDR::Lite \- Perl extension for merging IPv4 or IPv6 CIDR addresses
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::CIDR::Lite;
\&
\&  my $cidr = Net::CIDR::Lite\->new;
\&  $cidr\->add($cidr_address);
\&  @cidr_list = $cidr\->list;
\&  @ip_ranges = $cidr\->list_range;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Faster alternative to Net::CIDR when merging a large number
of \s-1CIDR\s0 address ranges. Works for IPv4 and IPv6 addresses.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBnew()\fR" 4
.IX Item "new()"
.Vb 2
\& $cidr = Net::CIDR::Lite\->new
\& $cidr = Net::CIDR::Lite\->new(@args)
.Ve
.Sp
Creates an object to represent a list of \s-1CIDR\s0 address ranges.
No particular format is set yet; once an add method is called
with a IPv4 or IPv6 format, only that format may be added for this
cidr object. Any arguments supplied are passed to \fBadd_any()\fR (see below).
.IP "\fBadd()\fR" 4
.IX Item "add()"
.Vb 1
\& $cidr\->add($cidr_address)
.Ve
.Sp
Adds a \s-1CIDR\s0 address range to the list.
.IP "\fBadd_range()\fR" 4
.IX Item "add_range()"
.Vb 1
\& $cidr\->add_range($ip_range)
.Ve
.Sp
Adds a hyphenated \s-1IP\s0 address range to the list.
.IP "\fBadd_cidr()\fR" 4
.IX Item "add_cidr()"
.Vb 1
\& $cidr1\->add_cidr($cidr2)
.Ve
.Sp
Adds address ranges from one object to another object.
.IP "\fBadd_ip()\fR" 4
.IX Item "add_ip()"
.Vb 1
\& $cidr\->add_ip($ip_address)
.Ve
.Sp
Adds a single \s-1IP\s0 address to the list.
.IP "\fBadd_any()\fR" 4
.IX Item "add_any()"
.Vb 1
\& $cidr\->add_any($cidr_or_range_or_address);
.Ve
.Sp
Determines format of range or single ip address and calls \fBadd()\fR,
\&\fBadd_range()\fR, \fBadd_cidr()\fR, or \fBadd_ip()\fR as appropriate.
.ie n .IP "$cidr\->\fBclean()\fR" 4
.el .IP "\f(CW$cidr\fR\->\fBclean()\fR" 4
.IX Item "$cidr->clean()"
.Vb 1
\& $cidr\->clean;
.Ve
.Sp
If you are going to call the list method more than once on the
same data, then for optimal performance, you can call this to
purge null nodes in overlapping ranges from the list. Boundary
nodes in contiguous ranges are automatically purged during \fBadd()\fR.
Only useful when ranges overlap or when contiguous ranges are added
out of order.
.ie n .IP "$cidr\->\fBlist()\fR" 4
.el .IP "\f(CW$cidr\fR\->\fBlist()\fR" 4
.IX Item "$cidr->list()"
.Vb 2
\& @cidr_list = $cidr\->list;
\& $list_ref  = $cidr\->list;
.Ve
.Sp
Returns a list of the merged \s-1CIDR\s0 addresses. Returns an array if called
in list context, an array reference if not.
.ie n .IP "$cidr\->\fBlist_range()\fR" 4
.el .IP "\f(CW$cidr\fR\->\fBlist_range()\fR" 4
.IX Item "$cidr->list_range()"
.Vb 2
\& @cidr_list = $cidr\->list_range;
\& $list_ref  = $cidr\->list_range;
.Ve
.Sp
Returns a list of the merged addresses, but in hyphenated range
format. Returns an array if called in list context, an array reference
if not.
.ie n .IP "$cidr\->\fBlist_short_range()\fR" 4
.el .IP "\f(CW$cidr\fR\->\fBlist_short_range()\fR" 4
.IX Item "$cidr->list_short_range()"
.Vb 2
\& @cidr_list = $cidr\->list_short_range;
\& $list_ref  = $cidr\->list_short_range;
.Ve
.Sp
Returns a list of the C subnet merged addresses, in short hyphenated range
format. Returns an array if called in list context, an array reference
if not.
.Sp
Example:
.Sp
.Vb 6
\&        1.1.1.1\-2
\&        1.1.1.5\-7
\&        1.1.1.254\-255
\&        1.1.2.0\-2
\&        1.1.3.5
\&        1.1.3.7
.Ve
.ie n .IP "$cidr\->\fBfind()\fR" 4
.el .IP "\f(CW$cidr\fR\->\fBfind()\fR" 4
.IX Item "$cidr->find()"
.Vb 1
\& $found = $cidr\->find($ip);
.Ve
.Sp
Returns true if the ip address is found in the \s-1CIDR\s0 range. False if not.
Not extremely efficient, is O(n*log(n)) to sort the ranges in the
cidr object O(n) to search through the ranges in the cidr object.
The sort is cached on the first call and used in subsequent calls,
but if more addresses are added to the cidr object, \fBprep_find()\fR must
be called on the cidr object.
.ie n .IP "$cidr\->\fBbin_find()\fR" 4
.el .IP "\f(CW$cidr\fR\->\fBbin_find()\fR" 4
.IX Item "$cidr->bin_find()"
Same as \fBfind()\fR, but forces a binary search. See also prep_find.
.ie n .IP "$cidr\->\fBprep_find()\fR" 4
.el .IP "\f(CW$cidr\fR\->\fBprep_find()\fR" 4
.IX Item "$cidr->prep_find()"
.Vb 1
\& $cidr\->prep_find($num);
.Ve
.Sp
Caches the result of sorting the ip addresses. Implicitly called on the first
find call, but must be explicitly called if more addresses are added to
the cidr object. \fBfind()\fR will do a binary search if the number of ranges is
greater than or equal to \f(CW$num\fR (default 20);
.ie n .IP "$cidr\->\fBspanner()\fR" 4
.el .IP "\f(CW$cidr\fR\->\fBspanner()\fR" 4
.IX Item "$cidr->spanner()"
.Vb 1
\& $spanner = $cidr1\->spanner($label1, $cidr2, $label2, ...);
.Ve
.Sp
Creates a spanner object to find out if multiple ip addresses are within
multiple labeled address ranges. May also be called as (with or without
any arguments):
.Sp
.Vb 1
\& Net::CIDR::Lite::Span\->new($cidr1, $label1, $cidr2, $label2, ...);
.Ve
.ie n .IP "$spanner\->\fBadd()\fR" 4
.el .IP "\f(CW$spanner\fR\->\fBadd()\fR" 4
.IX Item "$spanner->add()"
.Vb 1
\& $spanner\->add($cidr1, $label1, $cidr2, $label2,...);
.Ve
.Sp
Adds labeled address ranges to the spanner object. The 'address range' may
be a Net::CIDR::Lite object, a single \s-1CIDR\s0 address range, a single
hyphenated \s-1IP\s0 address range, or a single \s-1IP\s0 address.
.ie n .IP "$spanner\->\fBfind()\fR" 4
.el .IP "\f(CW$spanner\fR\->\fBfind()\fR" 4
.IX Item "$spanner->find()"
.Vb 1
\& $href = $spanner\->find(@ip_addresses);
.Ve
.Sp
Look up which range(s) ip addresses are in, and return a lookup table
of the results, with the keys being the ip addresses, and the value a
hash reference of which address ranges the ip address is in.
.ie n .IP "$spanner\->\fBbin_find()\fR" 4
.el .IP "\f(CW$spanner\fR\->\fBbin_find()\fR" 4
.IX Item "$spanner->bin_find()"
Same as \fBfind()\fR, but forces a binary search. See also prep_find.
.ie n .IP "$spanner\->\fBprep_find()\fR" 4
.el .IP "\f(CW$spanner\fR\->\fBprep_find()\fR" 4
.IX Item "$spanner->prep_find()"
.Vb 1
\& $spanner\->prep_find($num);
.Ve
.Sp
Called implicitly the first time \f(CW$spanner\fR\->find(..) is called, must be called
again if more cidr objects are added to the spanner object. Will do a
binary search if ratio of the number of ip addresses to the number of ranges
is less than \f(CW$num\fR percent (default 4).
.ie n .IP "$spanner\->\fBclean()\fR" 4
.el .IP "\f(CW$spanner\fR\->\fBclean()\fR" 4
.IX Item "$spanner->clean()"
.Vb 1
\& $clean_address = $spanner\->clean($ip_address);
.Ve
.Sp
Validates and returns a cleaned up version of an ip address (which is
what you will find as the key in the result from the \f(CW$spanner\fR\->find(..),
not necessarily what the original argument looked like). E.g. removes
unnecessary leading zeros, removes null blocks from IPv6
addresses, etc.
.SH "CAVEATS"
.IX Header "CAVEATS"
Garbage in/garbage out. This module does do validation, but maybe
not enough to suit your needs.
.SH "AUTHOR"
.IX Header "AUTHOR"
Douglas Wilson, <dougw@cpan.org>
w/numerous hints and ideas borrowed from Tye McQueen.
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Stig Palmquist <stig@stig.io>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 2
\& This module is free software; you can redistribute it and/or
\& modify it under the same terms as Perl itself.
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::CIDR.
F1l3 Manager
