loc_network

Name

loc_network_new, loc_network_new_from_string, loc_network_ref, loc_network_unref, loc_network_str, loc_network_address_family, loc_network_prefix - Create networks

Synopsis

#include <libloc/network.h>

struct loc_network;

int loc_network_new(struct loc_ctx* ctx, struct loc_network** network,
        struct in6_addr* first_address, unsigned int prefix);

int loc_network_new_from_string(struct loc_ctx* ctx,
        struct loc_network** network, const char* string);

struct loc_network* loc_network_ref(struct loc_network* network);

struct loc_network* loc_network_unref(struct loc_network* network);

const char* loc_network_str(struct loc_network* network);

int loc_network_address_family(struct loc_network* network);

unsigned int loc_network_prefix(struct loc_network* network);

Description

A network is a range of IP addresses, like 192.0.2.0/24 or 2001:db8::/32. Networks are being returned by loc_database_lookup(3) and by enumerators, and they can be created by the caller to work with them.

libloc stores all addresses as IPv6 addresses. IPv4 addresses are being stored as IPv4-mapped IPv6 addresses (::ffff:192.0.2.0), but the functions below return them as IPv4.

loc_network_new() creates a network which starts at first_address and has prefix bits. If first_address is an IPv4-mapped address, prefix is the length of the IPv4 prefix (0 to 32). Any bits of first_address after the prefix are being ignored.

loc_network_new_from_string() creates a network from a string like 192.0.2.0/24 or 2001:db8::/32. A single address without a prefix is a network with only that address in it.

loc_network_str() returns the network as a string, like 192.0.2.0/24.

loc_network_address_family() returns AF_INET or AF_INET6.

loc_network_prefix() returns the length of the prefix, which for IPv4 networks is between 0 and 32.

The string that loc_network_str() returns belongs to the network and remains valid for as long as the network does. The addresses of a network are described in loc_network_get_first_address(3).

Return Value

loc_network_new() and loc_network_new_from_string() return zero on success. On error, a negative error number (see errno(3)) is returned, for example -EINVAL if the address or the prefix are not valid. errno itself is not being set.

loc_network_str() returns NULL if the string could not be created.

loc_network_ref() returns the network. loc_network_unref() returns NULL once the last reference has been released and the network has been freed, or the network otherwise.

Example

struct loc_network* network = NULL;

if (loc_network_new_from_string(ctx, &network, "2001:db8::/32") == 0) {
        printf("%s has a prefix of %u bits\n", loc_network_str(network),
                loc_network_prefix(network));

        loc_network_unref(network);
}

Authors

Michael Tremer

loc_network_new(3)