The functions in this section allow you to work with IP maps, which map IP addresses to integer values. IP maps work seamlessly with both IPv4 and IPv6 addresses. Every IP address is mapped to some value; each IP map has a default value that will be used for any addresses that aren’t explicitly mapped to something else. (This is the map equivalent of an address not appearing in a set; “removing” an address from a map is the same as setting it to the map’s default value.)
Note
With this definition of a map, an IP set is just an IP map that is restricted to the values 0 and 1. This is actually how sets are implemented internally.
Note
Before using any of the IP map functions, you must initialize this library using ipset_init_library().
Maps IP addresses to integer values. The fields of this struct are opaque; you should only use the public library functions to access the contents of the map.
There are two ways that you can work with IP maps. The first is that you can allocate the space for the ip_map instance yourself — for instance, directly on the stack. The second is to let the IP map library allocate the space for you. Your choice determines which of the following functions you will use to create and free your IP maps.
Creates a new IP map. The map will use default_value as the default value for any addresses that aren’t explicitly mapped to something else.
The init variant should be used if you’ve allocated space for the map yourself. The new variant should be used if you want the library to allocate the space for you. (The new variant never returns NULL; it will abort the program if the allocation fails.) In both cases, the map starts off empty.
Finalizes an IP map. The done variant must be used if you created the map using ipmap_init(); the free variant must be used if you created the map using ipmap_new().
We provide a variety of functions for adding and removing addresses from an IP map.
Updates map so that ip is mapped to value.
Updates map so that all of the addresses in a CIDR network are mapped to value. ip is one of the addresses in the CIDR network; cidr_prefix is the number of bits in the network portion of each IP address in the CIDR network, as defined in RFC 4632. cidr_prefix must be in the range 0-32 (inclusive) if ip is an IPv4 address, and in the range 0-128 (inclusive) if it’s an IPv6 address.
Note
In all of the _network functions, if you want to strictly adhere to RFC 4632, ip can only have non-zero bits in its cidr_prefix uppermost bits. All of the lower-order bits (i.e., in the host portion of the IP address) must be map to 0. We do not enforce this, however.
Returns the value that ip is mapped to in map.
Returns whether map is empty. A map is considered empty is every IP address is mapped to the default value.
The functions in this section allow you to store IP maps on disk, and reload them into another program at a later time. You don’t have to know the details of the file format to be able to use these functions; we guarantee that maps written with previous versions of the library will be readable by later versions of the library (but not vice versa). And we guarantee that the file format is platform-independent; maps written on any machine will be readable on any other machine.
(That said, if you do want to know the details of the file format, that’s documented in another section.)
Saves an IP map into stream. You’re responsible for opening stream before calling this function, and for closing stream afterwards. If there are any errors writing the map, we return -1 and fill in a libcork error condition.
Saves an IP map into a libcork stream consumer. If there are any errors writing the map, we return -1 and fill in a libcork error condition.
Loads an IP map from stream. You’re responsible for opening stream before calling this function, and for closing stream afterwards. If there are any errors reading the map, we return NULL and fill in a libcork error condition. You must use ipmap_free() to free the map when you’re done with it.