Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::Works::Network(3)User Contributed Perl DocumentatioNet::Works::Network(3)

NAME
       Net::Works::Network - An	object representing a single IP	address	(4 or
       6) subnet

VERSION
       version 0.22

SYNOPSIS
	 use Net::Works::Network;

	 my $network = Net::Works::Network->new_from_string( string => '192.0.2.0/24' );
	 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 .	"\n"; }

	 my $network_32	= Net::Works::Network->new_from_string(	string => '192.0.2.4/32' );
	 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 => '2001:db8::/48' );

	 my @subnets = Net::Works::Network->range_as_subnets( '192.0.2.1', '192.0.2.32'	);
	 print $_->as_string, "\n" 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

DESCRIPTION
       Objects of this class represent an IP address network. It can handle
       both IPv4 and IPv6 subnets. It provides various methods for getting
       information about the subnet.

       For IPv6, it uses 128-bit integers (via Math::Int128) to	represent the
       numeric value of	an address as needed.

METHODS
       This class provides the following methods:

   Net::Works::Network->new_from_string( ... )
       This method takes a "string" parameter and an optional "version"
       parameter. The "string" parameter should	be a string representation of
       an IP address subnet, e.g., "192.0.2.0/24".

	   my $network = Net::Works::Network->new_from_string(
	       string => '192.0.2.0/24'
	   );
	   print $network->as_string; #	192.0.2.0/24

       The "version" parameter should be either	4 or 6,	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.

       If you pass an IPv4 network but specify the version as 6	then we	will
       add 96 to the netmask.

	   my $network = Net::Works::Network->new_from_string(
	       string  => '192.0.2.0/24',
	       version => 6,
	   );
	   print $network->as_string; #	::192.0.2.0/120

   Net::Works::Network->new_from_integer( ... )
       This method takes an "integer" parameter, "prefix_length" parameter,
       and an optional "version" parameter. The	"integer" parameter should be
       an integer representation of an IP within the subnet. The
       "prefix_length" parameter should	be an integer between 0	and 32 for
       IPv4 or 0 and 128 for IPv6. The "version" parameter should be either 4
       or 6.

       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 "prefix_length"
       yourself.

   $network->as_string()
       Returns a string	representation of the network like "192.0.2.0/24" or
       "2001:db8::/48".	The IP address in the string is	the first address
       within the subnet.

   $network->version()
       Returns a 4 or 6	to indicate whether this is an IPv4 or IPv6 network.

   $network->prefix_length()
       Returns the length of the netmask as an integer.

   $network->bits()
       Returns the number of bit of an address in the network, which is	either
       32 (IPv4) or 128	(IPv6).

   $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.

   $network->first()
       Returns the first IP in the network as an Net::Works::Address object.

   $network->first_as_integer()
       Returns the first IP in the network as an integer. This may be a
       Math::Int128 object.

   $network->last()
       Returns the last	IP in the network as an	Net::Works::Address object.

   $network->last_as_integer()
       Returns the last	IP in the network as an	integer. This may be a
       Math::Int128 object.

   $network->is_single_address()
       Returns true if the network contains just a single address (/32 in IPv4
       or /128 in IPv6).

   $network->iterator()
       This returns an anonymous sub that returns one IP address in the	range
       each time it's called.

       For single address subnets (/32 or /128), this returns a	single
       address.

       When it has exhausted all the addresses in the network, it returns
       "undef"

   $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.

   $network->split()
       This returns a list of two new network objects representing the
       original	network	split into two halves. For example, splitting
       "192.0.2.0/24" returns "192.0.2.0/25" and "192.0.2.128/25".

       If the original networks	is a single address network (a /32 in IPv4 or
       /128 in IPv6) then this method returns an empty list.

   Net::Works::Network->range_as_subnets( $first_address, $last_address,
       $version	)
       Given two IP addresses as strings, this method breaks the range up into
       the largest subnets that	include	all the	IP addresses in	the range
       (including the two passed to this method).

       This method also	excludes any reserved subnets such as the RFC1918
       <http://tools.ietf.org/html/rfc1918> IPv4 private address space,
       RFC5735 <http://tools.ietf.org/html/rfc5735> IPv4 special-use address
       space and RFC5156 <http://tools.ietf.org/html/rfc5156> IPv6 special-use
       address space.

       An overview can be found	at the IANA IPv4
       <http://www.iana.org/assignments/iana-ipv4-special-registry/iana-
       ipv4-special-registry.xhtml> and	IPv6
       <http://www.iana.org/assignments/iana-ipv6-special-registry/iana-
       ipv6-special-registry.xhtml> special-purpose address registries.

       The networks currently treated as reserved are:

	   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

       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.

       When given an IPv6 range	that includes the first	32 bits	of addresses
       (the IPv4 space), both IPv4 and IPv6 reserved networks are removed from
       the range.

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 IP address in	their networks,	and then by prefix
       length if they have the same starting address.

       It also overloads stringification to call the "$network->as_string()"
       method.

DEPRECATED METHODS AND ATTRIBUTES
       Prior to	version	0.17, this package referred to the prefix length as
       mask length. The	"mask_length()"	and "max_mask_length()"	methods	are
       deprecated, and will probably start warning in a	future release.	In
       addition, passing a "mask_length" key to	the "new_from_integer()"
       constructor has been replaced by	"prefix_length". The old key will
       continue	to work	for now	but may	start warning in a future release.

AUTHORS
       o   Dave	Rolsky <autarch@urth.org>

       o   Greg	Oschwald <oschwald@cpan.org>

       o   Olaf	Alders <oalders@wundercounter.com>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2016 by MaxMind, Inc.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2016-08-21		Net::Works::Network(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | OVERLOADING | DEPRECATED METHODS AND ATTRIBUTES | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Works::Network&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help