cidr v4 v6 merge Files

version:    1.0
website:    http:/info.fwsentry.org/projects/cidr-merge/
contact:    dbw <dbw@fwsentry.org>
license:    BSD revised (see http://www.opensource.org/licenses/bsd-license.php)


USAGE / INSTALLATION
====================

CIDR merge is 3 clause BSD-licensed, so you can use source code, in whole or part, 
and integrate it into your project or application. 

CIDR v4 v6 merge is a set highly efficient IP Address merge functions written in C.

You only need to include the cidr-v4-v6-merge.h file in your source code. If your 
project already incorporates D-List, you will have 2 extra functions available.

CIDR merge should be installed as a shared library, or can compiled directly into
your project. 

PACKAGE CONTENTS
================

-- src/dlist				source for D-List (dlist.c, dlist.h etc)
-- src						source code for cidr merge

There are 2 standard CIDR merge functions available in the package, and 2 more if
you compile your project with D-List.

The package has autoconf and automake files. To simplify build and usage.


API'S & DOCUMENTATION
=====================

There are 2 basic CIDR merge functions provided for callers to use. 

ipv4_addr_cidr_notation_t *merge_ipv4_cidr_array_list(const ipv4_addr_cidr_notation_t *input_list)

From the provided input list of IPv4/CIDR addresses, stored in an array of 
ipv4_addr_cidr_notation_t records, create a merged list by reducing
overlapping and concentric blocks, reducing the list to minimum needed to
to cover the original list.

	For example, input of 	"192.168.1.0" "29"
							"192.168.1.8" "29"
							"101.34.35.3" "24"
							"" ""
	will yield a result of	"101.34.35.3" "24"
							"192.168.1.0" "28"
							"" ""
The returned list will be sorted as well as merged. This function only
operates on IPv4 addresses. To process an equivalent array list For IPv6 
addresses please use the function merge_ipv6_cidr_array_list()

Addresses in the input list may be slightly malformed, for example in FWS
addresses are stored with a mask, but the address is the actual address that
was recorded, not the first address of the mask span. This function will
sanitize the ip addresses for use in interfaces that will not accept such
addresses. (as it stands most everything does, but this is a precaution)
	(e.g. 201.34.98.84/24 would get cleansed into 201.34.98.0/24)
No other code in the FWS ecosystem cleanses addresses, nor do they care,
just like all firewalls and inet code, it is not relevant when masked.

input_list		an array of ipv4_addr_cidr_notation_t, that describe the
				addr/cidr list to be merged. The list must be terminated 
				by an empty element at the end of the array 
				(ip_address == '\0' && cidr == '\0')
			
returns		Pointer	to a new array of ipv4_addr_cidr_notation_t, that 
					describes the addr/cidr list created by the merge
					operations. The list is terminated by an empty
					element at the end of the array 
					(ip_address == '\0' && cidr == '\0').
					The caller is responsible for proper disposal of the
					storage used for the return list.
			NULL	An error occurred. An error message will have been 
					output to stderr.												


and the function

ipv6_addr_cidr_notation_t *merge_ipv6_cidr_array_list(const ipv6_addr_cidr_notation_t *input_list)

From the provided input list of IPv6/CIDR addresses, stored in an array of 
ipv6_addr_cidr_notation_t records, create a merged list by reducing
overlapping and concentric blocks, reducing the list to minimum needed to
to cover the original list.

	For example, input of	"23a9:c53f:3abf:d6be:790a:1d79:ee90:26db" "128"
							"5f02:ead3:d11e:9747:76b6:6fca:be9:d592" "64"
							"5f02:ead3:d11e:9747:76b6:6fca:bf9:d592" "128"
							"5f02:ead3:d11e:9747:76b6:6fda:be9:d592" "128"
							"5f02:ead3:d11e:9747:76b6:6dca:be9:d592" "128"
							"5f02:ead3:d11e:9747:76b6:dfca:be9:d592" "128"
							"5f02:ead3:d11e:9748:76b6:6fca:be9:d592" "64"
							"5f02:ead3:d11e:9749:76b6:6fca:be9:d592" "64"
							"3af5:cd1c:39a1:d610:6aaf:8f42:1216:3a9" "128"
							"3ecb:9078:a8fc:5fd9:f93d:95d1:4b90:7cd2" "128"
							"" ""

	will yield a result of	"23a9:c53f:3abf:d6be:790a:1d79:ee90:26db" "128"
							"3af5:cd1c:39a1:d610:6aaf:8f42:1216:3a9" "128"
							"3ecb:9078:a8fc:5fd9:f93d:95d1:4b90:7cd2" "128"
							"5f02:ead3:d11e:9747:76b6:6dca:be9:d592" "128"
							"5f02:ead3:d11e:9747:0:0:0:0" "64"
							"5f02:ead3:d11e:9748:0:0:0:0" "63"
							"" ""
The returned list will be sorted as well as merged. This function only
operates on IPv6 addresses. To process an equivalent array list For IPv4 
addresses please use the function merge_ipv4_cidr_array_list()

Addresses in the input list may be slightly malformed, for example in FWS
addresses are stored with a mask, but the address is the actual address that
was recorded, not the first address of the mask span. This function will
sanitize the ip addresses for use in interfaces that will not accept such
addresses. (as it stands most everything does, but this is a precaution)
	(e.g. efcc:d75a:ddc0:d020:dc21:51fb:2e3f:8b48/56 would get cleansed into
		efcc:d75a:ddc0:d000:0:0:0:0/56)
No other code in the FWS ecosystem cleanses addresses, nor do they care,
just like all firewalls and inet code, it is not relevant when masked.

input_list		an array of ipv6_addr_cidr_notation_t, that describe the
				addr/CIDR list to be merged. The list must be terminated 
				by an empty element at the end of the array 
				(ip_address == '\0' && cidr == '\0')
			
returns		Pointer	to a new array of ipv4_addr_cidr_notation_t, that 
					describes the addr/CIDR list created by the merge
					operations. The list is terminated by an empty
					element at the end of the array 
					(ip_address == '\0' && cidr == '\0').
					The caller is responsible for proper disposal of the
					storage used for the return list.
			NULL	An error occurred. An error message will have been 
					output to stderr.