osmith
/
wireshark
forked from osmocom/wireshark
1
0
Fork 0
Code Pull Requests Releases Wiki Activity

dftest: update man page and README.display_filter

This commit is contained in:
Chuck Craft 2021-10-15 18:11:58 -05:00 committed by Wireshark GitLab Utility
parent 0f7217aadf
commit 947d3ff819
2 changed files with 80 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

122
doc/README.display_filter
View File

@ -41,14 +41,18 @@ definition, which is the enum of all possible ftypes:
/* field types */ /* field types */
enum ftenum { enum ftenum {
FT_NONE, /* used for text labels with no value */ FT_NONE, /* used for text labels with no value */
FT_PROTOCOL, FT_PROTOCOL,
FT_BOOLEAN, /* TRUE and FALSE come from <glib.h> */ FT_BOOLEAN, /* TRUE and FALSE come from <glib.h> */
FT_UINT8, FT_CHAR, /* 1-octet character as 0-255 */
FT_UINT16, FT_UINT8,
FT_UINT24, /* really a UINT32, but displayed as3 hex-digits if FD_HEX*/ FT_UINT16,
FT_UINT32, FT_UINT24, /* really a UINT32, but displayed as 6 hex-digits if FD_HEX*/
FT_UINT64, FT_UINT32,
FT_UINT40, /* really a UINT64, but displayed as 10 hex-digits if FD_HEX*/
FT_UINT48, /* really a UINT64, but displayed as 12 hex-digits if FD_HEX*/
FT_UINT56, /* really a UINT64, but displayed as 14 hex-digits if FD_HEX*/
FT_UINT64,
etc., etc. etc., etc.
} }
@ -60,27 +64,30 @@ The fvalue_t is mostly just a gigantic union of possible C-language types
(as opposed to FT_* types): (as opposed to FT_* types):
typedef struct _fvalue_t { typedef struct _fvalue_t {
ftype_t *ftype; ftype_t *ftype;
union { union {
/* Put a few basic types in here */ /* Put a few basic types in here */
guint32 uinteger; guint32 uinteger;
gint32 sinteger; gint32 sinteger;
guint64 integer64; guint64 integer64;
gdouble floating; guint64 uinteger64;
gchar *string; gint64 sinteger64;
guchar *ustring; gdouble floating;
GByteArray *bytes; gchar *string;
ipv4_addr ipv4; guchar *ustring;
ipv6_addr ipv6; GByteArray *bytes;
e_guid_t guid; ipv4_addr_and_mask ipv4;
nstime_t time; ipv6_addr_and_prefix ipv6;
tvbuff_t *tvb; e_guid_t guid;
GRegex *re; nstime_t time;
} value; protocol_value_t protocol;
guint16 sfloat_ieee_11073;
guint32 float_ieee_11073;
} value;
/* The following is provided for private use /* The following is provided for private use
* by the fvalue. */ * by the fvalue. */
gboolean fvalue_gboolean1; gboolean fvalue_gboolean1;
} fvalue_t; } fvalue_t;
@ -90,8 +97,8 @@ Defining a field type
The ftype system itself is designed to be modular, so that new field types The ftype system itself is designed to be modular, so that new field types
can be added when necessary. can be added when necessary.
Each field type must implement an ftype_t structure, also defined in Each field type must implement an ftype_t structure, defined in
ftypes.h. This is the way a field type is registered with the ftype engine. ftypes-int.h. This is the way a field type is registered with the ftype engine.
If you take a look at ftype-integer.c, you will see that it provides If you take a look at ftype-integer.c, you will see that it provides
an ftype_register_integers() function, that fills in many such ftype_t an ftype_register_integers() function, that fills in many such ftype_t
@ -207,7 +214,7 @@ The syntax tree system
---------------------- ----------------------
The syntax tree is created as a result of running the lemon-based The syntax tree is created as a result of running the lemon-based
grammar parser on the scanned tokens. The syntax tree code grammar parser on the scanned tokens. The syntax tree code
is in epan/dfilter/syntax-tree* and epan/dfilter/sttree-*. It too is in epan/dfilter/syntax-tree* and epan/dfilter/sttype-*. It too
uses a set of code modules that implement different syntax node types, uses a set of code modules that implement different syntax node types,
similar to how the field-type system registers a set of ftypes similar to how the field-type system registers a set of ftypes
with a central engine. with a central engine.
@ -217,19 +224,21 @@ These sttypes are very much related to ftypes (field types), but there
is not a one-to-one correspondence. The syntax tree nodes are slightly is not a one-to-one correspondence. The syntax tree nodes are slightly
high-level. For example, there is only a single INTEGER sttype, unlike high-level. For example, there is only a single INTEGER sttype, unlike
the ftype system that has a type for UINT64, UINT32, UINT16, UINT8, etc. the ftype system that has a type for UINT64, UINT32, UINT16, UINT8, etc.
(INTEGER removed in 2c701ddf - dfilter: Improve grammar to parse ranges)
typedef enum { typedef enum {
STTYPE_UNINITIALIZED, STTYPE_UNINITIALIZED,
STTYPE_TEST, STTYPE_TEST,
STTYPE_UNPARSED, STTYPE_UNPARSED,
STTYPE_STRING, STTYPE_STRING,
STTYPE_FIELD, STTYPE_CHARCONST,
STTYPE_FVALUE, STTYPE_FIELD,
STTYPE_INTEGER, STTYPE_FVALUE,
STTYPE_RANGE, STTYPE_RANGE,
STTYPE_FUNCTION, STTYPE_FUNCTION,
STTYPE_SET, STTYPE_SET,
STTYPE_NUM_TYPES STTYPE_PCRE,
STTYPE_NUM_TYPES
} sttype_id_t; } sttype_id_t;
@ -293,11 +302,11 @@ Both of these can only branch forwards, and never backwards. In this way
sets of DFVM instructions will never get into an infinite loop. sets of DFVM instructions will never get into an infinite loop.
The epan/dfilter/gencode.c code converts the syntax tree The epan/dfilter/gencode.c code converts the syntax tree
into a set of dvfm instructions. into a set of dfvm instructions.
The constants that are in the DFVM instructions (the constant The constants that are in the DFVM instructions (the constant
values that the user is checking against) are pre-loaded values that the user is checking against) are pre-loaded
into registers via the dvfm_init_const() call, and stored into registers via the dfvm_init_const() call, and stored
in the dfilter_t structure for when the display filter is in the dfilter_t structure for when the display filter is
actually applied. actually applied.
@ -331,7 +340,7 @@ $ make dftest
To use it, give it the display filter on the command-line: To use it, give it the display filter on the command-line:
$ ./dftest 'ip.addr == 127.0.0.1' $ ./dftest 'ip.addr == 127.0.0.1'
Filter: "ip.addr == 127.0.0.1" Filter: ip.addr == 127.0.0.1
Constants: Constants:
00000 PUT_FVALUE 127.0.0.1 <FT_IPv4> -> reg#1 00000 PUT_FVALUE 127.0.0.1 <FT_IPv4> -> reg#1
@ -367,9 +376,9 @@ in the proto_tree, then we jump to instruction 3.
00002 ANY_EQ reg#0 == reg#1 00002 ANY_EQ reg#0 == reg#1
This checks to see if any of the fields in register 0 This checks to see if any of the fields in register 1
(which has the pre-loaded constant value of 127.0.0.1) are equal (which has the pre-loaded constant value of 127.0.0.1) are equal
to any of the fields in register 1 (which are all of the ip.addr to any of the fields in register 0 (which are all of the ip.addr
fields in the proto tree). The resulting value in the fields in the proto tree). The resulting value in the
accumulator will be TRUE if any of the fields match, or FALSE accumulator will be TRUE if any of the fields match, or FALSE
if none match. if none match.
@ -378,10 +387,11 @@ if none match.
This returns the accumulator's value, either TRUE or FALSE. This returns the accumulator's value, either TRUE or FALSE.
In addition to dftest, there is also a tools/dfilter-test script In addition to dftest, there is also a unit-test script for the
which is a unit-test script for the display filter engine. display filter engine - test/suite_dfilter/dfiltertest.py.
It makes use of text2pcap and tshark to run specific display It makes use of tshark to run specific display filters against
filters against specific captures (embedded within dfilter-test). specific captures in test/captures. See the "Wireshark Tests" chapter
in the Wireshark Developer’s Guide.
@ -439,21 +449,23 @@ is passed to your function so you can set the pointer to your return value.
DFSemCheckType DFSemCheckType
-------------- --------------
typedef void (*DFSemCheckType)(int param_num, stnode_t *st_node); typedef void (*DFSemCheckType)(dfwork_t *dfw, int param_num, stnode_t *st_node);
For each parameter in the syntax tree, this function will be called. For each parameter in the syntax tree, this function will be called.
"param_num" will indicate the number of the parameter, starting with 0. "param_num" will indicate the number of the parameter, starting with 0.
The "stnode_t" is the syntax-tree node representing that parameter. The "stnode_t" is the syntax-tree node representing that parameter.
If everything is okay with the value of that stnode_t, your function If everything is okay with the value of that stnode_t, your function
does nothing --- it merely returns. If something is wrong, however, does nothing --- it merely returns. If something is wrong, however,
it should THROW a TypeError exception. it should call dfilter_fail(dfw,...) and THROW a TypeError exception.
Example: add an 'in' display filter operation Example: add an 'in' display filter operation
============================================= =============================================
This example has been discussed on wireshark-dev in April 2004. It illustrates This example has been discussed on ethereal-dev in April 2004.
how a more complex operation can be added to the display filter language. [Ethereal-dev] Need for an 'in' dfilter operator?
(https://www.wireshark.org/lists/ethereal-dev/200404/msg00372.html)
It illustrates how a more complex operation can be added to the display filter language.
Question: Question:

13
doc/dftest.adoc
View File

@ -18,6 +18,8 @@ dftest - Shows display filter byte-code, for debugging dfilter routines.
== DESCRIPTION == DESCRIPTION
*dftest* is a simple tool which compiles a display filter and shows its bytecode. *dftest* is a simple tool which compiles a display filter and shows its bytecode.
Please refer to doc/README.display_filter for a description of the
DFVM (Display Filter Virtual Machine) Byte Codes.
== OPTIONS == OPTIONS
@ -40,3 +42,14 @@ Shows how frame 150 is filtered:
== SEE ALSO == SEE ALSO
xref:wireshark-filter.html[wireshark-filter](4) xref:wireshark-filter.html[wireshark-filter](4)
// 526a2946 - dftest and randpkt ... they are not documented in any man page.
== AUTHORS
.Original Author
[%hardbreaks]
Jan Šafránek
.Contributors
[%hardbreaks]
Jaap Keuter