libnl  1.1.4

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

Neighbour Object Allocation/Freeage

struct rtnl_neigh * rtnl_neigh_alloc (void)
 
void rtnl_neigh_put (struct rtnl_neigh *neigh)
 

Neighbour Cache Managament

struct nl_cache * rtnl_neigh_alloc_cache (struct nl_handle *handle)
 Build a neighbour cache including all neighbours currently configured in the kernel. More...
 
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. More...
 

Neighbour Addition

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

Neighbour Deletion

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

Neighbour Modification

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

Neighbour States Translations

char * rtnl_neigh_state2str (int state, char *buf, size_t len)
 
int rtnl_neigh_str2state (const char *name)
 

Neighbour Flags Translations

char * rtnl_neigh_flags2str (int flags, char *buf, size_t len)
 
int rtnl_neigh_str2flag (const char *name)
 

Attributes

void rtnl_neigh_set_state (struct rtnl_neigh *neigh, int state)
 
int rtnl_neigh_get_state (struct rtnl_neigh *neigh)
 
void rtnl_neigh_unset_state (struct rtnl_neigh *neigh, int state)
 
void rtnl_neigh_set_flags (struct rtnl_neigh *neigh, unsigned int flags)
 
unsigned int rtnl_neigh_get_flags (struct rtnl_neigh *neigh)
 
void rtnl_neigh_unset_flags (struct rtnl_neigh *neigh, unsigned int flags)
 
void rtnl_neigh_set_ifindex (struct rtnl_neigh *neigh, int ifindex)
 
int rtnl_neigh_get_ifindex (struct rtnl_neigh *neigh)
 
void rtnl_neigh_set_lladdr (struct rtnl_neigh *neigh, struct nl_addr *addr)
 
struct nl_addr * rtnl_neigh_get_lladdr (struct rtnl_neigh *neigh)
 
int rtnl_neigh_set_dst (struct rtnl_neigh *neigh, struct nl_addr *addr)
 
struct nl_addr * rtnl_neigh_get_dst (struct rtnl_neigh *neigh)
 
void rtnl_neigh_set_family (struct rtnl_neigh *neigh, int family)
 
void rtnl_neigh_set_type (struct rtnl_neigh *neigh, int type)
 
int rtnl_neigh_get_type (struct rtnl_neigh *neigh)
 

Detailed Description

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.
  • interface index (rtnl_neigh_set_ifindex())
  • destination address (rtnl_neigh_set_dst())
Changeable Attributes
  • state (rtnl_neigh_set_state())
  • link layer address (rtnl_neigh_set_lladdr())
Required Caches for Dumping
In order to dump neighbour attributes you must provide the following caches via nl_cache_provide()
  • link cache holding all links
TODO
  • Document proxy settings
  • Document states and their influence
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);

Function Documentation

struct nl_cache* rtnl_neigh_alloc_cache ( struct nl_handle *  handle)
Parameters
handlenetlink 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 534 of file neigh.c.

References nl_cache_alloc(), nl_cache_free(), and nl_cache_refill().

535 {
536  struct nl_cache *cache;
537 
538  cache = nl_cache_alloc(&rtnl_neigh_ops);
539  if (cache == NULL)
540  return NULL;
541 
542  if (handle && nl_cache_refill(handle, cache) < 0) {
543  nl_cache_free(cache);
544  return NULL;
545  }
546 
547  NL_DBG(2, "Returning new cache %p\n", cache);
548 
549  return cache;
550 }
void nl_cache_free(struct nl_cache *cache)
Free a cache.
Definition: cache.c:277
int nl_cache_refill(struct nl_handle *handle, struct nl_cache *cache)
(Re)fill a cache with the contents in the kernel.
Definition: cache.c:680
struct nl_cache * nl_cache_alloc(struct nl_cache_ops *ops)
Allocate an empty cache.
Definition: cache.c:170
struct rtnl_neigh* rtnl_neigh_get ( struct nl_cache *  cache,
int  ifindex,
struct nl_addr *  dst 
)
Parameters
cacheneighbour cache
ifindexinterface index the neighbour is on
dstdestination address of the neighbour
Returns
neighbour handle or NULL if no match was found.

Definition at line 559 of file neigh.c.

References nl_addr_cmp(), and nl_object_get().

561 {
562  struct rtnl_neigh *neigh;
563 
564  nl_list_for_each_entry(neigh, &cache->c_items, ce_list) {
565  if (neigh->n_ifindex == ifindex &&
566  !nl_addr_cmp(neigh->n_dst, dst)) {
567  nl_object_get((struct nl_object *) neigh);
568  return neigh;
569  }
570  }
571 
572  return NULL;
573 }
void nl_object_get(struct nl_object *obj)
Acquire a reference on a object.
Definition: object.c:167
int nl_addr_cmp(struct nl_addr *a, struct nl_addr *b)
Compares two abstract address objects.
Definition: addr.c:489
struct nl_msg* rtnl_neigh_build_add_request ( struct rtnl_neigh *  tmpl,
int  flags 
)
Parameters
tmpltemplate with data of new neighbour
flagsadditional 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:

  • Interface index (rtnl_neigh_set_ifindex())
  • State (rtnl_neigh_set_state())
  • Destination address (rtnl_neigh_set_dst())
  • Link layer address (rtnl_neigh_set_lladdr())
Returns
The netlink message

Definition at line 633 of file neigh.c.

References NLM_F_CREATE.

Referenced by rtnl_neigh_add().

634 {
635  return build_neigh_msg(tmpl, RTM_NEWNEIGH, NLM_F_CREATE | flags);
636 }
#define NLM_F_CREATE
Create config object if it doesn't already exist.
int rtnl_neigh_add ( struct nl_handle *  handle,
struct rtnl_neigh *  tmpl,
int  flags 
)
Parameters
handlenetlink handle
tmpltemplate with requested changes
flagsadditional 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:

  • Interface index (rtnl_neigh_set_ifindex())
  • State (rtnl_neigh_set_state())
  • Destination address (rtnl_neigh_set_dst())
  • Link layer address (rtnl_neigh_set_lladdr())
Returns
0 on sucess or a negative error if an error occured.

Definition at line 656 of file neigh.c.

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

657 {
658  int err;
659  struct nl_msg *msg;
660 
661  msg = rtnl_neigh_build_add_request(tmpl, flags);
662  if (!msg)
663  return nl_errno(ENOMEM);
664 
665  err = nl_send_auto_complete(handle, msg);
666  nlmsg_free(msg);
667  if (err < 0)
668  return err;
669 
670  return nl_wait_for_ack(handle);
671 }
int nl_wait_for_ack(struct nl_handle *handle)
Wait for ACK.
Definition: nl.c:801
void nlmsg_free(struct nl_msg *n)
Free a netlink message.
Definition: msg.c:656
struct nl_msg * rtnl_neigh_build_add_request(struct rtnl_neigh *tmpl, int flags)
Build netlink request message to add a new neighbour.
Definition: neigh.c:633
int nl_send_auto_complete(struct nl_handle *handle, struct nl_msg *msg)
Send netlink message and check & extend header values as needed.
Definition: nl.c:373
struct nl_msg* rtnl_neigh_build_delete_request ( struct rtnl_neigh *  neigh,
int  flags 
)
Parameters
neighneighbour to delete
flagsadditional 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 693 of file neigh.c.

Referenced by rtnl_neigh_delete().

695 {
696  return build_neigh_msg(neigh, RTM_DELNEIGH, flags);
697 }
int rtnl_neigh_delete ( struct nl_handle *  handle,
struct rtnl_neigh *  neigh,
int  flags 
)
Parameters
handlenetlink handle
neighneighbour to delete
flagsadditional 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 711 of file neigh.c.

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

713 {
714  int err;
715  struct nl_msg *msg;
716 
717  msg = rtnl_neigh_build_delete_request(neigh, flags);
718  if (!msg)
719  return nl_errno(ENOMEM);
720 
721  err = nl_send_auto_complete(handle, msg);
722  nlmsg_free(msg);
723  if (err < 0)
724  return err;
725 
726  return nl_wait_for_ack(handle);
727 }
int nl_wait_for_ack(struct nl_handle *handle)
Wait for ACK.
Definition: nl.c:801
void nlmsg_free(struct nl_msg *n)
Free a netlink message.
Definition: msg.c:656
int nl_send_auto_complete(struct nl_handle *handle, struct nl_msg *msg)
Send netlink message and check & extend header values as needed.
Definition: nl.c:373
struct nl_msg * rtnl_neigh_build_delete_request(struct rtnl_neigh *neigh, int flags)
Build a netlink request message to delete a neighbour.
Definition: neigh.c:693
struct nl_msg* rtnl_neigh_build_change_request ( struct rtnl_neigh *  neigh,
int  flags 
)
Parameters
neighthe neighbour to change
flagsadditional 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 750 of file neigh.c.

References NLM_F_REPLACE.

Referenced by rtnl_neigh_change().

752 {
753  return build_neigh_msg(neigh, RTM_NEWNEIGH, NLM_F_REPLACE | flags);
754 }
#define NLM_F_REPLACE
Replace existing matching config object with this request.
int rtnl_neigh_change ( struct nl_handle *  handle,
struct rtnl_neigh *  neigh,
int  flags 
)
Parameters
handlenetlink handle
neighneighbour to be changed
flagsadditional 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 770 of file neigh.c.

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

772 {
773  int err;
774  struct nl_msg *msg;
775 
776  msg = rtnl_neigh_build_change_request(neigh, flags);
777  if (!msg)
778  return nl_errno(ENOMEM);
779 
780  err = nl_send_auto_complete(handle, msg);
781  nlmsg_free(msg);
782  if (err < 0)
783  return err;
784 
785  return nl_wait_for_ack(handle);
786 }
int nl_wait_for_ack(struct nl_handle *handle)
Wait for ACK.
Definition: nl.c:801
void nlmsg_free(struct nl_msg *n)
Free a netlink message.
Definition: msg.c:656
int nl_send_auto_complete(struct nl_handle *handle, struct nl_msg *msg)
Send netlink message and check & extend header values as needed.
Definition: nl.c:373
struct nl_msg * rtnl_neigh_build_change_request(struct rtnl_neigh *neigh, int flags)
Build a netlink request message to change neighbour attributes.
Definition: neigh.c:750