# `Linx.Netlink.Rtnl.Neighbour`
[🔗](https://github.com/oshlabs/linx/blob/v0.2.0/lib/linx/netlink/rtnl/neighbour.ex#L1)

rtnetlink neighbours — the kernel's ARP (IPv4) and NDP (IPv6) tables.

A neighbour entry maps an IP address to a link-layer (MAC) address on a
given interface. `list/1` and `list/2` read entries; `add/4` and `delete/3`
install and remove them.

`%Neighbour{}.dst` is a `Linx.IP`; `:lladdr` is a `Linx.MAC`. Verbs accept
either strings or the corresponding structs.

## Example

    {:ok, sock} = Rtnl.open()

    # A static ARP entry: 10.0.0.1 lives at this MAC on eth0.
    :ok = Neighbour.add(sock, "eth0", "10.0.0.1", "52:54:00:ab:cd:ef")

    {:ok, neighs} = Neighbour.list(sock, "eth0")
    # => [#Linx.Netlink.Rtnl.Neighbour<10.0.0.1 -> 52:54:00:ab:cd:ef ifindex=2>]

    :ok = Neighbour.delete(sock, "eth0", "10.0.0.1")

The wire format — `struct ndmsg` and the `NDA_*` attributes
(`include/uapi/linux/neighbour.h`) — is declared with the
`Linx.Netlink.Codec` DSL.

# `t`

```elixir
@type t() :: %Linx.Netlink.Rtnl.Neighbour{
  dst: term(),
  family: term(),
  flags: term(),
  ifindex: term(),
  lladdr: term(),
  state: term(),
  type: term()
}
```

# `add`

```elixir
@spec add(
  Linx.Netlink.Socket.t(),
  binary(),
  binary() | Linx.IP.t(),
  binary() | Linx.MAC.t()
) ::
  :ok | {:error, term()}
```

Adds a permanent neighbour entry — `ip` resolves to `mac` on `link_name`.

`ip` may be a string or `Linx.IP`; `mac` may be a string or `Linx.MAC`.

# `decode`

```elixir
@spec decode(binary()) :: t()
```

Decodes a netlink message body into a `t:t/0`.

# `delete`

```elixir
@spec delete(Linx.Netlink.Socket.t(), binary(), binary() | Linx.IP.t()) ::
  :ok | {:error, term()}
```

Removes the neighbour entry for `ip` on link `link_name`.

# `encode`

```elixir
@spec encode(t()) :: binary()
```

Encodes a `t:t/0` into its netlink message body.

# `list`

```elixir
@spec list(Linx.Netlink.Socket.t()) :: {:ok, [t()]} | {:error, term()}
```

Lists every neighbour entry in the socket's network namespace.

# `list`

```elixir
@spec list(Linx.Netlink.Socket.t(), binary()) :: {:ok, [t()]} | {:error, term()}
```

Lists the neighbour entries on link `link_name`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*