From Graeme Hewson:

     Remove reference to negative slice lengths.

     Clean and polish.


git-svn-id: http://anonsvn.wireshark.org/wireshark/trunk@11086 f5534014-38df-0310-8fa8-9805f1628bb7

1 files changed, 106 insertions, 86 deletions

diff --git a/doc/ethereal-filter.pod.template b/doc/ethereal-filter.pod.template
index fe455fd142..b96693aab9 100644
--- a/doc/ethereal-filter.pod.template
+++ b/doc/ethereal-filter.pod.template
@@ -12,12 +12,12 @@ S<[ B<-R> "filter expression" ]>
 
 =head1 DESCRIPTION
 
-B<Ethereal> and B<Tethereal> share a powerful filter engine that help remove
-the noise from a packet trace and let you see only the packets that interest
+B<Ethereal> and B<Tethereal> share a powerful filter engine that helps remove
+the noise from a packet trace and lets you see only the packets that interest
 you.  If a packet meets the requirements expressed in your filter, then it
 is displayed in the list of packets.  Display filters let you compare the
 fields within a protocol against a specific value, compare fields against
-fields, and to check the existence of specified fields or protocols.
+fields, and check the existence of specified fields or protocols.
 
 Filters are also used by other features such as statistics generation and
 packet list colorization (the latter is only available to B<Ethereal>). This
@@ -30,7 +30,7 @@ filter fields.
 
 The simplest filter allows you to check for the existence of a protocol or
 field.  If you want to see all packets which contain the IPX protocol, the
-filter would be "ipx".  (Without the quotation marks) To see all packets
+filter would be "ipx" (without the quotation marks). To see all packets
 that contain a Token-Ring RIF field, use "tr.rif".
 
 Think of a protocol or field in a filter as implicitly having the "exists"
@@ -43,12 +43,12 @@ below).
 =head2 Comparison operators
 
 Fields can also be compared against values.  The comparison operators
-can be expressed either through C-like symbols, or through English-like
+can be expressed either through C-like symbols or through English-like
 abbreviations:
 
     eq, ==    Equal
-    ne, !=    Not equal
-    gt, >     Greater than
+    ne, !=    Not Equal
+    gt, >     Greater Than
     lt, <     Less Than
     ge, >=    Greater than or Equal to
     le, <=    Less than or Equal to
@@ -57,25 +57,25 @@ abbreviations:
 
 Additional operators exist expressed only in English, not punctuation:
 
-	contains  Does the protocol, byte-string, or text string contain a value
-	matches   Does the text string match the given Perl regular expression
+    contains  Does the protocol, field or slice contain a value
+    matches   Does the text string match the given Perl regular expression
 
-The "contains" operator allows a filter to search for any sequence of
-characters that may occur in a protocol or field.  The "contains"
-operator is only implemented for protocols (in which case the sequence
-of characters is searched for in the data for that protocol), text
-fields, and raw data fields.  For example, to search for a given HTTP
+The "contains" operator allows a filter to search for a sequence of
+characters or bytes.  For example, to search for a given HTTP
 URL in a capture, the following filter can be used:
 
-	http contains "http://www.ethereal.com"
+    http contains "http://www.ethereal.com"
+
+The "contains" operator cannot be used on atomic fields,
+such as numbers or IP addresses.
 
 The "matches" operator allows a filter to apply to a specified
 Perl-compatible regular expression (PCRE).  The "matches" operator is only
-implemented for protocols, and also for protocol fields with a text string
+implemented for protocols and for protocol fields with a text string
 representation.  For example, to search for a given WAP WSP User-Agent,
-one can write:
+you can write:
 
-	wsp.user_agent matches "(?i)cldc"
+    wsp.user_agent matches "(?i)cldc"
 
 This example shows an interesting PCRE feature: pattern match options have to
 be specified with the B<(?>optionB<)> construct. For instance, B<(?i)> performs
@@ -86,20 +86,20 @@ B<http://www.perldoc.com/perl5.8.0/pod/perlre.html>).
 Note: the "matches" operator is only available if B<Ethereal> or B<Tethereal>
 have been compiled with the PCRE library. This can be checked by running:
 
-	ethereal -v
-	tethereal -v
+    ethereal -v
+    tethereal -v
 
 or selecting the "About Ethereal" item from the "Help" menu in B<Ethereal>.
 
 =head2 Protocol field types
 
-Furthermore, each protocol field is typed. The types are:
+Each protocol field is typed. The types are:
 
-    Unsigned integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
-    Signed integer (either 8-bit, 16-bit, 24-bit, or 32-bit)
+    Unsigned integer (8-bit, 16-bit, 24-bit, or 32-bit)
+    Signed integer (8-bit, 16-bit, 24-bit, or 32-bit)
     Boolean
     Ethernet address (6 bytes)
-    Byte string (n-number of bytes)
+    Byte array
     IPv4 address
     IPv6 address
     IPX network number
@@ -116,7 +116,7 @@ The following three display filters are equivalent:
 Boolean values are either true or false.  In a display filter expression
 testing the value of a Boolean field, "true" is expressed as 1 or any
 other non-zero value, and "false" is expressed as zero.  For example, a
-token-ring packet's source route field is boolean.  To find any
+token-ring packet's source route field is Boolean.  To find any
 source-routed packets, a display filter would be:
 
     tr.sr == 1
@@ -125,18 +125,15 @@ Non source-routed packets can be found with:
 
     tr.sr == 0
 
-Ethernet addresses, as well as a string of bytes, are represented in hex
+Ethernet addresses and byte arrays are represented by hex
 digits.  The hex digits may be separated by colons, periods, or hyphens:
 
-    fddi.dst eq ff:ff:ff:ff:ff:ff
-    ipx.srcnode == 0.0.0.0.0.1
-    eth.src == aa-aa-aa-aa-aa-aa
-
-If a string of bytes contains only one byte, then it is represented as
-an unsigned integer.  That is, if you are testing for hex value 'ff' in
-a one-byte byte-string, you must compare it agains '0xff' and not 'ff'. 
+    eth.dst eq ff:ff:ff:ff:ff:ff
+    aim.data == 0.1.0.d
+    fddi.src == aa-aa-aa-aa-aa-aa
+    echo.data == 7a
 
-IPv4 addresses can be represented in either dotted decimal notation, or
+IPv4 addresses can be represented in either dotted decimal notation or
 by using the hostname:
 
     ip.dst eq www.mit.edu
@@ -144,7 +141,7 @@ by using the hostname:
 
 IPv4 addresses can be compared with the same logical relations as numbers:
 eq, ne, gt, ge, lt, and le.  The IPv4 address is stored in host order,
-so you do not have to worry about how the endianness of an IPv4 address
+so you do not have to worry about the endianness of an IPv4 address
 when using it in a display filter.
 
 Classless InterDomain Routing (CIDR) notation can be used to test if an
@@ -155,25 +152,25 @@ will find all packets in the 129.111 Class-B network:
 
 Remember, the number after the slash represents the number of bits used
 to represent the network.  CIDR notation can also be used with
-hostnames, in this example of finding IP addresses on the same Class C
+hostnames, as in this example of finding IP addresses on the same Class C
 network as 'sneezy':
 
     ip.addr eq sneezy/24
 
 The CIDR notation can only be used on IP addresses or hostnames, not in
 variable names.  So, a display filter like "ip.src/24 == ip.dst/24" is
-not valid.  (yet)
+not valid (yet).
 
 IPX networks are represented by unsigned 32-bit integers.  Most likely
-you will be using hexadecimal when testing for IPX network values:
+you will be using hexadecimal when testing IPX network values:
 
-    ipx.srcnet == 0xc0a82c00
+    ipx.src.net == 0xc0a82c00
 
-Strings are enclosed in double-quotes:
+Strings are enclosed in double quotes:
 
     http.request.method == "POST"
 
-Inside double quotes, you may use the backslash to embed a double-quote,
+Inside double quotes, you may use a backslash to embed a double quote
 or an arbitrary byte represented in either octal or hexadecimal.
 
     browser.comment == "An embedded \" double-quote"
@@ -184,49 +181,49 @@ Use of hexadecimal to look for "HEAD":
 
 Use of octal to look for "HEAD":
 
-    http.request.method == "\x110EAD"
+    http.request.method == "\110EAD"
 
 This means that you must escape backslashes with backslashes inside
-double quotes:
+double quotes.
 
     smb.path contains "\\\\SERVER\\SHARE"
 
-to look for \\SERVER\SHARE in "smb.path".
+looks for \\SERVER\SHARE in "smb.path".
 
 =head2 The slice operator
 
-A slice operator also exists.  You can check the substring
-(byte-string) of any protocol or field.  For example, you can filter on
+You can take a slice of a field if the field is a text string or a
+byte array. 
+For example, you can filter on
 the vendor portion of an ethernet address (the first three bytes) like
 this:
 
     eth.src[0:3] == 00:00:83
 
-If the length of your byte-slice is only one byte, then it is still
-represented in hex, but without the preceding "0x": 
+Another example is:
 
-    llc[3] == aa
+    http.content_type[0:4] == "text"
 
-You can use the slice operator on a protocol name, too.  And
-remember, the "frame" protocol encompasses the entire packet, allowing
-you to look at the nth byte of a packet regardless of its frame type
-(Ethernet, token-ring, etc.).
+You can use the slice operator on a protocol name, too.
+The "frame" protocol can be useful, encompassing all the data captured
+by B<Ethereal> or B<Tethereal>.
 
     token[0:5] ne 0.0.0.1.1
-    ipx[0:2] == ff:ff
-    llc[3:1] eq 0xaa
+    llc[0] eq aa
+    frame[100-199] contains "ethereal"
 
 The following syntax governs slices:
 
-	[i:j]	i = start_offset, j = length
-	[i-j]	i = start_offset, j = end_offset, inclusive.
-	[i]	i = start_offset, length = 1
-	[:j]	start_offset = 0, length = j
-	[i:]	start_offset = i, end_offset = end_of_field
+    [i:j]    i = start_offset, j = length
+    [i-j]    i = start_offset, j = end_offset, inclusive.
+    [i]      i = start_offset, length = 1
+    [:j]     start_offset = 0, length = j
+    [i:]     start_offset = i, end_offset = end_of_field
 
-Offsets and lengths can be negative, in which case they indicate the
-offset from the B<end> of the field.  Here's how to check the last 4
-bytes of a frame:
+Offsets can be negative, in which case they indicate the
+offset from the B<end> of the field.  The last byte of the field is at offset
+-1, the last but one byte is at offset -2, and so on.
+Here's how to check the last four bytes of a frame:
 
     frame[-4:4] == 0.1.2.3
 
@@ -234,9 +231,27 @@ or
 
     frame[-4:] == 0.1.2.3
 
-You can create complex concatenations of slices using the comma operator:
+You can concatenate slices using the comma operator:
+
+    ftp[1,3-5,9:] == 01:03:04:05:09:0a:0b
+
+This concatenates offset 1, offsets 3-5, and offset 9 to the end of the ftp
+data.
+
+=head2 Type conversions
+
+If a field is a text string or a byte array, it can be expressed in whichever
+way is most convenient.
+
+So, for instance, the following filters are equivalent:
+
+    http.request.method == "GET"
+    http.request.method == 47.45.54
+
+A range can also be expressed in either way:
 
-	field[1,3-5,9:] == 01:03:04:05:09:0a:0b
+    frame[60:2] gt 50.51
+    frame[60:2] gt "PQ"
 
 =head2 Bit field operations
 
@@ -245,10 +260,10 @@ following bit field operation is supported:
 
     bitwise_and, &	Bitwise AND
 
-The bitwise AND operation allows testing if one or more bits are set.
+The bitwise AND operation allows testing to see if one or more bits are set.
 Bitwise AND operates on integer protocol fields and slices.
 
-When testing for TCP SYN packets, once can write:
+When testing for TCP SYN packets, you can write:
 
     tcp.flags & 0x02
 
@@ -256,14 +271,14 @@ Similarly, filtering for all WSP GET and extended GET methods is achieved with:
 
     wsp.pdu_type & 0x40
 
-When using slices, the bit mask must be specified as byte string, and it must
+When using slices, the bit mask must be specified as a byte string, and it must
 have the same number of bytes as the slice itself, as in:
 
     ip[42:2] & 40:ff
 
 =head2 Logical expressions
 
-All the above tests can be combined together with logical expressions. 
+Tests can be combined using logical expressions. 
 These too are expressable in C-like syntax or with English-like
 abbreviations:
 
@@ -276,8 +291,8 @@ all valid display filter expressions:
 
     tcp.port == 80 and ip.src == 192.168.2.1
     not llc
-    (ipx.srcnet == 0xbad && ipx.srnode == 0.0.0.0.0.1) || ip
-    tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29
+    http and frame[100-199] contains "ethereal"
+    (ipx.src.net == 0xbad && ipx.src.node == 0.0.0.0.0.1) || ip
 
 Remember that whenever a protocol or field name occurs in an expression, the
 "exists" operator is implicitly called. The "exists" operator has the highest
@@ -285,7 +300,9 @@ priority. This means that the first filter expression must be read as "show me
 the packets for which tcp.port exists and equals 80, and ip.src exists and
 equals 192.168.2.1". The second filter expression means "show me the packets
 where not (llc exists)", or in other words "where llc does not exist" and hence
-will match all packets that do not convey the llc protocol.
+will match all packets that do not contain the llc protocol.
+The third filter expression includes the constraint that offset 199 in the
+frame exists, in other words the length of the frame is at least 200.
 
 A special caveat must be given regarding fields that occur more than
 once per packet.  "ip.addr" occurs twice per IP packet, once for the
@@ -296,44 +313,47 @@ two expressions are not equivalent:
         ip.addr ne 192.168.4.1
     not ip.addr eq 192.168.4.1
 
-The first filter says "show me IP packets where an ip.addr exists that
+The first filter says "show me packets where an ip.addr exists that
 does not equal 192.168.4.1".  That is, as long as one ip.addr in the
-packet does not equal 192.168.44.1, the packet passes the display
-filter.  The second filter "don't show me any packets that have at least
-one ip.addr field equal to 192.168.4.1".  If one ip.addr is 192.168.4.1,
-the packet does not pass.  If B<neither> ip.addr fields is 192.168.4.1,
-then the packet passes.
+packet does not equal 192.168.4.1, the packet passes the display
+filter.  The other ip.addr could equal 192.168.4.1 and the packet would
+still be displayed.
+The second filter says "don't show me any packets that have an
+ip.addr field equal to 192.168.4.1".  If one ip.addr is 192.168.4.1,
+the packet does not pass.  If B<neither> ip.addr field is 192.168.4.1,
+then the packet is displayed.
 
 It is easy to think of the 'ne' and 'eq' operators as having an implict
 "exists" modifier when dealing with multiply-recurring fields.  "ip.addr
 ne 192.168.4.1" can be thought of as "there exists an ip.addr that does
-not equal 192.168.4.1".
+not equal 192.168.4.1".  "not ip.addr eq 192.168.4.1" can be thought of as
+"there does not exist an ip.addr equal to 192.168.4.1".
 
 Be careful with multiply-recurring fields; they can be confusing.
 
 Care must also be taken when using the display filter to remove noise
-from the packet trace. If you want to e.g. filter out all IP multicast
-packets to address 224.1.2.3, then using:
+from the packet trace. If, for example, you want to filter out all IP
+multicast packets to address 224.1.2.3, then using:
 
     ip.dst ne 224.1.2.3
 
 may be too restrictive. Filtering with "ip.dst" selects only those
 B<IP> packets that satisfy the rule. Any other packets, including all
-non-IP packets, will not be displayed. For displaying also the non-IP
-packets, you can use one of the following two expressions:
+non-IP packets, will not be displayed. To display the non-IP
+packets as well, you can use one of the following two expressions:
 
     not ip or ip.dst ne 224.1.2.3
     not ip.addr eq 224.1.2.3
 
 The first filter uses "not ip" to include all non-IP packets and then
-lets "ip.dst ne 224.1.2.3" to filter out the unwanted IP packets. The
+lets "ip.dst ne 224.1.2.3" filter out the unwanted IP packets. The
 second filter has already been explained above where filtering with
 multiply occuring fields was discussed.
 
 =head1 FILTER PROTOCOL REFERENCE
 
 Each entry below provides an abbreviated protocol or field name.  Every
-one of these fields can be used as a display filter.  The type of the
+one of these fields can be used in a display filter.  The type of the
 field is also given.
 
 =insert_dfilter_table
@@ -345,7 +365,7 @@ The latest version of B<Ethereal> can be found at
 B<http://www.ethereal.com>.
 
 Regular expressions in the "matches" operator are provided with B<libpcre>,
-the Perl-Compatible Regular Expressions library, see B<http://www.pcre.org/>.
+the Perl-Compatible Regular Expressions library: see B<http://www.pcre.org/>.
 
 This manpage does not describe the capture filter syntax, which is
 different. See the tcpdump(8) manpage for a description of capture