Document "len" and "count" in wireshark-filter(4) and WSUG

Add missing section on display filter functions to WSUG and make it
consistent with the wireshark-filter(4) manual. "count" was added in
Wireshark 1.12 (bug 9480). "len" was added in Wireshark 1.6.x.

"size" (added in 1.8.x) is not documented since it works like "len",
except that it is not limited to strings and byte arrays. I think that
"len" should be extended to other types while removing "size".

Change-Id: I2c8e2b4a11f007de7852a797bed971af86840b47
Reviewed-on: https://code.wireshark.org/review/27146
Petri-Dish: Peter Wu <peter@lekensteyn.nl>
Tested-by: Petri Dish Buildbot
Reviewed-by: Anders Broman <a.broman58@gmail.com>

diff --git a/doc/wireshark-filter.pod b/doc/wireshark-filter.pod
index c54e4ca353a1d011bb72f0dca5443174d1a5a108..adffef2aabc9f24e4fc053182500b25971bd1c4b 100644 (file)
--- a/doc/wireshark-filter.pod
+++ b/doc/wireshark-filter.pod
@@ -96,6 +96,8 @@ The filter language has the following functions:
 
     upper(string-field) - converts a string field to uppercase
     lower(string-field) - converts a string field to lowercase
+    len(field)          - returns the byte length of a string or bytes field
+    count(field)        - returns the number of field occurrences in a frame
 
 upper() and lower() are useful for performing case-insensitive string
 comparisons. For example:

diff --git a/docbook/wsug_src/WSUG_chapter_work.asciidoc b/docbook/wsug_src/WSUG_chapter_work.asciidoc
index 473673b8d1d28f606879260f2ddf1791af4f2d68..46e08c001c65bad3c17626d2537e9a8c96211fad 100644 (file)
--- a/docbook/wsug_src/WSUG_chapter_work.asciidoc
+++ b/docbook/wsug_src/WSUG_chapter_work.asciidoc
@@ -387,11 +387,11 @@ You can combine filter expressions in Wireshark using the  logical operators sho
 |or      |\|\|      | Logical OR. `ip.scr==10.0.0.5 or ip.src==192.1.1.1`
 |xor     |^^        | Logical XOR. `tr.dst[0:3] == 0.6.29 xor tr.src[0:3] == 0.6.29`
 |not     |!         | Logical NOT. `not llc`
-|[...]   |          | See “Substring Operator” below.
+|[...]   |          | See “Slice Operator” below.
 |in      |          | See “Membership Operator” below.
 |===============
 
-==== Substring Operator
+==== Slice Operator
 Wireshark allows you to select subsequences of a sequence in rather elaborate
 ways. After a label you can place a pair of brackets [] containing a comma
 separated list of range specifiers.
@@ -427,7 +427,7 @@ eth.src[0:3,1-2,:4,4:,2] ==
 Wireshark allows you to string together single ranges in a comma separated list
 to form compound ranges as shown above.
 
-==== Membership Operator.
+==== Membership Operator
 Wireshark allows you to test a field for membership in a set of values or
 fields. After the field name, use the in operator followed by the set items
 surrounded by braces {}.
@@ -457,6 +457,33 @@ ip.addr in {10.0.0.5 .. 10.0.0.9 192.168.1.1..192.168.1.9}
 frame.time_delta in {10 .. 10.5}
 ----
 
+==== Functions
+
+The display filter language has a number of functions to convert fields, see
+<<DispFunctions>>.
+
+[[DispFunctions]]
+.Display Filter Functions
+[options="header",cols="1,4"]
+|===============
+|Function|Description
+|upper   |Converts a string field to uppercase.
+|lower   |Converts a string field to lowercase.
+|len     |Returns the byte length of a string or bytes field.
+|count   |Returns the number of field occurrences in a frame.
+|===============
+
+The `upper` and `lower` functions can used to force case-insensitive matches:
+`lower(http.server) contains "apache"`.
+
+To find HTTP requests with long request URIs: `len(http.request.uri) > 100`.
+Note that the `len` function yields the string length in bytes rather than
+(multi-byte) characters.
+
+Usually an IP frame has only two addresses (source and destination), but in case
+of ICMP errors or tunneling, a single packet might contain even more addresses.
+These packets can be found with `count(ip.addr) > 2`.
+
 [[ChWorkBuildDisplayFilterMistake]]
 
 ==== A Common Mistake