docs/131918: Fixes for the BPF(4) man page

Guy Harris guy at alum.mit.edu
Sat Feb 21 04:00:07 UTC 2009


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

From: Guy Harris <guy at alum.mit.edu>
To: FreeBSD-gnats-submit at FreeBSD.org
Cc:  
Subject: Re: docs/131918: Fixes for the BPF(4) man page
Date: Fri, 20 Feb 2009 19:31:03 -0800

 --Apple-Mail-5--818174167
 Content-Type: text/plain;
 	charset=US-ASCII;
 	format=flowed;
 	delsp=yes
 Content-Transfer-Encoding: 7bit
 
 While we're at it, we might as well remove
 
 	Since packet data is in network byte order, applications should use  
 the byteorder(3) macros to extract multi-byte values.
 
 because, in fact, not all packet data *is* in network byte order (SMB  
 fields, for example, are little-endian).
 
 I've attached an updated patch.
 
 
 --Apple-Mail-5--818174167
 Content-Disposition: attachment;
 	filename=patch2.txt
 Content-Type: text/plain;
 	x-unix-mode=0644;
 	name="patch2.txt"
 Content-Transfer-Encoding: 7bit
 
 Index: bpf.4
 ===================================================================
 RCS file: /home/ncvs/src/share/man/man4/bpf.4,v
 retrieving revision 1.52
 diff -c -r1.52 bpf.4
 *** bpf.4	13 Aug 2008 17:45:06 -0000	1.52
 --- bpf.4	21 Feb 2009 03:25:52 -0000
 ***************
 *** 73,84 ****
   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.
 --- 73,78 ----
 ***************
 *** 86,104 ****
   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.
 --- 80,85 ----
 ***************
 *** 288,300 ****
   and
   .In net/if.h .
   .Pp
 - In addition to
 - .Dv FIONREAD
 - and
 - .Dv SIOCGIFADDR ,
 - the following commands may be applied to any open
 - .Nm
 - file.
   The (third) argument to
   .Xr ioctl 2
   should be a pointer to the type indicated.
 --- 269,274 ----
 ***************
 *** 315,321 ****
   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
   if it is passed a buffer that is not this size.
   .It Dv BIOCGDLT
   .Pq Li u_int
 --- 289,295 ----
   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 EINVAL
   if it is passed a buffer that is not this size.
   .It Dv BIOCGDLT
   .Pq Li u_int
 ***************
 *** 326,331 ****
 --- 300,342 ----
   .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.
 ***************
 *** 333,338 ****
 --- 344,352 ----
   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.
 ***************
 *** 346,352 ****
   All other fields are undefined.
   .It Dv BIOCSETIF
   .Pq Li "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
 --- 360,366 ----
   All other fields are undefined.
   .It Dv BIOCSETIF
   .Pq Li "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
 ***************
 *** 359,365 ****
   .It Dv BIOCSRTIMEOUT
   .It Dv BIOCGRTIMEOUT
   .Pq Li "struct timeval"
 ! Set or get the read timeout parameter.
   The argument
   specifies the length of time to wait before timing
   out on a read request.
 --- 373,379 ----
   .It Dv BIOCSRTIMEOUT
   .It Dv BIOCGRTIMEOUT
   .Pq Li "struct timeval"
 ! Sets or gets the read timeout parameter.
   The argument
   specifies the length of time to wait before timing
   out on a read request.
 ***************
 *** 389,395 ****
   .El
   .It Dv BIOCIMMEDIATE
   .Pq Li 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
 --- 403,409 ----
   .El
   .It Dv BIOCIMMEDIATE
   .Pq Li 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
 ***************
 *** 409,415 ****
   the following structure:
   .Bd -literal
   struct bpf_program {
 ! 	int bf_len;
   	struct bpf_insn *bf_insns;
   };
   .Ed
 --- 423,429 ----
   the following structure:
   .Bd -literal
   struct bpf_program {
 ! 	u_int bf_len;
   	struct bpf_insn *bf_insns;
   };
   .Ed
 ***************
 *** 471,480 ****
   may result in undefined behavior (most likely, an error returned by
   .Fn ioctl
   or haphazard packet matching).
   .It Dv BIOCSHDRCMPLT
   .It Dv BIOCGHDRCMPLT
   .Pq Li u_int
 ! Set or get the status of the
   .Dq header complete
   flag.
   Set to zero if the link level source address should be filled in automatically
 --- 485,502 ----
   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
 ! 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
 ***************
 *** 491,497 ****
   and
   .Dv BIOCGDIRECTION
   instead.
 ! Set or get 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.
 --- 513,519 ----
   and
   .Dv BIOCGDIRECTION
   instead.
 ! 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.
 ***************
 *** 499,505 ****
   .It Dv BIOCSDIRECTION
   .It Dv BIOCGDIRECTION
   .Pq Li u_int
 ! Set or get the setting determining whether incoming, outgoing, or all packets
   on the interface should be returned by BPF.
   Set to
   .Dv BPF_D_IN
 --- 521,527 ----
   .It Dv BIOCSDIRECTION
   .It Dv BIOCGDIRECTION
   .Pq Li u_int
 ! 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
 ***************
 *** 515,526 ****
   by default.
   .It Dv BIOCFEEDBACK
   .Pq Li u_int
 ! Set packet feedback mode.
   This allows injected packets to be fed back as input to the interface when
   output via the interface is successful.
   When
   .Dv BPF_D_INOUT
 ! direction is set, injected outgoing packet is not returned by BPF to avoid
   duplication. This flag is initialized to zero by default.
   .It Dv BIOCLOCK
   Set the locked flag on the
 --- 537,548 ----
   by default.
   .It Dv BIOCFEEDBACK
   .Pq Li u_int
 ! Sets packet feedback mode.
   This allows injected packets to be fed back as input to the interface when
   output via the interface is successful.
   When
   .Dv BPF_D_INOUT
 ! direction is set, injected outgoing packets are not returned by BPF to avoid
   duplication. This flag is initialized to zero by default.
   .It Dv BIOCLOCK
   Set the locked flag on the
 ***************
 *** 574,579 ****
 --- 596,653 ----
   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
   The following structure is prepended to each packet returned by
   .Xr read 2
 ***************
 *** 581,594 ****
   .Bd -literal
   struct bpf_hdr {
           struct timeval bh_tstamp;     /* time stamp */
 !         u_long bh_caplen;             /* length of captured portion */
 !         u_long bh_datalen;            /* original length of packet */
           u_short bh_hdrlen;            /* length of bpf header (this struct
   					 plus alignment padding */
   };
   .Ed
   .Pp
 ! The fields, whose values are stored in host order, and are:
   .Pp
   .Bl -tag -compact -width bh_datalen
   .It Li bh_tstamp
 --- 655,668 ----
   .Bd -literal
   struct bpf_hdr {
           struct timeval bh_tstamp;     /* time stamp */
 !         bpf_u_int32 bh_caplen;        /* length of captured portion */
 !         bpf_u_int32 bh_datalen;       /* original length of packet */
           u_short bh_hdrlen;            /* length of bpf header (this struct
   					 plus alignment padding */
   };
   .Ed
   .Pp
 ! The fields, whose values are stored in host order, are:
   .Pp
   .Bl -tag -compact -width bh_datalen
   .It Li bh_tstamp
 ***************
 *** 666,675 ****
   The following structure defines the instruction format:
   .Bd -literal
   struct bpf_insn {
 ! 	u_short	code;
 ! 	u_char 	jt;
 ! 	u_char 	jf;
 ! 	u_long k;
   };
   .Ed
   .Pp
 --- 740,749 ----
   The following structure defines the instruction format:
   .Bd -literal
   struct bpf_insn {
 ! 	u_short     code;
 ! 	u_char      jt;
 ! 	u_char      jf;
 ! 	bpf_u_int32 k;
   };
   .Ed
   .Pp
 ***************
 *** 946,952 ****
   .Xr kqueue 2 ,
   .Xr poll 2 ,
   .Xr select 2 ,
 - .Xr byteorder 3 ,
   .Xr ng_bpf 4 ,
   .Xr bpf 9
   .Rs
 --- 1020,1025 ----
 ***************
 *** 995,1002 ****
   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 ,
 --- 1068,1073 ----
 
 --Apple-Mail-5--818174167
 Content-Type: text/plain;
 	charset=US-ASCII;
 	format=flowed
 Content-Transfer-Encoding: 7bit
 
 
 
 --Apple-Mail-5--818174167--



More information about the freebsd-doc mailing list