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_UPinterface is up.
MON_IF_BROADCASTbroadcast address valid.
MON_IF_POINTOPOINTthe interface is a point-to-point link.
MON_IF_LOOPBACKthis is a local loopback interface.
MON_IF_RUNNINGresources allocated.
MON_IF_PROMISCreceive all packets.
MON_IF_MULTICASTmulticast is supported.
MON_IF_SEENinternal flag to mark an interface/address seen.
MON_IF_FLAGS_CHECKEDinternal flag to mark an interface's flags checked.
MON_IF_NEWinternal 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_UNKNOWNUnknown hardware.
MON_IFTYPE_LOOPBACKLocal loopback interface.
MON_IFTYPE_VIRTUALVirtual interface (tunnel etc.).
MON_IFTYPE_ETHEREthernet (10/100/1000 Mbit).
MON_IFTYPE_FDDIFDDI.
MON_IFTYPE_IEEE802_TRIEEE 802 Token Ring.
MON_IFTYPE_IEEE80211IEEE 802.11
MON_IFTYPE_SLIPIP over terminal device.
MON_IFTYPE_PPPPoint-to-Point device.
MON_IFTYPE_MEMCHANNELMemory channel or similar.
MON_IFTYPE_IRDAIrDA 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.