Addresses
[Routing Netlink]

Detailed Description

1) Address Addition

 // Allocate an empty address object to be filled out with the attributes
 // of the new address.
 struct rtnl_addr *addr = rtnl_addr_alloc();

 // Fill out the mandatory attributes of the new address. Setting the
 // local address will automatically set the address family and the
 // prefix length to the correct values.
 rtnl_addr_set_ifindex(addr, ifindex);
 rtnl_addr_set_local(addr, local_addr);

 // The label of the address can be specified, currently only supported
 // by IPv4 and DECnet.
 rtnl_addr_set_label(addr, "mylabel");

 // The peer address can be specified if necessary, in either case a peer
 // address will be sent to the kernel in order to fullfil the interface
 // requirements. If none is set, it will equal the local address.
 // Note: Real peer addresses are only supported by IPv4 for now.
 rtnl_addr_set_peer(addr, peer_addr);

 // In case you want to have the address have a scope other than global
 // it may be overwritten using rtnl_addr_set_scope(). The scope currently
 // cannot be set for IPv6 addresses.
 rtnl_addr_set_scope(addr, rtnl_str2scope("site"));

 // Broadcast and anycast address may be specified using the relevant
 // functions, the address family will be verified if one of the other
 // addresses has been set already. Currently only works for IPv4.
 rtnl_addr_set_broadcast(addr, broadcast_addr);
 rtnl_addr_set_anycast(addr, anycast_addr);

 // Build the netlink message and send it to the kernel, the operation will
 // block until the operation has been completed. Alternatively the required
 // netlink message can be built using rtnl_addr_build_add_request() to be
 // sent out using nl_send_auto_complete().
 rtnl_addr_add(handle, addr, 0);

 // Free the memory
 rtnl_addr_put(addr);

2) Address Deletion
 // Allocate an empty address object to be filled out with the attributes
 // matching the address to be deleted. Alternatively a fully equipped
 // address object out of a cache can be used instead.
 struct rtnl_addr *addr = rtnl_addr_alloc();

 // The only mandatory parameter besides the address family is the interface
 // index the address is on, i.e. leaving out all other parameters will
 // result in all addresses of the specified address family interface tuple
 // to be deleted.
 rtnl_addr_set_ifindex(addr, ifindex);

 // Specyfing the address family manually is only required if neither the
 // local nor peer address have been specified.
 rtnl_addr_set_family(addr, AF_INET);

 // Specyfing the local address is optional but the best choice to delete
 // specific addresses.
 rtnl_addr_set_local(addr, local_addr);

 // The label of the address can be specified, currently only supported
 // by IPv4 and DECnet.
 rtnl_addr_set_label(addr, "mylabel");

 // The peer address can be specified if necessary, in either case a peer
 // address will be sent to the kernel in order to fullfil the interface
 // requirements. If none is set, it will equal the local address.
 // Note: Real peer addresses are only supported by IPv4 for now.
 rtnl_addr_set_peer(addr, peer_addr);

 // Build the netlink message and send it to the kernel, the operation will
 // block until the operation has been completed. Alternatively the required
 // netlink message can be built using rtnl_addr_build_delete_request()
 // to be sent out using nl_send_auto_complete().
 rtnl_addr_delete(handle, addr, 0);

 // Free the memory
 rtnl_addr_put(addr);


Address Flags Translations

char * rtnl_addr_flags2str (int flags, char *buf, size_t size)
 Convert address flags to character string.
int rtnl_addr_str2flags (const char *name)
 Convert character string to address flags.

Address Object Creation/Deletion

rtnl_addr * rtnl_addr_alloc (void)
 Allocate and initialize a new address object.
void rtnl_addr_put (struct rtnl_addr *addr)
 Give back a reference on a address object.
void rtnl_addr_free (struct rtnl_addr *addr)
 Free an address object.

Address Cache Management

nl_cache * rtnl_addr_alloc_cache (struct nl_handle *handle)
 Allocate address cache and fill in all configured addresses.

Address Addition

nl_msg * rtnl_addr_build_add_request (struct rtnl_addr *addr, int flags)
 Build netlink request message to request addition of new address.
int rtnl_addr_add (struct nl_handle *handle, struct rtnl_addr *addr, int flags)
 Request addition of new address.

Address Deletion

nl_msg * rtnl_addr_build_delete_request (struct rtnl_addr *addr, int flags)
 Build a netlink request message to request deletion of an address.
int rtnl_addr_delete (struct nl_handle *handle, struct rtnl_addr *addr, int flags)
 Request deletion of an address.

Attribute Access

void rtnl_addr_set_label (struct rtnl_addr *addr, const char *label)
 Set label of address object.
char * rtnl_addr_get_label (struct rtnl_addr *addr)
 Get label of address object.
void rtnl_addr_set_ifindex (struct rtnl_addr *addr, int ifindex)
 Set interface index of address object.
int rtnl_addr_get_ifindex (struct rtnl_addr *addr)
 Get interface index of address object.
void rtnl_addr_set_family (struct rtnl_addr *addr, int family)
 Set address family of address object.
int rtnl_addr_get_family (struct rtnl_addr *addr)
 Get address family of address object.
void rtnl_addr_set_prefixlen (struct rtnl_addr *addr, int prefix)
 Set prefix length of address object.
int rtnl_addr_get_prefixlen (struct rtnl_addr *addr)
 Get prefix length of address object.
void rtnl_addr_set_scope (struct rtnl_addr *addr, int scope)
 Set scope of address object.
int rtnl_addr_get_scope (struct rtnl_addr *addr)
 Get scope of address object.
void rtnl_addr_set_flags (struct rtnl_addr *addr, unsigned int flags)
 Set flags of address object.
void rtnl_addr_unset_flags (struct rtnl_addr *addr, unsigned int flags)
 Unset flags of address object.
unsigned int rtnl_addr_get_flags (struct rtnl_addr *addr)
 Get flags of address object.
int rtnl_addr_set_local (struct rtnl_addr *addr, struct nl_addr *local)
 Set local address of address object.
nl_addr * rtnl_addr_get_local (struct rtnl_addr *addr)
 Get local address of address object.
int rtnl_addr_set_peer (struct rtnl_addr *addr, struct nl_addr *peer)
 Set peer address of address object.
nl_addr * rtnl_addr_get_peer (struct rtnl_addr *addr)
 Get peer address of address object.
int rtnl_addr_set_broadcast (struct rtnl_addr *addr, struct nl_addr *bcast)
 Set broadcast address of address object.
nl_addr * rtnl_addr_get_broadcast (struct rtnl_addr *addr)
 Get broadcast address of address object.
int rtnl_addr_set_anycast (struct rtnl_addr *addr, struct nl_addr *anycast)
 Set anycast address of address object.
nl_addr * rtnl_addr_get_anycast (struct rtnl_addr *addr)
 Get anycast address of address object.
int rtnl_addr_set_multicast (struct rtnl_addr *addr, struct nl_addr *multicast)
 Set multicast address of address object.
nl_addr * rtnl_addr_get_multicast (struct rtnl_addr *addr)
 Get multicast address of address object.

Function Documentation

struct rtnl_addr* rtnl_addr_alloc ( void   ) 

Allocate and initialize a new address object.

Note:
Free the memory after usage using rtnl_addr_put() or rtnl_addr_free().
Returns:
Newly allocated address object or NULL if an error occured.

Definition at line 571 of file addr.c.

References nl_object_alloc_from_ops().

void rtnl_addr_put ( struct rtnl_addr *  addr  ) 

Give back a reference on a address object.

Parameters:
addr Address object to be given back.
Decrements the reference counter and frees the object if the last reference has been released.

Definition at line 583 of file addr.c.

References nl_object_put().

void rtnl_addr_free ( struct rtnl_addr *  addr  ) 

Free an address object.

Parameters:
addr Address object to be freed.
Note:
Always use rtnl_addr_put() unless you're absolutely sure that no other user may have a reference on this object.

Definition at line 595 of file addr.c.

References nl_object_free().

struct nl_cache* rtnl_addr_alloc_cache ( struct nl_handle *  handle  ) 

Allocate address cache and fill in all configured addresses.

Parameters:
handle Netlink handle.
Allocates a new address cache, initializes it properly and updates it to include all addresses currently configured in the kernel.

Note:
Free the memory after usage.
Returns:
Newly allocated cache or NULL if an error occured.

Definition at line 617 of file addr.c.

References nl_cache_alloc_from_ops(), nl_cache_free(), and nl_cache_update().

struct nl_msg* rtnl_addr_build_add_request ( struct rtnl_addr *  addr,
int  flags 
)

Build netlink request message to request addition of new address.

Parameters:
addr Address object representing the new address.
flags Additional netlink message flags.
Builds a new netlink message requesting the addition of a new address. The netlink message header isn't fully equipped with all relevant fields and must thus be sent out via nl_send_auto_complete() or supplemented as needed.

Minimal required attributes:

The scope will default to universe except for loopback addresses in which case a host scope is used if not specified otherwise.

Note:
Free the memory after usage using nlmsg_free().
Returns:
Newly allocated netlink message or NULL if an error occured.

Definition at line 712 of file addr.c.

References NLM_F_CREATE.

Referenced by rtnl_addr_add().

int rtnl_addr_add ( struct nl_handle *  handle,
struct rtnl_addr *  addr,
int  flags 
)

Request addition of new address.

Parameters:
handle Netlink handle.
addr Address object representing the new address.
flags Additional netlink message flags.
Builds a netlink message by calling rtnl_addr_build_add_request(), sends the request to the kernel and waits for the next ACK to be received and thus blocks until the request has been fullfilled.

See also:
rtnl_addr_build_add_request()
Returns:
0 on sucess or a negative error if an error occured.

Definition at line 740 of file addr.c.

References nl_send_auto_complete(), nl_wait_for_ack(), nlmsg_free(), and rtnl_addr_build_add_request().

struct nl_msg* rtnl_addr_build_delete_request ( struct rtnl_addr *  addr,
int  flags 
)

Build a netlink request message to request deletion of an address.

Parameters:
addr Address object to be deleteted.
flags Additional netlink message flags.
Builds a new netlink message requesting a deletion of an address. The netlink message header isn't fully equipped with all relevant fields and must thus be sent out via nl_send_auto_complete() or supplemented as needed.

Minimal required attributes:

Optional attributes:

Note:
Free the memory after usage using nlmsg_free().
Returns:
Newly allocated netlink message or NULL if an error occured.

Definition at line 786 of file addr.c.

Referenced by rtnl_addr_delete().

int rtnl_addr_delete ( struct nl_handle *  handle,
struct rtnl_addr *  addr,
int  flags 
)

Request deletion of an address.

Parameters:
handle Netlink handle.
addr Address object to be deleted.
flags Additional netlink message flags.
Builds a netlink message by calling rtnl_addr_build_delete_request(), sends the request to the kernel and waits for the next ACK to be received and thus blocks until the request has been fullfilled.

See also:
rtnl_addr_build_delete_request();
Returns:
0 on sucess or a negative error if an error occured.

Definition at line 813 of file addr.c.

References nl_send_auto_complete(), nl_wait_for_ack(), nlmsg_free(), and rtnl_addr_build_delete_request().

void rtnl_addr_set_label ( struct rtnl_addr *  addr,
const char *  label 
)

Set label of address object.

Parameters:
addr Address object to be modified.
label New address label.
Note:
The maximum size of an address label is IFNAMSIZ.

Definition at line 845 of file addr.c.

char* rtnl_addr_get_label ( struct rtnl_addr *  addr  ) 

Get label of address object.

Parameters:
addr Address object.
Returns:
Address label or NULL if not set.

Definition at line 856 of file addr.c.

void rtnl_addr_set_ifindex ( struct rtnl_addr *  addr,
int  ifindex 
)

Set interface index of address object.

Parameters:
addr Address object ot be modified.
ifindex New interface index this address is on.

Definition at line 869 of file addr.c.

int rtnl_addr_get_ifindex ( struct rtnl_addr *  addr  ) 

Get interface index of address object.

Parameters:
addr Address object.
Returns:
Interface index address is on or RTNL_LINK_NOT_FOUND if not set.

Definition at line 880 of file addr.c.

References RTNL_LINK_NOT_FOUND.

void rtnl_addr_set_family ( struct rtnl_addr *  addr,
int  family 
)

Set address family of address object.

Parameters:
addr Address object to be modified.
family New address family
Note:
The address family is set automatically if one of the addresses is set and the family hasn't been specified yet. Setting it manually can be used to enforce family validation while setting addresses.

Definition at line 897 of file addr.c.

int rtnl_addr_get_family ( struct rtnl_addr *  addr  ) 

Get address family of address object.

Parameters:
addr Address object.
Returns:
Address family or AF_UNSPEC if not set.

Definition at line 908 of file addr.c.

void rtnl_addr_set_prefixlen ( struct rtnl_addr *  addr,
int  prefix 
)

Set prefix length of address object.

Parameters:
addr Address object to be modified.
prefix New prefix length.

Definition at line 921 of file addr.c.

int rtnl_addr_get_prefixlen ( struct rtnl_addr *  addr  ) 

Get prefix length of address object.

Parameters:
addr Address object.
Returns:
Prefix length or a negative number if not set.

Definition at line 932 of file addr.c.

void rtnl_addr_set_scope ( struct rtnl_addr *  addr,
int  scope 
)

Set scope of address object.

Parameters:
addr Address object to be modified.
scope New scope.

Definition at line 945 of file addr.c.

int rtnl_addr_get_scope ( struct rtnl_addr *  addr  ) 

Get scope of address object.

Parameters:
addr Address object.
Returns:
Scope or a negative number if not set.

Definition at line 956 of file addr.c.

void rtnl_addr_set_flags ( struct rtnl_addr *  addr,
unsigned int  flags 
)

Set flags of address object.

Parameters:
addr Address object to be modified.
flags Additional flags to set.
Note:
Existing flags that have been set will not be overwritten.

Definition at line 971 of file addr.c.

void rtnl_addr_unset_flags ( struct rtnl_addr *  addr,
unsigned int  flags 
)

Unset flags of address object.

Parameters:
addr Address object to be modified.
flags Flags to unset.

Definition at line 983 of file addr.c.

unsigned int rtnl_addr_get_flags ( struct rtnl_addr *  addr  ) 

Get flags of address object.

Parameters:
addr Address object.
Returns:
Flags in form of a bitmask.

Definition at line 995 of file addr.c.

int rtnl_addr_set_local ( struct rtnl_addr *  addr,
struct nl_addr *  local 
)

Set local address of address object.

Parameters:
addr Address object to be modified.
local New local address.
Assigns the new local address to the specified address object. The address is validated against the address family if set already via either rtnl_addr_set_family() or by setting one of the other addresses. The assignment fails if the address families mismatch. In case the address family has not been specified yet, the address family of the new address is elected to be the new requirement.

Note:
The address may not contain a prefix length if the peer address has been specified already.
Returns:
0 on success or a negative error code.

Definition at line 1035 of file addr.c.

References nl_addr_get_prefixlen().

struct nl_addr* rtnl_addr_get_local ( struct rtnl_addr *  addr  ) 

Get local address of address object.

Parameters:
addr Address object.
Returns:
Local address or NULL if not set.

Definition at line 1056 of file addr.c.

int rtnl_addr_set_peer ( struct rtnl_addr *  addr,
struct nl_addr *  peer 
)

Set peer address of address object.

Parameters:
addr Address object to be modified.
peer New peer address.
Assigns the new peer address to the specified address object. The address is validated against the address family if set already via either rtnl_addr_set_family() or by setting one of the other addresses. The assignment fails if the address families mismatch. In case the address family has not been specified yet, the address family of this new address is elected to be the requirement.

Returns:
0 on success or a negative error code.

Definition at line 1078 of file addr.c.

References nl_addr_get_prefixlen().

struct nl_addr* rtnl_addr_get_peer ( struct rtnl_addr *  addr  ) 

Get peer address of address object.

Parameters:
addr Adress object.
Returns:
Peer address or NULL if not set.

Definition at line 1093 of file addr.c.

int rtnl_addr_set_broadcast ( struct rtnl_addr *  addr,
struct nl_addr *  bcast 
)

Set broadcast address of address object.

Parameters:
addr Address object to be modified.
bcast New broadcast address.
Assigns the new broadcast address to the specified address object. The address is validated against the address family if set already via either rtnl_addr_set_family() or by setting one of the other addresses. The assignment fails if the address families mismatch. In case the address family has not been specified yet, the address family of this new address is elected to be the requirement.

Returns:
0 on success or a negative error code.

Definition at line 1115 of file addr.c.

struct nl_addr* rtnl_addr_get_broadcast ( struct rtnl_addr *  addr  ) 

Get broadcast address of address object.

Parameters:
addr Address object.
Returns:
Broadcast address or NULL if not set.

Definition at line 1125 of file addr.c.

int rtnl_addr_set_anycast ( struct rtnl_addr *  addr,
struct nl_addr *  anycast 
)

Set anycast address of address object.

Parameters:
addr Address object to be modified.
anycast New anycast address.
Assigns the new anycast address to the specified address object. The address is validated against the address family if set already via either rtnl_addr_set_family() or by setting one of the other addresses. The assignment fails if the address families mismatch. In case the address family has not been specified yet, the address family of this new address is elected to be the requirement.

Returns:
0 on success or a negative error code.

Definition at line 1147 of file addr.c.

struct nl_addr* rtnl_addr_get_anycast ( struct rtnl_addr *  addr  ) 

Get anycast address of address object.

Parameters:
addr Address object.
Returns:
Anycast address or NULL if not set.

Definition at line 1158 of file addr.c.

int rtnl_addr_set_multicast ( struct rtnl_addr *  addr,
struct nl_addr *  multicast 
)

Set multicast address of address object.

Parameters:
addr Address object to be modified.
multicast New multicast address.
Assigns the new multicast address to the specified address object. The address is validated against the address family if set already via either rtnl_addr_set_family() or by setting one of the other addresses. The assignment fails if the address families mismatch. In case the address family has not been specified yet, the address family of this new address is elected to be the requirement.

Returns:
0 on success or a negative error code.

Definition at line 1180 of file addr.c.

struct nl_addr* rtnl_addr_get_multicast ( struct rtnl_addr *  addr  ) 

Get multicast address of address object.

Parameters:
addr Address object.
Returns:
Multicast address or NULL if not set.

Definition at line 1191 of file addr.c.

char* rtnl_addr_flags2str ( int  flags,
char *  buf,
size_t  size 
)

Convert address flags to character string.

Parameters:
flags Address flags.
buf Destination buffer.
size Size of destination buffer.
Converts address flags to a character string separated by commas and stores the resulting character string in the specified destination buffer.

Returns:
Formatted flags as character string.

Definition at line 1224 of file addr.c.

int rtnl_addr_str2flags ( const char *  name  ) 

Convert character string to address flags.

Parameters:
name Name of address flags.
Converts the provided character string specifying any number of address flags separated by commas to the corresponding numeric bitmask.

Returns:
Address flags in form of a bitmask.

Definition at line 1239 of file addr.c.

Generated on Fri Apr 27 14:14:07 2007 for libnl by  doxygen 1.5.1