libnl: Neighbours

libnl 3.10.0

Functions
Neighbours
Routing Library (libnl-route)

## Functions
int | rtnl_neigh_parse (struct nlmsghdr *n, struct rtnl_neigh **result)

## 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)

## Neighbour Object Allocation/Freeage
struct rtnl_neigh * | rtnl_neigh_alloc (void)
void | rtnl_neigh_put (struct rtnl_neigh *neigh)

## Neighbour Cache Managament
int | rtnl_neigh_alloc_cache (struct nl_sock *sock, struct nl_cache **result)
| Build a neighbour cache including all neighbours currently configured in the kernel.
int | rtnl_neigh_alloc_cache_flags (struct nl_sock *sock, struct nl_cache **result, unsigned int flags)
| Build a neighbour cache including all neighbours currently configured in the kernel.
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.
struct rtnl_neigh * | rtnl_neigh_get_by_vlan (struct nl_cache *cache, int ifindex, struct nl_addr *lladdr, int vlan)
| Look up a neighbour by interface index, link layer address and vlan id.

## Neighbour Addition
int | rtnl_neigh_build_add_request (struct rtnl_neigh *tmpl, int flags, struct nl_msg **result)
| Build netlink request message to add a new neighbour.
int | rtnl_neigh_add (struct nl_sock *sk, struct rtnl_neigh *tmpl, int flags)
| Add a new neighbour.

## Neighbour Deletion
int | rtnl_neigh_build_delete_request (struct rtnl_neigh *neigh, int flags, struct nl_msg **result)
| Build a netlink request message to delete a neighbour.
int | rtnl_neigh_delete (struct nl_sock *sk, struct rtnl_neigh *neigh, int flags)
| Delete a neighbour.

## 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)
int | rtnl_neigh_get_family (struct rtnl_neigh *neigh)
void | rtnl_neigh_set_type (struct rtnl_neigh *neigh, int type)
int | rtnl_neigh_get_type (struct rtnl_neigh *neigh)
void | rtnl_neigh_set_vlan (struct rtnl_neigh *neigh, int vlan)
int | rtnl_neigh_get_vlan (struct rtnl_neigh *neigh)
void | rtnl_neigh_set_master (struct rtnl_neigh *neigh, int ifindex)
int | rtnl_neigh_get_master (struct rtnl_neigh *neigh)
void | rtnl_neigh_set_nhid (struct rtnl_neigh *neigh, uint32_t nhid)
int | rtnl_neigh_get_nhid (struct rtnl_neigh *neigh, uint32_t *out_val)

## 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_USE
  NTF_PROXY
  NTF_ROUTER
  NTF_SELF

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(sk);
  // 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);
  rtnl_neigh_alloc_cache
  int rtnl_neigh_alloc_cache(struct nl_sock *sock, struct nl_cache **result)
  Build a neighbour cache including all neighbours currently configured in the kernel.
  Definition neigh.c:628
  rtnl_neigh_get
  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.
  Definition neigh.c:673

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(sk, neigh, NLM_F_CREATE);
  // Free the memory
  rtnl_neigh_put(neigh);
  rtnl_neigh_add
  int rtnl_neigh_add(struct nl_sock *sk, struct rtnl_neigh *tmpl, int flags)
  Add a new neighbour.
  Definition neigh.c:817

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(sk, neigh, 0);
  // Free the memory
  rtnl_neigh_put(neigh);
  rtnl_neigh_delete
  int rtnl_neigh_delete(struct nl_sock *sk, struct rtnl_neigh *neigh, int flags)
  Delete a neighbour.
  Definition neigh.c:872

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_add(sk, neigh, NLM_F_REPLACE);
  // Free the memory
  rtnl_neigh_put(neigh);

## Function Documentation

## ◆ rtnl_neigh_parse()

int rtnl_neigh_parse | ( | struct nlmsghdr * | n,
|  | struct rtnl_neigh ** | result )

Definition at line 379 of file neigh.c.

## ◆ rtnl_neigh_alloc()

struct rtnl_neigh * rtnl_neigh_alloc | ( | void |  | ) |

Definition at line 601 of file neigh.c.

## ◆ rtnl_neigh_put()

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

Definition at line 606 of file neigh.c.

## ◆ rtnl_neigh_alloc_cache()

int rtnl_neigh_alloc_cache | ( | struct nl_sock * | sock,
|  | struct nl_cache ** | result )

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

Parameters

  sock | Netlink socket.
  result | Pointer to store resulting cache.

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

Returns
  0 on success or a negative error code.

Definition at line 628 of file neigh.c.

References nl_cache_alloc_and_fill().

Here is the call graph for this function:

## ◆ rtnl_neigh_alloc_cache_flags()

int rtnl_neigh_alloc_cache_flags | ( | struct nl_sock * | sock,
|  | struct nl_cache ** | result,
|  | unsigned int | flags )

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

Parameters

  sock | Netlink socket.
  result | Pointer to store resulting cache.
  flags | Flags to apply to cache before filling

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

Returns
  0 on success or a negative error code.

Definition at line 644 of file neigh.c.

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

Here is the call graph for this function:

## ◆ rtnl_neigh_get()

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 673 of file neigh.c.

References nl_addr_cmp(), and nl_object_get().

Here is the call graph for this function:

## ◆ rtnl_neigh_get_by_vlan()

struct rtnl_neigh * rtnl_neigh_get_by_vlan | ( | struct nl_cache * | cache,
|  | int | ifindex,
|  | struct nl_addr * | lladdr,
|  | int | vlan )

Look up a neighbour by interface index, link layer address and vlan id.

Parameters

  cache | neighbour cache
  ifindex | interface index the neighbour is on
  lladdr | link layer address of the neighbour
  vlan | vlan id of the neighbour

Returns
  neighbour handle or NULL if no match was found.

Definition at line 699 of file neigh.c.

References nl_addr_cmp(), and nl_object_get().

Here is the call graph for this function:

## ◆ rtnl_neigh_build_add_request()

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

Build netlink request message to add a new neighbour.

Parameters

  tmpl | template with data of new neighbour
  flags | additional netlink message flags
  result | Pointer to store resulting message.

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
  0 on success or a negative error code.

Definition at line 793 of file neigh.c.

Referenced by rtnl_neigh_add().

Here is the caller graph for this function:

## ◆ rtnl_neigh_add()

int rtnl_neigh_add | ( | struct nl_sock * | sk,
|  | struct rtnl_neigh * | tmpl,
|  | int | flags )

Add a new neighbour.

Parameters

  sk | Netlink socket.
  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:

- 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 success or a negative error if an error occured.

Definition at line 817 of file neigh.c.

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

Here is the call graph for this function:

## ◆ rtnl_neigh_build_delete_request()

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

Build a netlink request message to delete a neighbour.

Parameters

  neigh | neighbour to delete
  flags | additional netlink message flags
  result | Pointer to store resulting message.

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
  0 on success or a negative error code.

Definition at line 854 of file neigh.c.

Referenced by rtnl_neigh_delete().

Here is the caller graph for this function:

## ◆ rtnl_neigh_delete()

int rtnl_neigh_delete | ( | struct nl_sock * | sk,
|  | struct rtnl_neigh * | neigh,
|  | int | flags )

Delete a neighbour.

Parameters

  sk | Netlink socket.
  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 success or a negative error if an error occured.

Definition at line 872 of file neigh.c.

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

Here is the call graph for this function:

## ◆ rtnl_neigh_state2str()

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

Definition at line 912 of file neigh.c.

## ◆ rtnl_neigh_str2state()

int rtnl_neigh_str2state | ( | const char * | name | ) |

Definition at line 918 of file neigh.c.

## ◆ rtnl_neigh_flags2str()

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

Definition at line 940 of file neigh.c.

## ◆ rtnl_neigh_str2flag()

int rtnl_neigh_str2flag | ( | const char * | name | ) |

Definition at line 946 of file neigh.c.

## ◆ rtnl_neigh_set_state()

void rtnl_neigh_set_state | ( | struct rtnl_neigh * | neigh,
|  | int | state )

Definition at line 958 of file neigh.c.

## ◆ rtnl_neigh_get_state()

int rtnl_neigh_get_state | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 965 of file neigh.c.

## ◆ rtnl_neigh_unset_state()

void rtnl_neigh_unset_state | ( | struct rtnl_neigh * | neigh,
|  | int | state )

Definition at line 973 of file neigh.c.

## ◆ rtnl_neigh_set_flags()

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

Definition at line 980 of file neigh.c.

## ◆ rtnl_neigh_get_flags()

unsigned int rtnl_neigh_get_flags | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 987 of file neigh.c.

## ◆ rtnl_neigh_unset_flags()

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

Definition at line 992 of file neigh.c.

## ◆ rtnl_neigh_set_ifindex()

void rtnl_neigh_set_ifindex | ( | struct rtnl_neigh * | neigh,
|  | int | ifindex )

Definition at line 999 of file neigh.c.

## ◆ rtnl_neigh_get_ifindex()

int rtnl_neigh_get_ifindex | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 1005 of file neigh.c.

## ◆ rtnl_neigh_set_lladdr()

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

Definition at line 1034 of file neigh.c.

## ◆ rtnl_neigh_get_lladdr()

struct nl_addr * rtnl_neigh_get_lladdr | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 1039 of file neigh.c.

## ◆ rtnl_neigh_set_dst()

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

Definition at line 1047 of file neigh.c.

## ◆ rtnl_neigh_get_dst()

struct nl_addr * rtnl_neigh_get_dst | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 1053 of file neigh.c.

## ◆ rtnl_neigh_set_family()

void rtnl_neigh_set_family | ( | struct rtnl_neigh * | neigh,
|  | int | family )

Definition at line 1061 of file neigh.c.

## ◆ rtnl_neigh_get_family()

int rtnl_neigh_get_family | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 1067 of file neigh.c.

## ◆ rtnl_neigh_set_type()

void rtnl_neigh_set_type | ( | struct rtnl_neigh * | neigh,
|  | int | type )

Definition at line 1072 of file neigh.c.

## ◆ rtnl_neigh_get_type()

int rtnl_neigh_get_type | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 1078 of file neigh.c.

## ◆ rtnl_neigh_set_vlan()

void rtnl_neigh_set_vlan | ( | struct rtnl_neigh * | neigh,
|  | int | vlan )

Definition at line 1086 of file neigh.c.

## ◆ rtnl_neigh_get_vlan()

int rtnl_neigh_get_vlan | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 1092 of file neigh.c.

## ◆ rtnl_neigh_set_master()

void rtnl_neigh_set_master | ( | struct rtnl_neigh * | neigh,
|  | int | ifindex )

Definition at line 1100 of file neigh.c.

## ◆ rtnl_neigh_get_master()

int rtnl_neigh_get_master | ( | struct rtnl_neigh * | neigh | ) |

Definition at line 1106 of file neigh.c.

## ◆ rtnl_neigh_set_nhid()

void rtnl_neigh_set_nhid | ( | struct rtnl_neigh * | neigh,
|  | uint32_t | nhid )

Definition at line 1110 of file neigh.c.

## ◆ rtnl_neigh_get_nhid()

int rtnl_neigh_get_nhid | ( | struct rtnl_neigh * | neigh,
|  | uint32_t * | out_val )

Definition at line 1116 of file neigh.c.