libptv - arbitrary size prefix matching by intervals .fl

.. .fl

..

..

.. .Cs #include <ptv.h> .Ce libptv provides a set of functions to create and maintain collections of unlabelled prefix tables for arbitrary size unsigned big-endian integers. IPV6 addresses are modeled as 16 byte unsigned big-endian integers. Unlabelled prefixes are treated as intervals. Adjoining intervals are merged. An address matches the set of prefixes if it is contained on one of the intervals. Information on which prefix matches a particular address is not provided by the library. See iv (3) for longest prefix matching on arbitary size unsigned big-endian integers.

ptv provides functions that apply set operations on collections of prefix tables. These functions support questions like: does prefix table P match address A; does the union of prefix tables P and Q match address A; what set of addresses are matched by the intersection of prefix tables P and Q. .Ss "TYPES" .Ss " Ptv_t" Prefix table handle containing these public members: .Ss " Ptvcount_t entries" The number of prefixes in the table. .Ss " int size" The address size in bytes. .Ss " unsigned char* r[PTV_REGISTERS]" PTV_REGISTERS temporary address registers for address/prefix computations. PTV_REGISTERS is at least 6. .Ss " Ptvprefix_t" Prefix handle containing these public members: .Ss " unsigned char* min" The minimum address in the prefix interval. .Ss " unsigned char* max" The maximum address in the prefix interval. .Ss " union { long number; void* pointer; } data" User defined data associated with the prefix. .Ss " Ptvaddr_t" .L "unsigned char*" pointer to the significant prefix bytes in big-endian order. .Ss " Ptvcount_t" Unsigned integral type for counting. .Ss "DISCIPLINE" The prefix table discipline specifies the API version and an optional user error message callback. .Cs typedef int (*Error_f)(void* meth, void* disc, int level, const char* format, ...); typedef struct Ptvdisc_s { uint32_t version; Error_f errorf; } Ptvdisc_t; .Ce .Ss "FUNCTIONS" .Ss " void ptvinit(Ptvdisc_t* disc)" Initializes the discipline disc with the implementation version and default values for all other members. .Ss " Ptv_t* ptvopen(Ptvdisc_t* disc, int size)" This creates a new prefix table handle. disc is a discipline structure. size is the address size in bytes. ptvopen() returns the new handle or 0 on failure. .Ss " int ptvclose(Ptv_t* ptv)" This closes the prefix table handle ptv. It returns -1 on failure and 0 on success. .Ss " Ptvprefix_t* ptvinsert(Ptv_t* ptv, unsigned char* min, unsigned char* max)" Inserts the prefix with minimum address min and maximum address max in the table ptv. A pointer to the prefix is returned on success, 0 on failure. On success the prefix data member may be modified; this value is retained until the prefix is deleted or the table is closed. In particular, it may be recovered by ptvmatch(), described below. .Ss " int ptvdelete(Ptv_t* ptv, unsigned char* min, unsigned char* max)" Deletes the prefix with minimum address min and maximum address max from the table ptv. 0 is returned if the prefix was found and deleted, otherwise -1 is returned. .Ss " Ptvprefix_t* ptvmatch(Ptv_t* ptv, unsigned char* addr)" Returns a pointer to the prefix for the longest prefix match of addr on the table ptv. 0 is returned if there is no match. .Ss " unsigned char* ptvmin(int size, unsigned char* buf, unsigned char* addr, int bits)" Returns a pointer to the minimal address in buf of size bytes for the prefix addr limited to bits bits. .Ss " unsigned char* ptvmax(int size, unsigned char* buf, unsigned char* addr, int bits)" Returns a pointer to the maximal address in buf of size bytes for the prefix addr limited to bits bits.

libptv uses the CDT library for container data types and fv(3) for manipulating arbitrary size unsigned big-endian integers. iv(3), cdt(3), fv(3).

Glenn Fowler <gsf@research.att.com>