Network-Related Functions

Network-Related Functions — Various functions for managing network addresses and interfaces

Synopsis


#include <monitor/monitor.h>


            mon_address;
mon_address* mon_addr_new                   (struct sockaddr *addr,
                                             unsigned int alen,
                                             int priority,
                                             int weight);
unsigned int mon_addr_len                   (mon_address *addr);
            mon_addrlist;
mon_addrlist* mon_addrlist_new              (void);
void        mon_addrlist_done               (mon_addrlist *list);
void        mon_addrlist_ref                (mon_addrlist *list);
int         mon_addrlist_add                (mon_addrlist *list,
                                             struct sockaddr *addr,
                                             unsigned int alen,
                                             int priority,
                                             int weight);
int         mon_addrlist_parse              (mon_addrlist *list,
                                             const char *addr,
                                             int def_port);
int         mon_addrlist_next_sd            (mon_addrlist *list,
                                             GList ***iterator,
                                             mon_address **out_addr);
int         mon_addrlist_match              (mon_addrlist *src,
                                             mon_addrlist *dst,
                                             int chk_port);
int         mon_addrlist_equal              (mon_addrlist *src,
                                             mon_addrlist *dst,
                                             int chk_port);
int         mon_addr_to_str                 (char *buf,
                                             size_t buflen,
                                             const struct sockaddr *addr,
                                             unsigned int alen,
                                             int add_port);

enum        mon_ifflags;
#define     MON_IF_PUBLIC
            mon_ipv4_ifaddr;
            mon_ipv6_ifaddr;
            mon_hwaddr;
enum        mon_iftype;
            mon_ifinfo;
int         mon_ifinfo_match                (mon_ifinfo *ifinfo,
                                             mon_addrlist *addr);
            mon_iflist;
void        mon_iflist_init                 (mon_iflist *ifs);
int         mon_iflist_update               (mon_iflist *ifs);
void        mon_iflist_destroy              (mon_iflist *ifs);
int         mon_iflist_check_name           (mon_iflist *ifs,
                                             unsigned int ifindex,
                                             const char *name);
void        mon_iflist_del                  (mon_iflist *ifs,
                                             unsigned int ifindex);
void        mon_iflist_clean                (mon_iflist *ifs);
mon_hwaddr* mon_hwaddr_new                  (unsigned char *hwaddr,
                                             unsigned int addrlen);
void        mon_hwaddr_free                 (mon_hwaddr *addr);
const char* mon_iftype_tostr                (mon_iftype type);

Description

Details

mon_address

typedef struct {
	int			priority;
	int			weight;
	struct sockaddr		addr;
	/* may continue in memory */
} mon_address;

Represents a network address.

int `priority`;	the priority of the address.
int `weight`;	the weight of the address.
struct sockaddr `addr`;	the raw address.

mon_addr_new ()

mon_address* mon_addr_new                   (struct sockaddr *addr,
                                             unsigned int alen,
                                             int priority,
                                             int weight);

Allocate a new mon_address.

`addr` :	pointer to the raw address.
`alen` :	the length of the address.
`priority` :	the priority of the address.
`weight` :	the weight of the address.
Returns :	a mon_address or `NULL` if out of memory.

mon_addr_len ()

unsigned int mon_addr_len                   (mon_address *addr);

Return the length of the raw address contained by a mon_address.

`addr` :	the mon_address.
Returns :	the length of the raw address.

mon_addrlist

typedef struct {
	GList			*addresses;
	unsigned int		cnt;
	int			refcnt;
} mon_addrlist;

A list of network addresses.

GList *`addresses`;	the list of addresses.
unsigned int `cnt`;	number of elements in `addresses`.
int `refcnt`;	the reference count of this mon_addrlist.

mon_addrlist_new ()

mon_addrlist* mon_addrlist_new              (void);

Allocates a new empty mon_addrlist.

Returns : an empty mon_addrlist or NULL if there were not enough memory.

mon_addrlist_done ()

void        mon_addrlist_done               (mon_addrlist *list);

Decrements the reference count of a mon_addrlist. If the reference count reaches zero, the mon_addrlist is deallocated.

list : a mon_addrlist.

mon_addrlist_ref ()

void        mon_addrlist_ref                (mon_addrlist *list);

Increade the reference count of a mon_addrlist.

list : a mon_addrlist.

mon_addrlist_add ()

int         mon_addrlist_add                (mon_addrlist *list,
                                             struct sockaddr *addr,
                                             unsigned int alen,
                                             int priority,
                                             int weight);

Add a new address to a mon_addrlist.

`list` :	a mon_addrlist.
`addr` :	pointer to the raw address.
`alen` :	length of the raw address. If set to 0, the length will be guessed from the address family.
`priority` :	the priority of the address.
`weight` :	the weight of the address.
Returns :	0 if successful or an error code.

mon_addrlist_parse ()

int         mon_addrlist_parse              (mon_addrlist *list,
                                             const char *addr,
                                             int def_port);

Parse an address string and add the resulting address(es) to list. This function accepts hostnames, IPv4 addresses in the dotted-quad notation, or IPv6 addresses between brackets in hexadecimal notation. The function also supports an additional port specification separated from the address part by a colon.

`list` :	a mon_addrlist.
`addr` :	the address string to parse.
`def_port` :	the default port to use if `addr` does not specify one.
Returns :	0 or an error code.

mon_addrlist_next_sd ()

int         mon_addrlist_next_sd            (mon_addrlist *list,
                                             GList ***iterator,
                                             mon_address **out_addr);

Returns a socket descriptor suitable for bind() or connect() for the next address in the list.

`list` :	a mon_addrlist.
`iterator` :	the iterator used to step through the addresses. The pointed value must be `NULL` before the first invocation.
`out_addr` :	the actual mon_address that belongs to the socket descriptor.
Returns :	a socket descriptor or -1 if there were no more addresses to try.

mon_addrlist_match ()

int         mon_addrlist_match              (mon_addrlist *src,
                                             mon_addrlist *dst,
                                             int chk_port);

Test if two mon_addrlist structures have a common element.

`src` :	a mon_addrlist.
`dst` :	a mon_addrlist.
`chk_port` :	if true, the ports must also match; if false, port values are ignored
Returns :	TRUE if the two lists have a common element, FALSE otherwise.

mon_addrlist_equal ()

int         mon_addrlist_equal              (mon_addrlist *src,
                                             mon_addrlist *dst,
                                             int chk_port);

Test if two mon_addrlist structures are equal (the order of mon_address structures does not matter).

`src` :	a mon_addrlist.
`dst` :	a mon_addrlist.
`chk_port` :	if true, the ports must also match; if false, port values are ignored
Returns :	TRUE if the two lists are equal, FALSE otherwise.

mon_addr_to_str ()

int         mon_addr_to_str                 (char *buf,
                                             size_t buflen,
                                             const struct sockaddr *addr,
                                             unsigned int alen,
                                             int add_port);

Convert a network address to a string.

`buf` :	the output buffer.
`buflen` :	the size of the output buffer.
`addr` :	a network address.
`alen` :	the length of the network address.
`add_port` :	if true, the output will also contain the port.
Returns :	0 if successful or an error code.

enum mon_ifflags

typedef enum
{
	/* Interface flags */
	MON_IF_UP		= (1 << 0),
	MON_IF_BROADCAST	= (1 << 1),
	MON_IF_POINTOPOINT	= (1 << 2),
	MON_IF_LOOPBACK		= (1 << 3),
	MON_IF_RUNNING		= (1 << 4),
	MON_IF_PROMISC		= (1 << 5),
	MON_IF_MULTICAST	= (1 << 6),

	/* Private flags */
	MON_IF_SEEN		= (1 << 20),
	MON_IF_FLAGS_CHECKED	= (1 << 21),
	MON_IF_NEW		= (1 << 22)
} mon_ifflags;

Network interface flags.

`MON_IF_UP`	interface is up.
`MON_IF_BROADCAST`	broadcast address valid.
`MON_IF_POINTOPOINT`	the interface is a point-to-point link.
`MON_IF_LOOPBACK`	this is a local loopback interface.
`MON_IF_RUNNING`	resources allocated.
`MON_IF_PROMISC`	receive all packets.
`MON_IF_MULTICAST`	multicast is supported.
`MON_IF_SEEN`	internal flag to mark an interface/address seen.
`MON_IF_FLAGS_CHECKED`	internal flag to mark an interface's flags checked.
`MON_IF_NEW`	internal flag to mark newly discovered interfaces.

MON_IF_PUBLIC

#define MON_IF_PUBLIC ~(MON_IF_SEEN | MON_IF_FLAGS_CHECKED | MON_IF_NEW)

Mask for mon_ifflags to exclude the private flags.

mon_ipv4_ifaddr

typedef struct {
	unsigned int		flags;
	char			*label;
	struct in_addr		localaddr;
	struct in_addr		netmask;
	struct in_addr		dstaddr;
	struct in_addr		broadcast;
} mon_ipv4_ifaddr;

Represents an IPv4 address of a network interface.

unsigned int `flags`;	address flags (used by `mon_iflist_update()`).
char *`label`;	address label (interface alias name).
struct in_addr `localaddr`;	the local address.
struct in_addr `netmask`;	the netmask.
struct in_addr `dstaddr`;	the destination address (for point-to-point links).
struct in_addr `broadcast`;	the broadcast address.

mon_ipv6_ifaddr

typedef struct {
	unsigned int		flags;
	char			*label;
	unsigned int		prefixlen;
	struct in6_addr		localaddr;
	struct in6_addr		dstaddr;
} mon_ipv6_ifaddr;

Represents an IPv6 address of a network interface.

unsigned int `flags`;	address flags (used by `mon_iflist_update()`).
char *`label`;	address label (interface alias name).
unsigned int `prefixlen`;	prefix length of the local address.
struct in6_addr `localaddr`;	the local address.
struct in6_addr `dstaddr`;	the destination address (for point-to-point links).

mon_hwaddr

typedef struct {
	unsigned int		addrlen;
	unsigned char		addr[0];
} mon_hwaddr;

Represents the hardware address of a network interface.

unsigned int `addrlen`;	the length of the address.
unsigned char `addr`[0];	opaque hardware address.

enum mon_iftype

typedef enum
{
	MON_IFTYPE_UNKNOWN,
	MON_IFTYPE_LOOPBACK,
	MON_IFTYPE_VIRTUAL,
	MON_IFTYPE_ETHER,
	MON_IFTYPE_FDDI,
	MON_IFTYPE_IEEE802_TR,
	MON_IFTYPE_IEEE80211,
	MON_IFTYPE_SLIP,
	MON_IFTYPE_PPP,
	MON_IFTYPE_MEMCHANNEL,
	MON_IFTYPE_IRDA
} mon_iftype;

Network interface hardware types.

`MON_IFTYPE_UNKNOWN`	Unknown hardware.
`MON_IFTYPE_LOOPBACK`	Local loopback interface.
`MON_IFTYPE_VIRTUAL`	Virtual interface (tunnel etc.).
`MON_IFTYPE_ETHER`	Ethernet (10/100/1000 Mbit).
`MON_IFTYPE_FDDI`	FDDI.
`MON_IFTYPE_IEEE802_TR`	IEEE 802 Token Ring.
`MON_IFTYPE_IEEE80211`	IEEE 802.11
`MON_IFTYPE_SLIP`	IP over terminal device.
`MON_IFTYPE_PPP`	Point-to-Point device.
`MON_IFTYPE_MEMCHANNEL`	Memory channel or similar.
`MON_IFTYPE_IRDA`	IrDA device.

mon_ifinfo

typedef struct {
	char			*name;

	mon_iftype		type;
	mon_hwaddr		*hwaddr;

	unsigned int		mtu;
	mon_ifflags		flags;

	GList			*v4_addrs;
	unsigned int		num_v4_addrs;
	GList			*v6_addrs;
	unsigned int		num_v6_addrs;

	/* Can be used to hold statistics */
	void			*user_data;
} mon_ifinfo;

Represents information about a network interface.

char *`name`;	the name of the interface.
mon_iftype `type`;	the hardware type of the interface.
mon_hwaddr *`hwaddr`;	the hardware address of the interface (if it has one).
unsigned int `mtu`;	the MTU of the interface.
mon_ifflags `flags`;	one or more of mon_ifflags.
GList *`v4_addrs`;	the list of IPv4 addresses the interface has.
unsigned int `num_v4_addrs`;	number of IPv4 addresses configured on the interface.
GList *`v6_addrs`;	the list of IPv6 addresses the interface has.
unsigned int `num_v6_addrs`;	number of IPv6 addresses configured on the interface.
void *`user_data`;	user-controlled data, usually traffic and error statistics.

mon_ifinfo_match ()

int         mon_ifinfo_match                (mon_ifinfo *ifinfo,
                                             mon_addrlist *addr);

Checks if one or more addresses in addr are configured on the interface ifinfo.

`ifinfo` :	a mon_ifinfo interface description.
`addr` :	a mon_addrlist.
Returns :	`TRUE` if one or more addresses are configured on `ifinfo`, `FALSE` otherwise.

mon_iflist

typedef struct {
	/* Elements allocated for the ifs field */
	unsigned int		num_ifs;
	/* Number of interfaces that are UP */
	unsigned int		ifs_up;
	/* Number of interfaces that are known */
	unsigned int		ifs_known;
	mon_ifinfo		*ifs;
	GDestroyNotify		user_data_done;
	struct timeval		last_update;
} mon_iflist;

Represents the list of all defined network interfaces on the system.

unsigned int `num_ifs`;	number of slots allocated for network interfaces.
unsigned int `ifs_up`;	number of interfaces that are up.
unsigned int `ifs_known`;	number of currently defined interfaces.
mon_ifinfo *`ifs`;	list of interfaces. The index in the list is the interface's index; if the `name` field of a slot is `NULL`, then there is no defined interface with that index.
GDestroyNotify `user_data_done`;	function to call for deallocating `user_data` in a mon_ifinfo structure.
struct timeval `last_update`;	timestamp of the last update of the interface list.

mon_iflist_init ()

void        mon_iflist_init                 (mon_iflist *ifs);

Initializes a mon_iflist.

ifs : a mon_iflist to initialize.

mon_iflist_update ()

int         mon_iflist_update               (mon_iflist *ifs);

Updates a mon_iflist to match the current state of the network interfaces.

`ifs` :	a mon_iflist.
Returns :	0 if successful or an error code.

mon_iflist_destroy ()

void        mon_iflist_destroy              (mon_iflist *ifs);

Releases memory allocated to a mon_iflist.

ifs : a mon_iflist.

mon_iflist_check_name ()

int         mon_iflist_check_name           (mon_iflist *ifs,
                                             unsigned int ifindex,
                                             const char *name);

Checks if the interface with the given index has the given name. If this interface was not known previously, the interface list is resized to have enough space to accomodate it. If the interface was previously defined but its name was changed, reflect the change in ifs too.

`ifs` :	a mon_iflist.
`ifindex` :	the index of the interface to check.
`name` :	the current name of the interface.
Returns :	0 if successful or an erorr code.

mon_iflist_del ()

void        mon_iflist_del                  (mon_iflist *ifs,
                                             unsigned int ifindex);

Deletes an interface from a mon_iflist.

`ifs` :	a mon_iflist.
`ifindex` :	the index of the interface to delete.

mon_iflist_clean ()

void        mon_iflist_clean                (mon_iflist *ifs);

Removes all interfaces and/or interface addresses from a mon_iflist that do not have the MON_IF_SEEN flag set.

ifs : a mon_iflist.

mon_hwaddr_new ()

mon_hwaddr* mon_hwaddr_new                  (unsigned char *hwaddr,
                                             unsigned int addrlen);

Allocates a new hardware address.

`hwaddr` :	the opaque hardware address.
`addrlen` :	length of `hwaddr`.
Returns :	a mon_hwaddr or `NULL` if out of memory.

mon_hwaddr_free ()

void        mon_hwaddr_free                 (mon_hwaddr *addr);

Deallocates a mon_hwaddr.

addr : a mon_hwaddr.

mon_iftype_tostr ()

const char* mon_iftype_tostr                (mon_iftype type);

Converts a mon_iftype to a string.

`type` :	a mon_iftype.
Returns :	the stringified `type`.