packetfilter.4

来自「<B>Digital的Unix操作系统VAX 4.2源码</B>」· 4 代码 · 共 1,077 行 · 第 1/2 页

.br
.ne .5i
.IP ens_count
.br
The length of the packet in bytes (does not include the
.PN enstamp
header).
.br
.ne .5i
.IP ens_dropped
.br
The number of packets accepted by this filter but dropped because the input
queue was full; this is a cumulative count since the previous
.PN enstamp
was read from this
packet filter
file.  This count may be completely wrong if the ENNONEXCL mode
bit is set for this filter.
.br
.ne .5i
.IP ens_ifoverflows
.br
The total number of input overflows reported by the network interface since the
system was booted.
.br
.ne .5i
.IP ens_tstamp
.br
The approximate time the packet was received.
.br
.PP
If the buffer returned by a batched
.MS read 2
contains more than one packet, the offset from the beginning of the buffer
at which each
.PN enstamp
structure begins is an integer multiple of the word-size of the processor.
For example, on a VAX, each
.PN enstamp
is aligned on a longword boundary (provided that the buffer address passed to
the
.MS read 2
system call is aligned).
The alignment (in units of bytes) is given by the constant
.PN ENALIGNMENT ,
defined in
.PN <net/pfilt.h> .
If you have an integer
.IR x ,
you can use the macro
\f(CWENALIGN(\fIx\fP)\fR
to get the least integer that is a multiple of
.PN ENALIGNMENT
and not less than
\fIx\fR.
For example, this code fragment reads and processes one batch:
.ne 1i
.EX
char *buffer = &(BigBuffer[0]);
int buflen;
int pktlen, stamplen;
struct enstamp *stamp;

buflen = read(f, buffer, sizeof(BigBuffer));
while (buflen > 0) {
    stamp = (struct enstamp *)buffer;
    pktlen = stamp->ens_count;
    stamplen = stamp->ens_stamplen;
    ProcessPacket(&(buffer[stamplen]), pktlen);   /* your code here */
    if (buflen == (pktlen + stamplen))
        break;                             /* last packet in batch */
    pktlen = ENALIGN(pktlen);     /* account for alignment padding */
    buflen -= (pktlen + stamplen);
    buffer += (pktlen + stamplen);          /* move to next stamp */
}
.EE
.PP
If a buffer filled by a batched read
contains more than one packet, the final packet is never truncated.
If, however, the entire buffer is not big enough to contain a single
packet, the packet will be truncated; this is also true for unbatched
reads.  Therefore, the buffer passed to the
.MS read 2
system call should always be big enough to hold the largest
possible packet plus an
.PN enstamp
structure.
(See the 
.PN EIOCDEVP
.PN ioctl
request later in this reference page for 
information on how to determine the maximum packet
size.  See also the
.PN EIOCTRUNCATE
.PN ioctl
request for an example that delivers only the desired
number of bytes of a packet.)
.ne 1.5i
.PP
Normally, a packet filter application blocks in the
.PN read
system call until a received packet is available for reading.
There are several ways to avoid blocking indefinitely: an application
can use the
.MS select 2
system call, it can set a ``timeout'' for the packet filter file,
or it can request the delivery of a signal (see
.MS sigvec 2 )
when a packet matches the filter.
.ne 1i
.i0
.DT
.PP
.IP EIOCSETW
.br
The packet filter interface limits the number of packets that can
be queued for delivery for a specific packet filter file.  Application
programs can vary this ``backlog'', if necessary, using the
following call:
.EX
ioctl(\fIfildes\fP, EIOCSETW, \fImaxwaitingp\fP)
u_int *\fImaxwaitingp\fP;
.EE
The argument
.I maxwaitingp
points to an integer containing
the input queue size to be set.
If this is greater than the maximum allowable
size (see EIOCMAXBACKLOG later), it is set to the maximum.
If it is zero, it is set to a default value.
.br
.ne 1i
.IP EIOCFLUSH
.br
After changing the packet filter program, the input queue may contain packets
that were accepted under the old filter.
To flush the queue of incoming packets, use the following:
.EX
ioctl(\fIfildes\fP, EIOCFLUSH, 0)
.EE
.ne 1i
.IP EIOCTRUNCATE
.br
An application, such as a network load monitor, that does not want to
see the entire packet can ask the packet filter to truncate
received packets at a specified length. This action may improve performance
by reducing data movement.  
.sp .5
To specify truncation, use:
.EX
ioctl(\fIfildes\fP, EIOCTRUNCATE, \fItruncationp\fP)
u_int *\fItruncationp\fP;
.EE
The argument
.I truncationp
points to an integer specifying the truncation length, in bytes.
Packets shorter than this length are passed intact.
.PP
This example, a revision of the previous example, illustrates
the use of EIOCTRUNCATE, which causes the packet filter to
deliver only the first \fIn\fR bytes of a packet, not the
entire packet.
.ne 1i
.EX
char *buffer = &(BigBuffer[0]);
int buflen;
int pktlen, stamplen;
struct enstamp *stamp;
int truncation = SIZE_OF_INTERESTING_PART_OF_PACKET;

if (ioctl(f, EIOCTRUNCATE, &truncation) < 0)
    exit(1);
    
while (1) {
    buflen = read(f, buffer, sizeof(BigBuffer));
    while (buflen > 0) {
       stamp = (struct enstamp *)buffer;
       pktlen = stamp->ens_count;     /* ens_count is untruncated length */
       stamplen = stamp->ens_stamplen; 
.sp .5
       ProcessPacket(&(buffer[stamplen]), pktlen);     /* your code here */
.sp .5
       if (pktlen > truncation)       /* truncated portion not in buffer */
           pktlen = truncation;
       if (buflen == (pktlen + stamplen))
           break;                                /* last packet in batch */
       pktlen = ENALIGN(pktlen);        /* account for alignment padding */
       buflen -= (pktlen + stamplen);
       buffer += (pktlen + stamplen);              /* move to next stamp */
   }
}

.EE
.PP
Two calls control the timeout mechanism; they are of the following
form:
.EX
#include <net/time.h>
.sp .5
ioctl(\fIfildes\fP, \fIcode\fP, \fItvp\fP)
.sp .5
struct timeval *\fItvp\fP;
.EE
.DT
.i0
.PP
The
.I tvp
argument is the address of a
.PN struct
.PN timeval
containing the timeout interval (this is a relative
value, not an absolute time).  The codes are:
.IP EIOCGRTIMEOUT
.br
Returns the current timeout value.
.br
.ne 4
.IP EIOCSRTIMEOUT
.br
Sets the timeout value.
When the value is
positive, a
.MS read 2
call returns a 0 if no packet arrives during the period.
When the timeout value is zero, reads block indefinitely (this
is the default).  When the value is negative, a
.MS read 2
call returns a 0 immediately if there are no queued packets.
Note that the largest legal timeout value
is a few million seconds.
.PP
Two calls control the signal-on-reception mechanism;
they are of the following form:
.EX
ioctl(\fIfildes\fP, \fIcode\fP, \fIsignp\fP)
u_int *\fIsignp\fP;
.EE
.PP
The argument
.I signp
is a pointer to an integer containing the number
of the signal
to be sent when an input packet arrives.
The applicable
.I codes
are:
.br
.ne 6
.IP EIOCENBS
.br
Enables the specified signal when an input packet
is received for this file.
If the ENHOLDSIG flag (see EIOCMBIS later) is not set,
further signals are automatically disabled
whenever a signal is sent to prevent nesting, and hence
must be explicitly re-enabled after processing.
When the signal number is 0,
this call is equivalent to EIOCINHS.
.IP EIOCINHS
.br
Disables signaling on packet reception.
The
.I signp
argument
is ignored.
This is the default when the file is first opened.
.ne 1i
.SS Device Configuration ioctl Requests
.IP EIOCIFNAME
.br
Each packet filter file is associated with a specific network interface.
To find out the name of the interface underlying the
packet filter file, use the following:
.EX
#include <net/socket.h>
#include <net/if.h>
.sp
ioctl(\fIfildes\fP, EIOCIFNAME, \fIifr\fP)
struct ifreq *\fIifr\fP;
.EE
The interface name (for example, ``de0'') is returned in
.I ifr->ifr_name\fR;
other fields of the
.I struct ifreq
are not set.
.IP EIOCSETIF
.br
To set the interface associated with a packet filter file, use
the following:
.EX
ioctl(\fIfildes\fP, EIOCSETIF, \fIifr\fP)
struct ifreq *\fIifr\fP;
.EE
.sp .5
The interface name should be passed
.I ifr->ifr_name\fR;
other fields of the
.I struct ifreq
are ignored.
The name provided may be one of the actual interface names,
such as ``de0'' or ``qe1'', or it may be a pseudo-interface
name of the form ``pf\fIn\fP'',
used to specify the 
.I n\fRth
\fRinterface attached to the system.
For example, ``pf0'' specifies
the first interface.
This is useful for applications
that do not know the names of specific interfaces.
Pseudo-interface names are never returned by EIOCIFNAME.
.ne 6
.IP EIOCDEVP
.br
To get device parameters of the network interface underlying the
packet filter file, use the following:
.EX
ioctl(\fIfildes\fP, EIOCDEVP, \fIparam\fP)
struct endevp *\fIparam\fP;
.EE
.ne 1.75i
The
.PN endevp
structure is defined in
.PN <net/pfilt.h>
as:
.EX
.ta \w'struct 'u +\w'u_short  'u
struct endevp {
	u_char	end_dev_type;
	u_char	end_addr_len;
	u_short	end_hdr_len;
	u_short	end_MTU;
	u_char	end_addr[EN_MAX_ADDR_LEN];
	u_char	end_broadaddr[EN_MAX_ADDR_LEN];
};
.DT
.EE
The fields are:
.RS
.IP end_dev_type 1.5i
Specifies the device type: ENDT_3MB, ENDT_BS3MB, or ENDT_10MB.
.IP end_addr_len 1.5i
Specifies the address length in bytes (for example, 1 or 6).
.IP end_hdr_len 1.5i
Specifies the total header length in bytes (for example, 4 or 14).
.IP end_MTU 1.5i
Specifies the maximum packet size, including header, in bytes.
.IP end_addr 1.5i
The address of this interface; aligned so that the low order
byte of the address is in
.IR end_addr[0] .
.IP end_broadaddr 1.5i
The hardware destination address for broadcasts on this network.
.RE
.SS Administrative ioctl Requests
.IP EIOCMAXBACKLOG
.br
The maximum queue length that can be set using EIOCSETW depends
on whether the process is running as the superuser or not.  If
so, the maximum is a kernel constant; otherwise, the maximum is a
value that can be set, by the superuser, for each interface.
To set the maximum non-superuser backlog for an interface, use
EIOCSETIF to bind to the interface, and then use the following:
.EX
ioctl(\fIfildes\fP, EIOCMAXBACKLOG, \fImaxbacklogp\fP)
int *\fImaxbacklogp\fP;
.EE
The argument
.I maxbacklogp
points to an integer containing the maximum value.
(If
.I maxbacklogp
points to an integer containing a negative value, it is replaced
with the current backlog value, and no action is taken.)
.IP EIOCALLOWPROMISC
.br
Certain kinds of network-monitoring applications need to place the
interface in ``promiscuous mode'', where it receives all packets on
the network.  Promiscuous mode can be set 
by the superuser with the
.I /etc/ifconfig
command, or the superuser can configure an interface
to go into promiscuous mode automatically if any packet filter applications
have the ENPROMISC mode bit set.  To do so, use
EIOCSETIF to bind to the interface, and then use the following:
.EX
ioctl(\fIfildes\fP, EIOCALLOWPROMISC, \fIallowp\fP)
int *\fIallowp\fP;
.EE
The argument
.I allowp
points to an integer containing a Boolean value (nonzero
means promiscuous mode is set automatically).
(If
.I allowp
points to an integer containing a negative value, it is replaced
with the current Boolean value, and no action is taken.)
.IP EIOCALLOWCOPYALL
.br
Certain promiscuous-mode network-monitoring applications need to see
unicast packets sent or received by the local host.  For reasons of
efficiency, these packets are not normally provided to the packet filter,
but in ``copy all'' mode they are.  The superuser can configure an 
interface to go into copy-all mode automatically if any packet filter
applications have the ENCOPYALL mode bit set.  To do so, use EIOCSETIF
to bind to the interface, and then use the following:
.EX
ioctl(\fIfildes\fP, EIOCALLOWCOPYALL, \fIallowp\fP)
int *\fIallowp\fP;
.EE
The argument
.I allowp
points to an integer containing a Boolean value (nonzero
means copy-all mode is set automatically).
(If
.I allowp
points to an integer containing a negative value, it is replaced with
the current Boolean value, and no action is taken.)
.IP EIOCMFREE
.br
To find out how many packet filter files remain for opening, use this
.PN ioctl ,
which places the number in the integer pointed to by
\fImfree\fR:
.EX
ioctl(\fIfildes\fP, EIOCMFREE, \fImfree\fP)
int *\fImfree\fP;
.EE
.br
.ne 1.5i
.SS Miscellaneous ioctl Requests
Two calls are provided for backwards compatibility and should not be used
in new code.  These calls are used to set and fetch parameters
of a packet filter file
(\fInot\fR
the underlying device; see EIOCDEVP).
The form for these calls is:
.EX
#include <sys/types.h>
#include <net/pfilt.h>
.sp .5
ioctl(\fIfildes\fP, \fIcode\fP, \fIparam\fP)
.sp .5
struct eniocb *\fIparam\fP;
.EE
.sp .5
The structure
.PN eniocb
is defined in 
.PN <net/pfilt.h>
as:
.EX
.ta \w'struct 'u +\w'u_char  'u
struct eniocb
{
	u_char	en_addr;
	u_char	en_maxfilters;
	u_char	en_maxwaiting;
	u_char	en_maxpriority;
	long	en_rtout;
};
.DT
.EE
.i0
.sp .5
The applicable
.I codes
are:
.IP EIOCGETP
.br
Fetch the parameters for this file.
.IP EIOCSETP
.br
Set the parameters for this file.
.i0
.DT
.sp .5
All the fields, which are described later, except \fIen_rtout\fR,
are read-only.
.RS
.IP en_addr 1.5i
No longer maintained; use EIOCDEVP.
.IP en_maxfilters 1.5i
The maximum length of a filter command list; see EIOCSETF.
.br
.ne 3
.IP en_maxwaiting 1.5i
The maximum number of packets that can be queued for reading on the
packet filter
file; use EIOCMAXBACKLOG.
.IP en_maxpriority 1.5i
The highest allowable filter priority; see EIOCSETF.
.IP en_rtout 1.5i
The number of clock ticks to
wait before timing out on a read request and returning a zero length.
If zero, reads block indefinitely until a packet arrives.
If negative, read requests return a zero length
immediately if there are no packets in the input queue.
Initialized to zero by
.MS open 2 ,
indicating no timeout.
(Use EIOCSRTIMEOUT and EIOCGRTIMEOUT.)
.RE
.br
.ne 1.5i
.SH Restrictions
Because the packet filter include file 
.PN <net/pfilt.h>
was originally named 
.PN <sys/enet.h> ,
some filter applications may need to be updated.
.PP
A previous restriction against accessing data words past approximately
the first
hundred bytes in a packet has been removed.  However, it becomes
slightly more costly to examine words that are not near the beginning
of the packet.
.PP
Because packets are streams of bytes, yet the filters operate
on short words, and standard network byte order is usually opposite
from VAX byte order, the relational operators
ENF_LT, ENF_LE,
ENF_GT,
and
ENF_GE
are not particularly useful.  If this becomes a severe problem,
a byte-swapping operator could be added.
.SH Files
.PN /dev/pf/pfilt\fInnn
\fR	Packet filter special files
.SH See Also
ethers(3n), pfopen(3), de(4), ln(4), ni(4), qe(4), xna(4), ifconfig(8),
MAKEDEV(8), pfconfig(8c), pfstat(8)
.br
\fIThe Packet Filter: An Efficient Mechanism for User-Level Network
Code\fR