Re: misc/40703: Fixes to the BPF(4) man page

[Guy Harris <guy%alum.mit.edu@localhost>]

The following reply was made to PR misc/40703; it has been noted by GNATS.

From: Guy Harris <guy%alum.mit.edu@localhost>
To: gnats-bugs%NetBSD.org@localhost
Cc: 
Subject: Re: misc/40703: Fixes to the BPF(4) man page
Date: Fri, 20 Feb 2009 14:28:15 -0800

 --Apple-Mail-4--836342457
 Content-Type: text/plain;
        charset=US-ASCII;
        format=flowed
 Content-Transfer-Encoding: 7bit
 
 Here's a patch:
 
 
 --Apple-Mail-4--836342457
 Content-Disposition: attachment;
        filename=patch
 Content-Type: application/octet-stream;
        x-unix-mode=0644;
        name="patch"
 Content-Transfer-Encoding: 7bit
 
 Index: bpf.4
 ===================================================================
 RCS file: /cvsroot/src/share/man/man4/bpf.4,v
 retrieving revision 1.39
 diff -c -r1.39 bpf.4
 *** bpf.4      4 Aug 2006 23:30:53 -0000       1.39
 --- bpf.4      20 Feb 2009 22:27:22 -0000
 ***************
 *** 43,49 ****
   .Pa /dev/bpf .
   After opening the device, the file descriptor must be bound to a
   specific network interface with the
 ! .Dv BIOSETIF
   ioctl.
   A given interface can be shared by multiple listeners, and the filter
   underlying each descriptor will see an identical packet stream.
 --- 43,49 ----
   .Pa /dev/bpf .
   After opening the device, the file descriptor must be bound to a
   specific network interface with the
 ! .Dv BIOCSETIF
   ioctl.
   A given interface can be shared by multiple listeners, and the filter
   underlying each descriptor will see an identical packet stream.
 ***************
 *** 62,79 ****
   .Nm .
   This size is returned by the
   .Dv BIOCGBLEN
 ! ioctl (see below), and under
 ! BSD, can be set with
   .Dv BIOCSBLEN .
   Note that an individual packet larger than this size is necessarily
   truncated.
   .Pp
 - The packet filter will support any link level protocol that has fixed length
 - headers.
 - Currently, only Ethernet, SLIP and 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.
 --- 62,72 ----
   .Nm .
   This size is returned by the
   .Dv BIOCGBLEN
 ! ioctl (see below), and can be set with
   .Dv BIOCSBLEN .
   Note that an individual packet larger than this size is necessarily
   truncated.
   .Pp
   Since packet data is in network byte order, applications should use the
   .Xr byteorder 3
   macros to extract multi-byte values.
 ***************
 *** 131,137 ****
   are defined in
   .Aq Pa net/bpf.h .
   .It Dv BIOCGDLTLIST (struct bpf_dltlist)
 ! Returns an array of available type of the data link layer
   underlying the attached interface:
   .Bd -literal -offset indent
   struct bpf_dltlist {
 --- 124,130 ----
   are defined in
   .Aq Pa net/bpf.h .
   .It Dv BIOCGDLTLIST (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 {
 ***************
 *** 140,152 ****
   };
   .Ed
   .Pp
 ! The available type is returned to the array pointed to the
   .Va bfl_list
 ! field while its length in u_int is supplied to the
   .Va bfl_len
   field.
   .Er ENOMEM
 ! is returned if there is not enough buffer.
   The
   .Va bfl_len
   field is modified on return to indicate the actual length in u_int
 --- 133,147 ----
   };
   .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
 ***************
 *** 157,165 ****
   .Dv NULL ,
   the
   .Va bfl_len
 ! field is returned to indicate the required length of an array in u_int.
   .It Dv BIOCSDLT (u_int)
 ! Change 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.
 --- 152,160 ----
   .Dv NULL ,
   the
   .Va bfl_len
 ! field is set to indicate the required length of an array in u_int.
   .It Dv BIOCSDLT (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.
 ***************
 *** 183,189 ****
   .Fa ifr .
   All other fields are undefined.
   .It Dv BIOCSETIF (struct ifreq)
 ! Sets the hardware interface associate with the file.
   This command must be performed before any packets can be read.
   The device is indicated by name using the
   .Dv ifr_name
 --- 178,184 ----
   .Fa ifr .
   All other fields are undefined.
   .It Dv BIOCSETIF (struct ifreq)
 ! 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
   .Dv ifr_name
 ***************
 *** 192,198 ****
   Additionally, performs the actions of
   .Dv BIOCFLUSH .
   .It Dv BIOCSRTIMEOUT, BIOCGRTIMEOUT (struct timeval)
 ! Set or get the read timeout parameter.
   The
   .Fa timeval
   specifies the length of time to wait before timing
 --- 187,193 ----
   Additionally, performs the actions of
   .Dv BIOCFLUSH .
   .It Dv BIOCSRTIMEOUT, BIOCGRTIMEOUT (struct timeval)
 ! Sets or gets the read timeout parameter.
   The
   .Fa timeval
   specifies the length of time to wait before timing
 ***************
 *** 225,231 ****
   the number of packets accepted by the filter.
   .El
   .It Dv BIOCIMMEDIATE (u_int)
 ! Enable or disable
   .Dq immediate mode ,
   based on the truth value of the argument.
   When immediate mode is enabled, reads return immediately upon packet
 --- 220,226 ----
   the number of packets accepted by the filter.
   .El
   .It Dv BIOCIMMEDIATE (u_int)
 ! Enables or disables
   .Dq immediate mode ,
   based on the truth value of the argument.
   When immediate mode is enabled, reads return immediately upon packet
 ***************
 *** 239,245 ****
   .It Dv BIOCSETF (struct bpf_program)
   Sets the filter program used by the kernel to discard uninteresting
   packets.
 ! An array of instructions and its length is passed in using the following 
structure:
   .Bd -literal -offset indent
   struct bpf_program {
        u_int bf_len;
 --- 234,240 ----
   .It Dv BIOCSETF (struct bpf_program)
   Sets the filter program used by the kernel to discard uninteresting
   packets.
 ! An array of instructions and its length are passed in using the following 
structure:
   .Bd -literal -offset indent
   struct bpf_program {
        u_int bf_len;
 ***************
 *** 286,298 ****
   may result in undefined behavior (most likely, an error returned by
   .Xr ioctl 2
   or haphazard packet matching).
   .It Dv BIOCGHDRCMPLT BIOCSHDRCMPLT (u_int)
 ! Enable/disable or get the
   .Dq header complete
 ! flag status.
 ! If enabled, packets written to the bpf file descriptor will not have
 ! network layer headers rewritten in the interface output routine.
 ! By default, the flag is disabled (value is 0).
   .It Dv BIOCGSEESENT BIOCSSEESENT (u_int)
   Enable/disable or get the
   .Dq see sent
 --- 281,301 ----
   may result in undefined behavior (most likely, an error returned by
   .Xr ioctl 2
   or haphazard packet matching).
 + .It Dv BIOCSRSIG BIOCGRSIG (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 BIOCGHDRCMPLT BIOCSHDRCMPLT (u_int)
 ! 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 by the interface output routine.
 ! Set to one if the link level source address will be written,
 ! as provided, to the wire.
 ! This flag is initialized to zero by default.
   .It Dv BIOCGSEESENT BIOCSSEESENT (u_int)
   Enable/disable or get the
   .Dq see sent
 ***************
 *** 355,361 ****
   };
   .Ed
   .Pp
 ! The fields, whose values are stored in host order, and are:
   .Bl -tag -width bh_datalen -offset indent
   .It Va bh_tstamp
   The time at which the packet was processed by the packet filter.
 --- 358,364 ----
   };
   .Ed
   .Pp
 ! The fields, whose values are stored in host order, are:
   .Bl -tag -width bh_datalen -offset indent
   .It Va bh_tstamp
   The time at which the packet was processed by the packet filter.
 ***************
 *** 429,437 ****
   .Bd -literal -offset indent
   struct bpf_insn {
        uint16_t code;
 !      u_char  jt;
 !      u_char  jf;
 !      int32_t k;
   };
   .Ed
   .Pp
 --- 432,440 ----
   .Bd -literal -offset indent
   struct bpf_insn {
        uint16_t code;
 !      u_char   jt;
 !      u_char   jf;
 !      uint32_t k;
   };
   .Ed
   .Pp
 ***************
 *** 477,483 ****
   The type of the source operand is specified by an
   .Dq addressing mode
   and can be a constant
 ! .Sy ( BBPF_IMM ) ,
   packet data at a fixed offset
   .Sy ( BPF_ABS ) ,
   packet data at a variable offset
 --- 480,486 ----
   The type of the source operand is specified by an
   .Dq addressing mode
   and can be a constant
 ! .Sy ( BPF_IMM ) ,
   packet data at a fixed offset
   .Sy ( BPF_ABS ) ,
   packet data at a variable offset
 ***************
 *** 735,742 ****
   all files must assume that the interface is promiscuous, and if
   so desired, must use a filter to reject foreign packets.
   .Pp
 - Data link protocols with variable length headers are not currently supported.
 - .Pp
   Under SunOS, if a BPF application reads more than 2^31 bytes of
   data, read will fail in
   .Er EINVAL .
 --- 738,743 ----
 
 --Apple-Mail-4--836342457
 Content-Type: text/plain;
        charset=US-ASCII;
        format=flowed
 Content-Transfer-Encoding: 7bit
 
 
 
 --Apple-Mail-4--836342457--