Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
BPF(9)			    Kernel Developer's Manual			  BPF(9)

NAME
     bpf -- Berkeley Packet Filter

SYNOPSIS
     #include <net/bpf.h>

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

     void
     bpfattach2(struct ifnet *ifp, u_int dlt, u_int hdrlen,
	 struct bpf_if **driverp);

     void
     bpfdetach(struct ifnet *ifp);

     void
     bpf_tap(struct ifnet *ifp, u_char *pkt, u_int *pktlen);

     void
     bpf_mtap(struct ifnet *ifp, struct mbuf *m);

     void
     bpf_mtap2(struct bpf_if *bp, void *data, u_int dlen, struct mbuf *m);

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

     int
     bpf_validate(const struct bpf_insn *fcode, int flen);

DESCRIPTION
     The Berkeley Packet Filter provides a raw interface, that is protocol inde-
     pendent,  to  data link layers.  It allows all packets on the network, even
     those destined for other hosts, to be passed from a  network  interface  to
     user  programs.   Each  program  may specify a filter, in the form of a bpf
     filter machine program.  The bpf(4) manual  page  describes  the  interface
     used  by  user  programs.	This manual page describes the functions used by
     interfaces to pass packets to bpf and the functions for testing and running
     bpf filter machine programs.

     The bpfattach() function attaches a network interface to bpf.  The ifp  ar-
     gument  is  a pointer to the structure that defines the interface to be at-
     tached to an interface.  The dlt argument	is  the  data  link-layer  type:
     DLT_NULL	 (no	link-layer    encapsulation),	DLT_EN10MB   (Ethernet),
     DLT_IEEE802_11 (802.11 wireless networks), etc.  The rest of the link layer
     types can be found in <net/bpf.h>.  The hdrlen argument is the  fixed  size
     of the link header; variable length headers are not yet supported.  The bpf
     system  will  hold  a  pointer to ifp->if_bpf.  This variable will set to a
     non-NULL value when bpf requires packets from this interface to  be  tapped
     using the functions below.

     The bpfattach2() function allows multiple bpf instances to be attached to a
     single  interface,  by  registering  an  explicit	if_bpf rather than using
     ifp->if_bpf.  It is then possible to run tcpdump(1) on  the  interface  for
     any data link-layer types attached.

     The  bpfdetach() function detaches a bpf instance from an interface, speci-
     fied by ifp.  The bpfdetach() function should be called once for  each  bpf
     instance attached.

     The  bpf_tap()  function is used by an interface to pass the packet to bpf.
     The packet data (including link-header), pointed to by pkt,  is  of  length
     pktlen,  which  must be a contiguous buffer.  The ifp argument is a pointer
     to the structure that defines the interface to be tapped.	 The  packet  is
     parsed  by  each  processes filter, and if accepted, it is buffered for the
     process to read.

     The bpf_mtap() function is like bpf_tap() except that it  is  used  to  tap
     packets that are in an mbuf chain, m.  The ifp argument is a pointer to the
     structure	that  defines  the  interface  to  be  tapped.	 Like bpf_tap(),
     bpf_mtap() requires a link-header for whatever  data  link  layer	type  is
     specified.   Note that bpf only reads from the mbuf chain, it does not free
     it or keep a pointer to it.  This means that an mbuf containing  the  link-
     header  can be prepended to the chain if necessary.  A cleaner interface to
     achieve this is provided by bpf_mtap2().

     The bpf_mtap2() function allows the user to pass  a  link-header  data,  of
     length  dlen,  independent of the mbuf m, containing the packet.  This sim-
     plifies the passing of some link-headers.

     The bpf_filter() function executes the filter program starting at pc on the
     packet pkt.  The wirelen argument is the length of the original packet  and
     buflen is the amount of data present.  The buflen value of 0 is special; it
     indicates	that the pkt is actually a pointer to an mbuf chain (struct mbuf
     *).

     The bpf_validate() function checks that the filter code  fcode,  of  length
     flen, is valid.

RETURN VALUES
     The bpf_filter() function returns -1 (cast to an unsigned integer) if there
     is no filter.  Otherwise, it returns the result of the filter program.

     The  bpf_validate() function returns 0 when the program is not a valid fil-
     ter program.

EVENT HANDLERS
     bpf invokes bpf_track EVENTHANDLER(9) event each time listener attaches  to
     or  detaches  from  an interface.	Pointer to (struct ifnet *) is passed as
     the first argument, interface dlt follows.  Last  argument  indicates  lis-
     tener  is	attached (1) or detached (0).  Note that handler is invoked with
     bpf global lock held, which implies restriction on sleeping and calling bpf
     subsystem inside EVENTHANDLER(9) dispatcher.   Note  that	handler  is  not
     called for write-only listeners.

SEE ALSO
     tcpdump(1), bpf(4), EVENTHANDLER(9)

HISTORY
     The  Enet packet filter was created in 1980 by Mike Accetta and Rick Rashid
     at Carnegie-Mellon University.  Jeffrey Mogul, at Stanford, ported the code
     to BSD and continued its development from 1983  on.   Since  then,  it  has
     evolved  into  the  Ultrix Packet Filter at DEC, a STREAMS NIT module under
     SunOS 4.1, and BPF.

AUTHORS
     Steven McCanne, of Lawrence Berkeley Laboratory, implemented BPF in  Summer
     1990.  Much of the design is due to Van Jacobson.	This manpage was written
     by Orla McGann.

FreeBSD ports 15.1		  May 11, 2012				  BPF(9)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=bpf&sektion=9&manpath=FreeBSD+15.1-RELEASE+and+Ports>

home | help