Neighbours
[Routing Netlink]


Detailed Description

The neighbour table establishes bindings between protocol addresses and link layer addresses for hosts sharing the same physical link.

This module allows you to access and manipulate the content of these tables.

Neighbour States
 NUD_INCOMPLETE
 NUD_REACHABLE
 NUD_STALE
 NUD_DELAY
 NUD_PROBE
 NUD_FAILED
 NUD_NOARP
 NUD_PERMANENT
Neighbour Flags
 NTF_PROXY
 NTF_ROUTER
Neighbour Identification
A neighbour is uniquely identified by the attributes listed below, whenever you refer to an existing neighbour all of the attributes must be set. Neighbours from caches automatically have all required attributes set.
Changeable Attributes
Required Caches for Dumping
In order to dump neighbour attributes you must provide the following caches via nl_cache_provide()
TODO
1) Retrieving information about configured neighbours
 // The first step is to retrieve a list of all available neighbour within
 // the kernel and put them into a cache.
 struct nl_cache *cache = rtnl_neigh_alloc_cache(handle);

 // Neighbours can then be looked up by the interface and destination
 // address:
 struct rtnl_neigh *neigh = rtnl_neigh_get(cache, ifindex, dst_addr);
 
 // After successful usage, the object must be given back to the cache
 rtnl_neigh_put(neigh);
2) Adding new neighbours
 // Allocate an empty neighbour handle to be filled out with the attributes
 // of the new neighbour.
 struct rtnl_neigh *neigh = rtnl_neigh_alloc();

 // Fill out the attributes of the new neighbour
 rtnl_neigh_set_ifindex(neigh, ifindex);
 rtnl_neigh_set_dst(neigh, dst_addr);
 rtnl_neigh_set_state(neigh, rtnl_neigh_str2state("permanent"));

 // 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_neigh_build_add_request()
 // to be sent out using nl_send_auto_complete().
 rtnl_neigh_add(nl_handle, neigh, NLM_F_REPLACE);

 // Free the memory
 rtnl_neigh_put(neigh);
3) Deleting an existing neighbour
 // Allocate an empty neighbour object to be filled out with the attributes
 // matching the neighbour to be deleted. Alternatively a fully equipped
 // neighbour object out of a cache can be used instead.
 struct rtnl_neigh *neigh = rtnl_neigh_alloc();

 // Neighbours are uniquely identified by their interface index and
 // destination address, you may fill out other attributes but they
 // will have no influence.
 rtnl_neigh_set_ifindex(neigh, ifindex);
 rtnl_neigh_set_dst(neigh, dst_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_neigh_build_delete_request()
 // to be sent out using nl_send_auto_complete().
 rtnl_neigh_delete(handle, neigh, 0);

 // Free the memory
 rtnl_neigh_put(neigh);
4) Changing neighbour attributes
 // Allocate an empty neighbour object to be filled out with the attributes
 // matching the neighbour to be changed and the new parameters. Alternatively
 // a fully equipped modified neighbour object out of a cache can be used.
 struct rtnl_neigh *neigh = rtnl_neigh_alloc();

 // Identify the neighbour to be changed by its interface index and
 // destination address
 rtnl_neigh_set_ifindex(neigh, ifindex);
 rtnl_neigh_set_dst(neigh, dst_addr);

 // The link layer address may be modified, if so it is wise to change
 // its state to "permanent" in order to avoid having it overwritten.
 rtnl_neigh_set_lladdr(neigh, lladdr);

 // Secondly the state can be modified allowing normal neighbours to be
 // converted into permanent entries or to manually confirm a neighbour.
 rtnl_neigh_set_state(neigh, state);

 // 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_neigh_build_change_request()
 // to be sent out using nl_send_auto_complete().
 rtnl_neigh_change(handle, neigh, 0);

 // Free the memory
 rtnl_neigh_put(neigh);


Neighbour States Translations

char * rtnl_neigh_state2str (int state, char *buf, size_t len)
 Convert neighbour states to a character string (Reentrant).
int rtnl_neigh_str2state (const char *name)
 Convert a character string to a neighbour state.

Neighbour Flags Translations

char * rtnl_neigh_flags2str (int flags, char *buf, size_t len)
 Convert neighbour flags to a character string (Reentrant).
int rtnl_neigh_str2flag (const char *name)
 Convert a character string to a neighbour flag.

Neighbour Object Allocation/Freeage

rtnl_neigh * rtnl_neigh_alloc (void)
 Allocate a new neighbour object.
void rtnl_neigh_put (struct rtnl_neigh *neigh)
 Give back reference on neighbour object.
void rtnl_neigh_free (struct rtnl_neigh *neigh)
 Free neighbour object.

Neighbour Cache Managament

nl_cache * rtnl_neigh_alloc_cache (struct nl_handle *handle)
 Build a neighbour cache including all neighbours currently configured in the kernel.
rtnl_neigh * rtnl_neigh_get (struct nl_cache *cache, int ifindex, struct nl_addr *dst)
 Look up a neighbour by interface index and destination address.

Neighbour Addition

nl_msg * rtnl_neigh_build_add_request (struct rtnl_neigh *tmpl, int flags)
 Build netlink request message to add a new neighbour.
int rtnl_neigh_add (struct nl_handle *handle, struct rtnl_neigh *tmpl, int flags)
 Add a new neighbour.

Neighbour Deletion

nl_msg * rtnl_neigh_build_delete_request (struct rtnl_neigh *neigh, int flags)
 Build a netlink request message to delete a neighbour.
int rtnl_neigh_delete (struct nl_handle *handle, struct rtnl_neigh *neigh, int flags)
 Delete a neighbour.

Neighbour Modification

nl_msg * rtnl_neigh_build_change_request (struct rtnl_neigh *neigh, int flags)
 Build a netlink request message to change neighbour attributes.
int rtnl_neigh_change (struct nl_handle *handle, struct rtnl_neigh *neigh, int flags)
 Change neighbour attributes.

Attribute Modification

void rtnl_neigh_set_state (struct rtnl_neigh *neigh, int state)
 Set a neighbour state.
int rtnl_neigh_get_state (struct rtnl_neigh *neigh)
 Get neighbour states.
void rtnl_neigh_unset_state (struct rtnl_neigh *neigh, int state)
 Unset a neigbour state.
void rtnl_neigh_set_flags (struct rtnl_neigh *neigh, unsigned int flags)
 Set neighbour flags.
unsigned int rtnl_neigh_get_flags (struct rtnl_neigh *neigh)
 Get neighbour flags.
void rtnl_neigh_unset_flags (struct rtnl_neigh *neigh, unsigned int flags)
 Unset neighbour flags.
void rtnl_neigh_set_ifindex (struct rtnl_neigh *neigh, int ifindex)
 Set the interface index of device this neighbour is on.
int rtnl_neigh_get_ifindex (struct rtnl_neigh *neigh)
 Get the interface index of the device this neighbour is on.
void rtnl_neigh_set_lladdr (struct rtnl_neigh *neigh, struct nl_addr *addr)
 Set link layer address of a neighbour.
nl_addr * rtnl_neigh_get_lladdr (struct rtnl_neigh *neigh)
 Get link layer address of a neighbour.
int rtnl_neigh_set_dst (struct rtnl_neigh *neigh, struct nl_addr *addr)
 Set destination address of a neighbour.
nl_addr * rtnl_neigh_get_dst (struct rtnl_neigh *neigh)
 Get the destination address of a neighbour.
void rtnl_neigh_set_family (struct rtnl_neigh *neigh, int family)
 Set destination address family.
void rtnl_neigh_set_type (struct rtnl_neigh *neigh, int type)
 Set RTN type of a neighbour.
int rtnl_neigh_get_type (struct rtnl_neigh *neigh)
 Get RTN type of a neighbour.


Function Documentation

struct rtnl_neigh* rtnl_neigh_alloc ( void   ) 

Allocate a new neighbour object.

Returns:
New neighbour object

Definition at line 469 of file neigh.c.

References nl_object_alloc_from_ops().

void rtnl_neigh_put ( struct rtnl_neigh *  neigh  ) 

Give back reference on neighbour object.

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

Definition at line 481 of file neigh.c.

References nl_object_put().

void rtnl_neigh_free ( struct rtnl_neigh *  neigh  ) 

Free neighbour object.

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

Definition at line 492 of file neigh.c.

References nl_object_free().

struct nl_cache* rtnl_neigh_alloc_cache ( struct nl_handle *  handle  ) 

Build a neighbour cache including all neighbours currently configured in the kernel.

Parameters:
handle netlink handle
Allocates a new neighbour cache, initializes it properly and updates it to include all neighbours currently configured in the kernel.

Note:
The caller is responsible for destroying and freeing the cache after using it.
Returns:
The new cache or NULL if an error occured.

Definition at line 515 of file neigh.c.

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

struct rtnl_neigh* rtnl_neigh_get ( struct nl_cache *  cache,
int  ifindex,
struct nl_addr *  dst 
)

Look up a neighbour by interface index and destination address.

Parameters:
cache neighbour cache
ifindex interface index the neighbour is on
dst destination address of the neighbour
Returns:
neighbour handle or NULL if no match was found.

Definition at line 539 of file neigh.c.

References nl_addr_cmp(), and nl_object_get().

struct nl_msg* rtnl_neigh_build_add_request ( struct rtnl_neigh *  tmpl,
int  flags 
)

Build netlink request message to add a new neighbour.

Parameters:
tmpl template with data of new neighbour
flags additional netlink message flags
Builds a new netlink message requesting a addition of a new neighbour. 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. tmpl must contain the attributes of the new neighbour set via rtnl_neigh_set_* functions.

The following attributes must be set in the template:

Returns:
The netlink message

Definition at line 613 of file neigh.c.

References NLM_F_CREATE.

Referenced by rtnl_neigh_add().

int rtnl_neigh_add ( struct nl_handle *  handle,
struct rtnl_neigh *  tmpl,
int  flags 
)

Add a new neighbour.

Parameters:
handle netlink handle
tmpl template with requested changes
flags additional netlink message flags
Builds a netlink message by calling rtnl_neigh_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.

The following attributes must be set in the template:

Returns:
0 on sucess or a negative error if an error occured.

Definition at line 636 of file neigh.c.

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

struct nl_msg* rtnl_neigh_build_delete_request ( struct rtnl_neigh *  neigh,
int  flags 
)

Build a netlink request message to delete a neighbour.

Parameters:
neigh neighbour to delete
flags additional netlink message flags
Builds a new netlink message requesting a deletion of a neighbour. 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. neigh must point to an existing neighbour.

Returns:
The netlink message

Definition at line 673 of file neigh.c.

Referenced by rtnl_neigh_delete().

int rtnl_neigh_delete ( struct nl_handle *  handle,
struct rtnl_neigh *  neigh,
int  flags 
)

Delete a neighbour.

Parameters:
handle netlink handle
neigh neighbour to delete
flags additional netlink message flags
Builds a netlink message by calling rtnl_neigh_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.

Returns:
0 on sucess or a negative error if an error occured.

Definition at line 691 of file neigh.c.

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

struct nl_msg* rtnl_neigh_build_change_request ( struct rtnl_neigh *  neigh,
int  flags 
)

Build a netlink request message to change neighbour attributes.

Parameters:
neigh the neighbour to change
flags additional netlink message flags
Builds a new netlink message requesting a change of a neigh attributes. 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.

Returns:
The netlink message
Note:
Not all attributes can be changed, see Changeable Attributes for a list.

Definition at line 730 of file neigh.c.

References NLM_F_REPLACE.

Referenced by rtnl_neigh_change().

int rtnl_neigh_change ( struct nl_handle *  handle,
struct rtnl_neigh *  neigh,
int  flags 
)

Change neighbour attributes.

Parameters:
handle netlink handle
neigh neighbour to be changed
flags additional netlink message flags
Builds a netlink message by calling rtnl_neigh_build_change_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.

Returns:
0 on sucess or a negative error if an error occured.
Note:
Not all attributes can be changed, see Changeable Attributes for a list.

Definition at line 750 of file neigh.c.

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

char* rtnl_neigh_state2str ( int  state,
char *  buf,
size_t  len 
)

Convert neighbour states to a character string (Reentrant).

Parameters:
state neighbour state
buf destination buffer
len buffer length
Converts a neighbour state to a character string separated by commands and stores it in the specified destination buffer.

Returns:
The destination buffer

Definition at line 797 of file neigh.c.

int rtnl_neigh_str2state ( const char *  name  ) 

Convert a character string to a neighbour state.

Parameters:
name Name of cscope
Converts the provided character string specifying a neighbour state the corresponding numeric value.

Returns:
Neighbour state or a negative value if none was found.

Definition at line 812 of file neigh.c.

char* rtnl_neigh_flags2str ( int  flags,
char *  buf,
size_t  len 
)

Convert neighbour flags to a character string (Reentrant).

Parameters:
flags neighbour flags
buf destination buffer
len buffer length
Converts neighbour flags to a character string separated by commands and stores it in the specified destination buffer.

Returns:
The destination buffer or a empty string if no flags are set.

Definition at line 840 of file neigh.c.

int rtnl_neigh_str2flag ( const char *  name  ) 

Convert a character string to a neighbour flag.

Parameters:
name name of the flag
Converts the provided character string specifying a neighbour flag the corresponding numeric value.

Returns:
Neighbour flag or a negative value if none was found.

Definition at line 855 of file neigh.c.

void rtnl_neigh_set_state ( struct rtnl_neigh *  neigh,
int  state 
)

Set a neighbour state.

Parameters:
neigh neighbour to change
state state to set

Definition at line 872 of file neigh.c.

int rtnl_neigh_get_state ( struct rtnl_neigh *  neigh  ) 

Get neighbour states.

Parameters:
neigh neighbour handle
Returns:
Neighbour state or -1 if not set

Definition at line 884 of file neigh.c.

void rtnl_neigh_unset_state ( struct rtnl_neigh *  neigh,
int  state 
)

Unset a neigbour state.

Parameters:
neigh neighbour to change
state state to unset

Definition at line 897 of file neigh.c.

void rtnl_neigh_set_flags ( struct rtnl_neigh *  neigh,
unsigned int  flags 
)

Set neighbour flags.

Parameters:
neigh neighbour to change
flags flag to set

Definition at line 909 of file neigh.c.

unsigned int rtnl_neigh_get_flags ( struct rtnl_neigh *  neigh  ) 

Get neighbour flags.

Parameters:
neigh neighbour handle
Returns:
Neighbour flags

Definition at line 921 of file neigh.c.

void rtnl_neigh_unset_flags ( struct rtnl_neigh *  neigh,
unsigned int  flags 
)

Unset neighbour flags.

Parameters:
neigh neighbour to change
flags flag to unset

Definition at line 931 of file neigh.c.

void rtnl_neigh_set_ifindex ( struct rtnl_neigh *  neigh,
int  ifindex 
)

Set the interface index of device this neighbour is on.

Parameters:
neigh neighbour to change
ifindex new interface index

Definition at line 943 of file neigh.c.

int rtnl_neigh_get_ifindex ( struct rtnl_neigh *  neigh  ) 

Get the interface index of the device this neighbour is on.

Parameters:
neigh neighbour handle
Returns:
Interface index or RTNL_LINK_NOT_FOUND if not set

Definition at line 954 of file neigh.c.

References RTNL_LINK_NOT_FOUND.

void rtnl_neigh_set_lladdr ( struct rtnl_neigh *  neigh,
struct nl_addr *  addr 
)

Set link layer address of a neighbour.

Parameters:
neigh neighbour to change
addr new link layer address
Assigns the new link layer address to the specified neighbour handle.

Note:
The prefix length of the address will be ignored.

Definition at line 996 of file neigh.c.

struct nl_addr* rtnl_neigh_get_lladdr ( struct rtnl_neigh *  neigh  ) 

Get link layer address of a neighbour.

Parameters:
neigh neighbour handle
Returns:
Link layer address or NULL if not set

Definition at line 1006 of file neigh.c.

int rtnl_neigh_set_dst ( struct rtnl_neigh *  neigh,
struct nl_addr *  addr 
)

Set destination address of a neighbour.

Parameters:
neigh neighbour to change
addr new destination address
Assigns the new destination address to the specified neighbour handle. The address is validated against the address family if set already via rtnl_neigh_set_family(). 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 1027 of file neigh.c.

struct nl_addr* rtnl_neigh_get_dst ( struct rtnl_neigh *  neigh  ) 

Get the destination address of a neighbour.

Parameters:
neigh neighbour handle
Returns:
Destination address or NULL if not set

Definition at line 1038 of file neigh.c.

void rtnl_neigh_set_family ( struct rtnl_neigh *  neigh,
int  family 
)

Set destination address family.

Parameters:
neigh neighbour to change
family new destination address family

Definition at line 1051 of file neigh.c.

void rtnl_neigh_set_type ( struct rtnl_neigh *  neigh,
int  type 
)

Set RTN type of a neighbour.

Parameters:
neigh neighbour to change
type new rtn type

Definition at line 1062 of file neigh.c.

int rtnl_neigh_get_type ( struct rtnl_neigh *  neigh  ) 

Get RTN type of a neighbour.

Parameters:
neigh neighbour handle
Returns:
Type or -1 if not set

Definition at line 1073 of file neigh.c.


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