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.