svn commit: r366580 - head/share/man/man4
Gordon Bergling
gbe at FreeBSD.org
Fri Oct 9 15:50:51 UTC 2020
Author: gbe (doc committer)
Date: Fri Oct 9 15:50:50 2020
New Revision: 366580
URL: https://svnweb.freebsd.org/changeset/base/366580
Log:
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
Modified:
head/share/man/man4/bpf.4
Modified: head/share/man/man4/bpf.4
==============================================================================
--- head/share/man/man4/bpf.4 Fri Oct 9 15:45:34 2020 (r366579)
+++ head/share/man/man4/bpf.4 Fri Oct 9 15:50:50 2020 (r366580)
@@ -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 i
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 u
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
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 inter
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
@@ -1100,8 +1179,6 @@ This could be fixed in the kernel with additional proc
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 ,
More information about the svn-src-all
mailing list