bpf(4): Update the man page to reflect reality
PR: 131918 Submitted by: guy at alum dot mit dot edu Reviewed by: gnn, gbe Approved by: gnn MFC after: 2 weeks Differential Revision: https://reviews.freebsd.org/D25993
This commit is contained in:
Gordon Bergling
parent
6f6f0f286b
commit
b56d7f9663
@ -49,7 +49,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd October 21, 2016
|
||||
.Dd October 9, 2020
|
||||
.Dt BPF 4
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -73,12 +73,6 @@ ioctl.
|
||||
A given interface can be shared by multiple listeners, and the filter
|
||||
underlying each descriptor will see an identical packet stream.
|
||||
.Pp
|
||||
A separate device file is required for each minor device.
|
||||
If a file is in use, the open will fail and
|
||||
.Va errno
|
||||
will be set to
|
||||
.Er EBUSY .
|
||||
.Pp
|
||||
Associated with each open instance of a
|
||||
.Nm
|
||||
file is a user-settable packet filter.
|
||||
@ -86,19 +80,6 @@ Whenever a packet is received by an interface,
|
||||
all file descriptors listening on that interface apply their filter.
|
||||
Each descriptor that accepts the packet receives its own copy.
|
||||
.Pp
|
||||
The packet filter will support any link level protocol that has fixed length
|
||||
headers.
|
||||
Currently, only Ethernet,
|
||||
.Tn SLIP ,
|
||||
and
|
||||
.Tn PPP
|
||||
drivers have been modified to interact with
|
||||
.Nm .
|
||||
.Pp
|
||||
Since packet data is in network byte order, applications should use the
|
||||
.Xr byteorder 3
|
||||
macros to extract multi-byte values.
|
||||
.Pp
|
||||
A packet can be sent out on the network by writing to a
|
||||
.Nm
|
||||
file descriptor.
|
||||
@ -313,7 +294,7 @@ with
|
||||
If the requested buffer size cannot be accommodated, the closest
|
||||
allowable size will be set and returned in the argument.
|
||||
A read call will result in
|
||||
.Er EIO
|
||||
.Er EINVAL
|
||||
if it is passed a buffer that is not this size.
|
||||
.It Dv BIOCGDLT
|
||||
.Pq Li u_int
|
||||
@ -324,6 +305,43 @@ The device types, prefixed with
|
||||
.Dq Li DLT_ ,
|
||||
are defined in
|
||||
.In net/bpf.h .
|
||||
.It Dv BIOCGDLTLIST
|
||||
.Pq Li "struct bpf_dltlist"
|
||||
Returns an array of the available types of the data link layer
|
||||
underlying the attached interface:
|
||||
.Bd -literal -offset indent
|
||||
struct bpf_dltlist {
|
||||
u_int bfl_len;
|
||||
u_int *bfl_list;
|
||||
};
|
||||
.Ed
|
||||
.Pp
|
||||
The available types are returned in the array pointed to by the
|
||||
.Va bfl_list
|
||||
field while their length in u_int is supplied to the
|
||||
.Va bfl_len
|
||||
field.
|
||||
.Er ENOMEM
|
||||
is returned if there is not enough buffer space and
|
||||
.Er EFAULT
|
||||
is returned if a bad address is encountered.
|
||||
The
|
||||
.Va bfl_len
|
||||
field is modified on return to indicate the actual length in u_int
|
||||
of the array returned.
|
||||
If
|
||||
.Va bfl_list
|
||||
is
|
||||
.Dv NULL ,
|
||||
the
|
||||
.Va bfl_len
|
||||
field is set to indicate the required length of an array in u_int.
|
||||
.It Dv BIOCSDLT
|
||||
.Pq Li u_int
|
||||
Changes the type of the data link layer underlying the attached interface.
|
||||
.Er EINVAL
|
||||
is returned if no interface has been specified or the specified
|
||||
type is not available for the interface.
|
||||
.It Dv BIOCPROMISC
|
||||
Forces the interface into promiscuous mode.
|
||||
All packets, not just those destined for the local host, are processed.
|
||||
@ -331,6 +349,9 @@ Since more than one file can be listening on a given interface,
|
||||
a listener that opened its interface non-promiscuously may receive
|
||||
packets promiscuously.
|
||||
This problem can be remedied with an appropriate filter.
|
||||
.Pp
|
||||
The interface remains in promiscuous mode until all files listening
|
||||
promiscuously are closed.
|
||||
.It Dv BIOCFLUSH
|
||||
Flushes the buffer of incoming packets,
|
||||
and resets the statistics that are returned by BIOCGSTATS.
|
||||
@ -344,7 +365,7 @@ structure.
|
||||
All other fields are undefined.
|
||||
.It Dv BIOCSETIF
|
||||
.Pq Li "struct ifreq"
|
||||
Sets the hardware interface associate with the file.
|
||||
Sets the hardware interface associated with the file.
|
||||
This
|
||||
command must be performed before any packets can be read.
|
||||
The device is indicated by name using the
|
||||
@ -357,7 +378,7 @@ Additionally, performs the actions of
|
||||
.It Dv BIOCSRTIMEOUT
|
||||
.It Dv BIOCGRTIMEOUT
|
||||
.Pq Li "struct timeval"
|
||||
Set or get the read timeout parameter.
|
||||
Sets or gets the read timeout parameter.
|
||||
The argument
|
||||
specifies the length of time to wait before timing
|
||||
out on a read request.
|
||||
@ -387,7 +408,7 @@ kernel because of buffer overflows
|
||||
.El
|
||||
.It Dv BIOCIMMEDIATE
|
||||
.Pq Li u_int
|
||||
Enable or disable
|
||||
Enables or disables
|
||||
.Dq immediate mode ,
|
||||
based on the truth value of the argument.
|
||||
When immediate mode is enabled, reads return immediately upon packet
|
||||
@ -407,7 +428,7 @@ An array of instructions and its length is passed in using
|
||||
the following structure:
|
||||
.Bd -literal
|
||||
struct bpf_program {
|
||||
int bf_len;
|
||||
u_int bf_len;
|
||||
struct bpf_insn *bf_insns;
|
||||
};
|
||||
.Ed
|
||||
@ -469,10 +490,18 @@ An incompatible filter
|
||||
may result in undefined behavior (most likely, an error returned by
|
||||
.Fn ioctl
|
||||
or haphazard packet matching).
|
||||
.It Dv BIOCGRSIG
|
||||
.It Dv BIOCSRSIG
|
||||
.Pq Li u_int
|
||||
Sets or gets the receive signal.
|
||||
This signal will be sent to the process or process group specified by
|
||||
.Dv FIOSETOWN .
|
||||
It defaults to
|
||||
.Dv SIGIO .
|
||||
.It Dv BIOCSHDRCMPLT
|
||||
.It Dv BIOCGHDRCMPLT
|
||||
.Pq Li u_int
|
||||
Set or get the status of the
|
||||
Sets or gets the status of the
|
||||
.Dq header complete
|
||||
flag.
|
||||
Set to zero if the link level source address should be filled in automatically
|
||||
@ -489,7 +518,7 @@ Use
|
||||
and
|
||||
.Dv BIOCGDIRECTION
|
||||
instead.
|
||||
Set or get the flag determining whether locally generated packets on the
|
||||
Sets or gets the flag determining whether locally generated packets on the
|
||||
interface should be returned by BPF.
|
||||
Set to zero to see only incoming packets on the interface.
|
||||
Set to one to see packets originating locally and remotely on the interface.
|
||||
@ -497,7 +526,7 @@ This flag is initialized to one by default.
|
||||
.It Dv BIOCSDIRECTION
|
||||
.It Dv BIOCGDIRECTION
|
||||
.Pq Li u_int
|
||||
Set or get the setting determining whether incoming, outgoing, or all packets
|
||||
Sets or gets the setting determining whether incoming, outgoing, or all packets
|
||||
on the interface should be returned by BPF.
|
||||
Set to
|
||||
.Dv BPF_D_IN
|
||||
@ -631,6 +660,57 @@ therefore ownership is not assigned, the user process must check
|
||||
against
|
||||
.Vt bzh_user_gen .
|
||||
.El
|
||||
.Sh STANDARD IOCTLS
|
||||
.Nm
|
||||
now supports several standard
|
||||
.Xr ioctl 2 Ns 's
|
||||
which allow the user to do async and/or non-blocking I/O to an open
|
||||
.I bpf
|
||||
file descriptor.
|
||||
.Bl -tag -width SIOCGIFADDR
|
||||
.It Dv FIONREAD
|
||||
.Pq Li int
|
||||
Returns the number of bytes that are immediately available for reading.
|
||||
.It Dv SIOCGIFADDR
|
||||
.Pq Li "struct ifreq"
|
||||
Returns the address associated with the interface.
|
||||
.It Dv FIONBIO
|
||||
.Pq Li int
|
||||
Sets or clears non-blocking I/O.
|
||||
If arg is non-zero, then doing a
|
||||
.Xr read 2
|
||||
when no data is available will return -1 and
|
||||
.Va errno
|
||||
will be set to
|
||||
.Er EAGAIN .
|
||||
If arg is zero, non-blocking I/O is disabled.
|
||||
Note: setting this overrides the timeout set by
|
||||
.Dv BIOCSRTIMEOUT .
|
||||
.It Dv FIOASYNC
|
||||
.Pq Li int
|
||||
Enables or disables async I/O.
|
||||
When enabled (arg is non-zero), the process or process group specified by
|
||||
.Dv FIOSETOWN
|
||||
will start receiving
|
||||
.Dv SIGIO 's
|
||||
when packets arrive.
|
||||
Note that you must do an
|
||||
.Dv FIOSETOWN
|
||||
in order for this to take affect,
|
||||
as the system will not default this for you.
|
||||
The signal may be changed via
|
||||
.Dv BIOCSRSIG .
|
||||
.It Dv FIOSETOWN
|
||||
.It Dv FIOGETOWN
|
||||
.Pq Li int
|
||||
Sets or gets the process or process group (if negative) that should
|
||||
receive
|
||||
.Dv SIGIO
|
||||
when packets are available.
|
||||
The signal may be changed using
|
||||
.Dv BIOCSRSIG
|
||||
(see above).
|
||||
.El
|
||||
.Sh BPF HEADER
|
||||
One of the following structures is prepended to each packet returned by
|
||||
.Xr read 2
|
||||
@ -750,10 +830,10 @@ and implicit program counter.
|
||||
The following structure defines the instruction format:
|
||||
.Bd -literal
|
||||
struct bpf_insn {
|
||||
u_short code;
|
||||
u_char jt;
|
||||
u_char jf;
|
||||
u_long k;
|
||||
u_short code;
|
||||
u_char jt;
|
||||
u_char jf;
|
||||
bpf_u_int32 k;
|
||||
};
|
||||
.Ed
|
||||
.Pp
|
||||
@ -964,7 +1044,7 @@ variables controls the behaviour of the
|
||||
.Nm
|
||||
subsystem
|
||||
.Bl -tag -width indent
|
||||
.It Va net.bpf.optimize_writers: No 0
|
||||
.It Va net.bpf.optimize_writers : No 0
|
||||
Various programs use BPF to send (but not receive) raw packets
|
||||
(cdpd, lldpd, dhcpd, dhcp relays, etc. are good examples of such programs).
|
||||
They do not need incoming packets to be send to them.
|
||||
@ -973,20 +1053,20 @@ makes new BPF users to be attached to write-only interface list until program
|
||||
explicitly specifies read filter via
|
||||
.Fn pcap_set_filter .
|
||||
This removes any performance degradation for high-speed interfaces.
|
||||
.It Va net.bpf.stats:
|
||||
.It Va net.bpf.stats :
|
||||
Binary interface for retrieving general statistics.
|
||||
.It Va net.bpf.zerocopy_enable: No 0
|
||||
.It Va net.bpf.zerocopy_enable : No 0
|
||||
Permits zero-copy to be used with net BPF readers.
|
||||
Use with caution.
|
||||
.It Va net.bpf.maxinsns: No 512
|
||||
.It Va net.bpf.maxinsns : No 512
|
||||
Maximum number of instructions that BPF program can contain.
|
||||
Use
|
||||
.Xr tcpdump 1
|
||||
.Fl d
|
||||
option to determine approximate number of instruction for any filter.
|
||||
.It Va net.bpf.maxbufsize: No 524288
|
||||
.It Va net.bpf.maxbufsize : No 524288
|
||||
Maximum buffer size to allocate for packets buffer.
|
||||
.It Va net.bpf.bufsize: No 4096
|
||||
.It Va net.bpf.bufsize : No 4096
|
||||
Default buffer size to allocate for packets buffer.
|
||||
.El
|
||||
.Sh EXAMPLES
|
||||
@ -1052,7 +1132,6 @@ struct bpf_insn insns[] = {
|
||||
.Xr kqueue 2 ,
|
||||
.Xr poll 2 ,
|
||||
.Xr select 2 ,
|
||||
.Xr byteorder 3 ,
|
||||
.Xr ng_bpf 4 ,
|
||||
.Xr bpf 9
|
||||
.Rs
|
||||
@ -1101,8 +1180,6 @@ However, we favor the model where
|
||||
all files must assume that the interface is promiscuous, and if
|
||||
so desired, must utilize a filter to reject foreign packets.
|
||||
.Pp
|
||||
Data link protocols with variable length headers are not currently supported.
|
||||
.Pp
|
||||
The
|
||||
.Dv SEESENT ,
|
||||
.Dv DIRECTION ,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user