BPF_MTAP(9) | Kernel Developer's Manual | BPF_MTAP(9)

# NAME

`bpfattach`, `bpfxattach`, `bpfdetach`, `bpfsattach`, `bpfsdetach`, `bpf_filter`, `bpf_mfilter`, `bpf_validate`, `bpf_mtap`, `bpf_mtap_hdr`, `bpf_mtap_af`, `bpf_mtap_ether`, `bpf_tap_hdr` — BPF kernel API

# SYNOPSIS

`#include <net/bpf.h>`

void
`bpfattach`(caddr_t *bpfp, struct ifnet *ifp, u_int dlt, u_int hdrlen);

void *
`bpfxattach`(caddr_t *bpfp, const char *name, struct ifnet *ifp, u_int dlt, u_int hdrlen);

void
`bpfdetach`(struct ifnet *ifp);

void *
`bpfsattach`(caddr_t *bpfp, const char *name, u_int dlt, u_int hdrlen);

void
`bpfsdetach`(void *bpfif);

u_int
`bpf_filter`(const struct bpf_insn *pc, const u_char *pkt, u_int wirelen, u_int pktlen);

u_int
`bpf_mfilter`(const struct bpf_insn *pc, const struct mbuf *m, u_int wirelen);

int
`bpf_validate`(struct bpf_insn *pc, int len);

int
`bpf_mtap`(caddr_t bpf, const struct mbuf *m, u_int direction);

int
`bpf_mtap_hdr`(caddr_t bpf, const void *hdr, u_int hdrlen, const struct mbuf *m, u_int direction);

int
`bpf_mtap_af`(caddr_t bpf, u_int32_t af, const struct mbuf *m, u_int direction);

int
`bpf_mtap_ether`(caddr_t bpf, const struct mbuf *m, u_int direction);

int
`bpf_tap_hdr`(caddr_t bpf, const void *hdr, u_int hdrlen, const void *buf, u_int buflen, u_int direction);

# DESCRIPTION

The BPF kernel API provides functions for evaluating BPF instructions against packets, and incoming linkage from device drivers. A packet is parsed by the filters associated with each interface and, if accepted, stashed into the corresponding buffer.

`bpfattach`() allocates and configures a BPF interface for use with the network interface ifp. bpfp is the location of BPF interface pointer that the network interface passes to the filter functions. The BPF interface pointer will be clear until a filter is registered and packets can be filtered on it. The dlt argument identifies the data link-layer type that the network interface provides for this BPF interface. `bpfattach`() may be called multiple times against the same network interface to provide different data link-layer types for filtering. hdrlen indicates the length of the link header for the data link-layer type.

`bpfxattach`() allocates and configures a BPF interface for use with the network interface ifp, but with a BPF interface name provided by the name argument instead of the name of the network interface. The bpfp, dlt, hdrlen arguments work like those in `bpfattach`().

`bpfdetach`() removes and frees all the BPF interfaces that were configured for the network interface ifp.

`bpfsattach`() allocates and configures a BPF interface for use by the subsystem identified by name. The bpfp, dlt, hdrlen arguments work like those in `bpfattach`().

`bpfsdetach`() removes and frees the BPF interface referenced by bpfif.

`bpf_filter`() executes the BPF program referenced by pc against the packet buffer starting at pkt of pktlen bytes in length. wirelen is the length of the original packet on the wire.

`bpf_mfilter`() executes the BPF program referenced by pc against the packet in the mbuf m. wirelen is the length of the original packet on the wire.

`bpf_validate`() tests if the BPF program referenced by pc is valid. len specifies the number of instructions in pc.

`bpf_tap`() runs the filters on the BPF interface referenced by bpf in the direction direction against the packet in the pkt buffer.

`bpf_mtap`() runs the filters on the BPF interface referenced by bpf in the direction direction against the packet in mbuf chain m.

`bpf_mtap_hdr`() runs the filters on the BPF interface referenced by bpf in the direction direction against the packet in mbuf chain m. The header referenced by hdr will be prefixed to the packet during filter evaluation.

`bpf_mtap_af`() runs the filters on the BPF interface referenced by bpf in the direction direction against the packet in mbuf chain m. The address family specified by af will be prepended to the packet before matching occurs.

`bpf_mtap_ether`() runs the filters on the BPF interface referenced by bpf in the direction direction against an Ethernet packet in the mbuf m. If the mbuf is flagged with `M_VLANTAG`, an Ethernet VLAN header is constructed using m->m_pkthdr.ether_vtag and m->m_pkthdr.pf.prio before matching occurs.

`bpf_tap_hdr`() runs the filters on the BPF interface referenced by bpf in the direction direction against the buffer buf of length buflen. The header hdr of length hdrlen will be prefixed to the buffer for filter evaluation.

# CONTEXT

`bpfattach`(), `bpfxattach`(), `bpfdetach`(), `bpfsattach`(), and `bpfsdetach`() can be called from process context.

`bpf_filter`(), `bpf_mfilter`(), and `bpf_validate`() can be called from process context, or from an interrupt context.

`bpf_mtap`(), `bpf_mtap_hdr`(), `bpf_mtap_af`(), `bpf_mtap_ether`(), and `bpf_tap_hdr`() can be called from process context, or from an interrupt context at or below `IPL_NET`.

# RETURN VALUES

`bpfsattach`() and `bpfxattach`() return a reference to the BPF interface they allocate.

`bpf_filter`() and `bpf_mfilter`() return -1 (cast to an unsigned integer) if the filter program is `NULL`, or the result of the filter program. Filter programs should return the maximum number of bytes of the packet to capture, or 0 if the packet does not match the filter program.

`bpf_validate`() returns a non-zero value if the BPF program is valid, otherwise 0.

`bpf_mtap`(), `bpf_mtap_hdr`(), `bpf_mtap_af`(), `bpf_mtap_ether`(), and `bpf_tap_hdr`() return 1 if the packet or buffer matched a filter that indicates it should be dropped, otherwise 0.

# SEE ALSO

mbuf(9), spl(9)

March 4, 2025 | Debian