GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  NET::CIDR::SET (3)

.ds Aq ’

NAME

Net::CIDR::Set - Manipulate sets of IP addresses

CONTENTS

VERSION

This document describes Net::CIDR::Set version 0.13

SYNOPSIS



  use Net::CIDR::Set;

  my $priv = Net::CIDR::Set->new( 10.0.0.0/8, 172.16.0.0/12,
    192.168.0.0/16 );
  for my $ip ( @addr ) {
    if ( $priv->contains( $ip ) ) {
      print "$ip is private\n";
    }
  }



DESCRIPTION

Net::CIDR::Set represents sets of IP addresses and allows standard set operations (union, intersection, membership test etc) to be performed on them.

In spite of the name it can work with sets consisting of arbitrary ranges of IP addresses - not just CIDR blocks.

Both IPv4 and IPv6 addresses are handled - but they may not be mixed in the same set. You may explicitly set the personality of a set:



  my $ip4set = Net::CIDR::Set->new({ type => ipv4 }, 10.0.0.0/8);



Normally this isn’t necessary - the set will guess its personality from the first data that is added to it.

INTERFACE

CWnew

Create a new Net::CIDR::Set. All arguments are optional. May be passed a list of list of IP addresses or ranges which, if present, will be passed to add.

The first argument may be a hash reference which will be inspected for named options. Currently the only option that may be passed is type which should be ’ipv4’, ’ipv6’ or the name of a coder class. See Net::CIDR::Set::IPv4 and Net::CIDR::Set::IPv6 for examples of coder classes.

CWinvert

Invert (negate, complement) a set in-place.



  my $set = Net::CIDR::Set->new;
  $set->invert;



CWcopy

Make a deep copy of a set.



  my $set2 = $set->copy;



CWadd

Add a number of addresses or ranges to a set.



  $set->add(
    10.0.0.0/8,
    192.168.0.32-192.168.0.63,
    127.0.0.1
  );



It is legal to add ranges that overlap with each other and/or with the ranges already in the set. Overlapping ranges are merged.

CWremove

Remove a number of addresses or ranges from a set.



  $set->remove(
    8.8.0.0/16,
    158.152.1.58
  );



There is no requirement that the addresses being removed be members of the set.

CWmerge

Merge the contents of other sets into this set.



  $set = Net::CIDR::Set->new;
  $set->merge($s1, $s2);



CWcontains

A synonmym for contains_all.

CWcontains_all

Return true if the set contains all of the supplied addresses. Given this set:



  my $set = Net::CIDR::Set->new(244.188.12.0/8);



this condition is true:



  if ( $set->contains_all(244.188.12.128/3) ) {
    # ...
  }



while this condition is false:



  if ( $set->contains_all(244.188.12.0/12) ) {
    # ...
  }



CWcontains_any

Return true if there is any overlap between the supplied addresses/ranges and the contents of the set.

CWcomplement

Return a new set that is the complement of this set.



  my $inv = $set->complement;



CWunion

Return a new set that is the union of a number of sets. This is equivalent to a logical OR between sets.



  my $everything = $east->union($west);



CWintersection

Return a new set that is the intersection of a number of sets. This is equivalent to a logical AND between sets.



  my $overlap = $north->intersection($south);



CWxor

Return a new set that is the exclusive-or of existing sets.



  my $xset = $this->xor($that);



The resulting set will contain all addresses that are members of one set but not the other.

CWdiff

Return a new set containing all the addresses that are present in this set but not another.



  my $diff = $this->diff($that);



CWis_empty

Return a true value if the set is empty.



  if ( $set->is_empty ) {
    print "Nothing there!\n";
  }



CWsuperset

Return true if this set is a superset of the supplied set.

CWsubset

Return true if this set is a subset of the supplied set.

CWequals

Return true if this set is identical to another set.



  if ( $set->equals($foo) ) {
    print "We have the same addresses.\n";
  }



Retrieving Set Contents

The following methods allow the contents of a set to be retrieved in various representations. Each of the following methods accepts an optional numeric argument that controls the formatting of the returned addresses. It may take one of the following values:
0 Format each range of addresses as compactly as possible. If the range contains only a single address format it as such. If it can be represented as a single CIDR block use CIDR representation (<ip>/<mask>) otherwise format it as an arbitrary range (<start>-<end>).
1 Always format as either a CIDR block or an arbitrary range even if the range is just a single address.
2 Always use arbitrary range format (<start>-<end>) even if the range is a single address or a legal CIDR block.
Here’s an example of the different formatting options:



  my $set = Net::CIDR::Set->new( 127.0.0.1, 192.168.37.0/24,
    10.0.0.11-10.0.0.17 );

  for my $fmt ( 0 .. 2 ) {
    print "Using format $fmt:\n";
    print "  $_\n" for $set->as_range_array( $fmt );
  }



And here’s the output from that code:



  Using format 0:
    10.0.0.11-10.0.0.17
    127.0.0.1
    192.168.37.0/24
  Using format 1:
    10.0.0.11-10.0.0.17
    127.0.0.1/32
    192.168.37.0/24
  Using format 2:
    10.0.0.11-10.0.0.17
    127.0.0.1-127.0.0.1
    192.168.37.0-192.168.37.255



Note that this option never affects the addresses that are returned; only how they are formatted.

For most purposes the formatting argument can be omitted; it’s default value is 0 which provides the most general formatting.

CWiterate_addresses

Return an iterator (a closure) that will return each of the addresses in the set in ascending order. This code



  my $set = Net::CIDR::Set->new(192.168.37.0/24);
  my $iter = $set->iterate_addresses;
  while ( my $ip = $iter->() ) {
    print "Got $ip\n";
  }



outputs 256 distinct addresses from 192.168.37.0 to 192.168.27.255.

CWiterate_cidr

Return an iterator (a closure) that will return each of the CIDR blocks in the set in ascending order. This code



  my $set = Net::CIDR::Set->new(192.168.37.9-192.168.37.134);
  my $iter = $set->iterate_cidr;
  while ( my $cidr = $iter->() ) {
    print "Got $cidr\n";
  }



outputs



  Got 192.168.37.9
  Got 192.168.37.10/31
  Got 192.168.37.12/30
  Got 192.168.37.16/28
  Got 192.168.37.32/27
  Got 192.168.37.64/26
  Got 192.168.37.128/30
  Got 192.168.37.132/31
  Got 192.168.37.134



This is the most compact CIDR representation of the set because its limits don’t fall on convenient CIDR boundaries.

CWiterate_ranges

Return an iterator (a closure) that will return each of the ranges in the set in ascending order. This code



  my $set = Net::CIDR::Set->new(
    192.168.37.9-192.168.37.134,
    127.0.0.1,
    10.0.0.0/8
  );
  my $iter = $set->iterate_ranges;
  while ( my $range = $iter->() ) {
    print "Got $range\n";
  }



outputs



  Got 10.0.0.0/8
  Got 127.0.0.1
  Got 192.168.37.9-192.168.37.134



CWas_array

Convenience method that gathers all of the output from one of the iterators above into an array.



  my @ranges = $set->as_array( $set->iterate_ranges );



Normally you will use one of as_address_array, as_cidr_array or as_range_array instead.

CWas_address_array

Return an array containing all of the distinct addresses in a set. Note that this may very easily create a very large array. At the time of writing it is, for example, unlikely that you have enough memory for an array containing all of the possible IPv6 addresses...

CWas_cidr_array

Return an array containing all of the distinct CIDR blocks in a set.

CWas_range_array

Return an array containing all of the ranges in a set.

CWas_string

Return a compact string representation of a set.

AUTHOR

Andy Armstrong <andy.armstrong@messagesystems.com>

CREDITS

The encode and decode routines were stolen en masse from Douglas Wilson’s Net::CIDR::Lite.

LICENCE AND COPYRIGHT

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

Copyright (c) 2009, Message Systems, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:



    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in
      the documentation and/or other materials provided with the
      distribution.
    * Neither the name Message Systems, Inc. nor the names of its
      contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.



THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NET::CIDR::SET (3) 2016-03-18

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.