From Andrew Feren:
Fix an assortment of typos and other minor errors in various README files svn path=/trunk/; revision=23166
This commit is contained in:
parent
ff5826a106
commit
5a58a1435c
|
@ -2,7 +2,7 @@ $Id$
|
|||
|
||||
1. Introduction
|
||||
|
||||
Binary trees is a well known and popular device in computer science to handle
|
||||
Binary trees are a well known and popular device in computer science to handle
|
||||
storage of object based on a search key or identity.
|
||||
One particular class of binary trees are Red/Black trees which have nice
|
||||
properties such as being self-balanced.
|
||||
|
@ -11,7 +11,7 @@ for lookups, compared to linked lists that are of order O(n).
|
|||
|
||||
Benefits of using binary trees are that they are incredibly fast for
|
||||
accessing data and they scale very well with good characteristics even to
|
||||
very large number of objects.
|
||||
very large numbers of objects.
|
||||
|
||||
Wireshark provides its own version of red black binary trees designed in
|
||||
particular to be easy to use and to eliminate most of the memory management
|
||||
|
@ -26,7 +26,7 @@ Please see README.malloc for a description of EPhemeral and SEasonal storage.
|
|||
|
||||
|
||||
2. Basic Usage
|
||||
For most users it will be sufficiant to only know and use three functions
|
||||
For most users it will be sufficient to only know and use three functions
|
||||
emem_tree_t *se_tree_create(int type, char *name);
|
||||
void se_tree_insert32(emem_tree_t *se_tree, guint32 key, void *data);
|
||||
void *se_tree_lookup32(emem_tree_t *se_tree, guint32 key);
|
||||
|
@ -34,8 +34,8 @@ void *se_tree_lookup32(emem_tree_t *se_tree, guint32 key);
|
|||
|
||||
2.1 se_tree_create(int type, char *name);
|
||||
se_tree_create() is used to initialize a tree that will be automatically
|
||||
cleared and reset everytime wireshark is resetting all SEasonal storage,
|
||||
that is every time you load a new capture file into wireshark or when
|
||||
cleared and reset everytime wireshark is resetting all SEasonal storage.
|
||||
That is every time you load a new capture file into wireshark or when
|
||||
you rescan the entire capture file from scratch.
|
||||
|
||||
Name is just a literal text string and serves no other purpose than making
|
||||
|
@ -53,14 +53,15 @@ static emem_tree_t *tcp_pdu_time_table = NULL;
|
|||
...
|
||||
void proto_register_...(void) {
|
||||
...
|
||||
tcp_pdu_time_table=se_tree_create(EMEM_TREE_TYPE_RED_BLACK, "PROTO_my_tree");
|
||||
tcp_pdu_time_table=se_tree_create(EMEM_TREE_TYPE_RED_BLACK, "PROTO_mytree");
|
||||
...
|
||||
}
|
||||
|
||||
That is how easy it is to create a binary tree. You only need to create it once
|
||||
when wireshark starts and the tree will remain there until you exit wireshark.
|
||||
Everytime a new capture is loaded, all nodes allocated to the tree is
|
||||
automatically and the tree is reset without you having to do anything at all.
|
||||
That is how easy it is to create a binary tree. You only need to create it
|
||||
once when wireshark starts and the tree will remain there until you exit
|
||||
wireshark. Everytime a new capture is loaded, all nodes allocated to the
|
||||
tree are freed automatically and the tree is reset without you having to do
|
||||
anything at all.
|
||||
|
||||
|
||||
2.2 se_tree_insert32(emem_tree_t *se_tree, guint32 key, void *data);
|
||||
|
@ -70,21 +71,21 @@ identifier/key for the node. Most trees you want to use are likely in this
|
|||
category.
|
||||
|
||||
As data you should specify a pointer to the data structure you want to be
|
||||
able to retreive later when you look for that same key.
|
||||
able to retrieve later when you look for that same key.
|
||||
|
||||
NOTE: If you insert a node to a key that already exists in the tree
|
||||
this function will allow you to do that. It will just drop the old pointer
|
||||
to data and replace it with the new one you just provided.
|
||||
This should not be a problem as long as the old and the new data blobs
|
||||
are se_allocated() since you cant free() such memory explicitely anyway
|
||||
are se_allocated() since you cant free() such memory explicitly anyway
|
||||
and the old one will be release automatically anyway when the SEasonal
|
||||
system reclaims all the SE data.
|
||||
|
||||
NOTE: It is a good idea to only provide data that point to blobs allocated
|
||||
bu se_alloc(). By doing that you will have a tree where the tree and all
|
||||
the data pointed to will be automatically released by the system at the same
|
||||
time.
|
||||
This is very neat and makes real difficult to have memory leaks in your code.
|
||||
by se_alloc(). By doing that you will have a tree where the tree and all
|
||||
the data pointed to will be automatically released by the system at the
|
||||
same time. This is very neat and makes it real difficult to have memory
|
||||
leaks in your code.
|
||||
|
||||
NOTE: When you insert items in the tree, it is very likely that you only
|
||||
want to add any data to the tree during the very first time you process
|
||||
|
@ -106,7 +107,7 @@ Example:
|
|||
}
|
||||
|
||||
Please do think about how and when you want to add items to the tree.
|
||||
If you dont think you should not use the if statement to protect the insert
|
||||
If you don't think you should use the if statement to protect the insert
|
||||
please reconsider and think it through one extra time.
|
||||
|
||||
|
||||
|
@ -122,7 +123,7 @@ Example:
|
|||
...
|
||||
}
|
||||
|
||||
Dont forget to check that the returned pointer is non-NULL before you
|
||||
Don't forget to check that the returned pointer is non-NULL before you
|
||||
dereference it, please.
|
||||
|
||||
|
||||
|
@ -136,14 +137,14 @@ This will list some of the more unconventional and hopefully rarely used
|
|||
functions.
|
||||
|
||||
3.1 se_tree_create_non_persistent(int type, char *name);
|
||||
Sometimes you dont want a tree that is automatically reset to become an empty
|
||||
Sometimes you don't want a tree that is automatically reset to become an empty
|
||||
tree. You might want a tree that is completely destroyed once the next
|
||||
capture file is read and even the pointer to the tree itself becomes invalid.
|
||||
|
||||
This would most likely be the case when you do NOT want a global tree
|
||||
but instead a tree that is held inside some other SE allocated structure.
|
||||
So that when that encapsulating structure is released the entire tree will
|
||||
dissapear completely as well.
|
||||
disappear completely as well.
|
||||
|
||||
Maybe you have a normal tree to track all conversations for your protocol
|
||||
and for each conversation you se_alloc() a structure to maintain some
|
||||
|
@ -161,24 +162,24 @@ typedef struct _emem_tree_key_t {
|
|||
void se_tree_insert32_array(emem_tree_t *se_tree, emem_tree_key_t *key, void *data);
|
||||
void *se_tree_lookup32_array(emem_tree_t *se_tree, emem_tree_key_t *key);
|
||||
|
||||
NOTE: the *key parameter taken by these functions WILL be modified by
|
||||
these functions so if you want to reuse the key for a second call
|
||||
you will have to reinitialize key.
|
||||
NOTE: the *key parameter taken by these functions WILL be modified by these
|
||||
functions so if you want to reuse the key for a second call you will have
|
||||
to reinitialize key.
|
||||
|
||||
|
||||
These functions are used to insert and lookup a tree where nodes are NOT
|
||||
indexed by a single guint32 but more like an array of guint32 elements.
|
||||
|
||||
These functions take as key an array of guint32 vectors : emem_tree_key_t.
|
||||
The fucntions will use vector by vector to search further down the tree
|
||||
The functions will use vector by vector to search further down the tree
|
||||
until an array element where length==0 is found indicating the end of the
|
||||
array.
|
||||
|
||||
NOTE: you MUST terminate the emem_tree_key_t array by {0, NULL}
|
||||
If you forget to do this wireshark will immediately crash.
|
||||
|
||||
NOTE: length indicates the number of guint32 values in the vector, not number
|
||||
of bytes.
|
||||
NOTE: length indicates the number of guint32 values in the vector, not the
|
||||
number of bytes.
|
||||
|
||||
If your keys are always of exactly the same length, always, and you are willing
|
||||
to bet that there can never ever be a key of a different length you can
|
||||
|
@ -191,13 +192,13 @@ get away with a simple :
|
|||
se_tree_insert32_array(se_tree, &key[0], data);
|
||||
But IF you would accidentally pass a key with a different number of guint32s
|
||||
in its vectors to this same se_tree you will crash.
|
||||
Dont use key like this. Please.
|
||||
Don't use key like this. Please.
|
||||
|
||||
|
||||
Instead use this simple workaround to make it all safe :
|
||||
Specify the first index as 1 guint32 holding the total number of guints in the
|
||||
rest of the key.
|
||||
See NFS that does this to handle filehandes that may be of different lengths
|
||||
See NFS that does this to handle filehandles that may be of different lengths
|
||||
in the same tree :
|
||||
emem_tree_key_t fhkey[3];
|
||||
guint32 tmplen;
|
||||
|
@ -215,4 +216,3 @@ in the same tree :
|
|||
|
||||
3.3 se_tree_insert_string / se_tree_lookup_string
|
||||
to be added...
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@ maybe wrong :-( The following will concentrate a bit on the win32 gtk
|
|||
port of wireshark.
|
||||
|
||||
|
||||
XXX: when ongoing file reorganisation will be completed, the following
|
||||
XXX: when ongoing file reorganization will be completed, the following
|
||||
two lists maybe won't be needed any longer!
|
||||
|
||||
libpcap related source files:
|
||||
|
@ -90,7 +90,7 @@ menu/toolbar of the parent process or the Stop button of the child processes
|
|||
dialog box (which obviously cannot be used it this dialog is hidden).
|
||||
|
||||
The Stop button will stop the capture itself, close the control pipe and then
|
||||
closes itself. The parent will detect this and stop it's part of the capture.
|
||||
closes itself. The parent will detect this and stop its part of the capture.
|
||||
|
||||
If the menu/toolbar is used, the parent will send a break signal to the child
|
||||
which will lead to the same sequence as described above.
|
||||
|
@ -103,7 +103,7 @@ message instead of a signal.
|
|||
Start capture
|
||||
-------------
|
||||
A capture is started, by specifying to start the capture at the command line,
|
||||
trigger the Ok button in the "Capture Options" dialog box and some more. The
|
||||
trigger the OK button in the "Capture Options" dialog box and some more. The
|
||||
capture start is actually done by calling the capture_start() function in
|
||||
capture.c.
|
||||
|
||||
|
@ -133,14 +133,14 @@ matched, the ld.go flag is set to FALSE, and the loop will stop shortly after.
|
|||
|
||||
Capture parent
|
||||
--------------
|
||||
In the capture parent the cap_pipe_input_cb() function is called "cyclically"
|
||||
(unix:waiting for pipe, win32:timer,1000ms) to read data from the pipe and show it
|
||||
on the main screen. While the capture is in progress, no other capture file
|
||||
In the capture parent the cap_pipe_input_cb() function is called "cyclically"
|
||||
(unix:waiting for pipe, win32:timer,1000ms) to read data from the pipe and show
|
||||
it on the main screen. While the capture is in progress, no other capture file
|
||||
can be opened.
|
||||
|
||||
|
||||
Updating
|
||||
--------
|
||||
The actual packet capturing inside the libpcap is done using it's own task.
|
||||
The actual packet capturing inside the libpcap is done using its own task.
|
||||
Catching and processing the packet data from the libpcap is done using the
|
||||
pcap_dispatch() function.
|
||||
pcap_dispatch() function.
|
||||
|
|
|
@ -57,7 +57,7 @@ faster.
|
|||
|
||||
You define a display filter function by adding an entry to
|
||||
the df_functions table in epan/dfilter/dfunctions.c. The record struct
|
||||
is defined in defunctions.h, and shown here:
|
||||
is defined in dfunctions.h, and shown here:
|
||||
|
||||
typedef struct {
|
||||
char *name;
|
||||
|
|
|
@ -76,7 +76,7 @@ Procedure
|
|||
and that will leave you with heuristic dissection.
|
||||
|
||||
|
||||
If you dont want to use the shell script wrapper, then try
|
||||
If you don't want to use the shell script wrapper, then try
|
||||
steps 3 or 4 instead.
|
||||
|
||||
3. To write the C code to stdout.
|
||||
|
@ -94,8 +94,8 @@ steps 3 or 4 instead.
|
|||
and that will leave you with heuristic dissection.
|
||||
|
||||
|
||||
5. Copy the resulting C code to your wireshark src directory, edit the 2 make files
|
||||
to include the packet-test-idl.c
|
||||
5. Copy the resulting C code to your wireshark src directory, edit the 2 make
|
||||
files to include the packet-test-idl.c
|
||||
|
||||
cp packet-test-idl.c /dir/where/wireshark/lives/
|
||||
edit Makefile.am
|
||||
|
|
|
@ -57,9 +57,9 @@ ep_new0(t) : allocate a single element of type t and fill it with 0.
|
|||
.._strndup(s,n) : allocate a chunk of size n+1 and copy s into it.
|
||||
.._memdup(s,n) : allocate n chunk and copy into it n bytes starting at s.
|
||||
|
||||
.._strdup_printf() : will calculate the size of the formated string, allocate
|
||||
.._strdup_printf() : will calculate the size of the formatted string, allocate
|
||||
a chunk for it and format the string.
|
||||
.._strdup_vprintf() : will calculate the size of the formated string,
|
||||
.._strdup_vprintf() : will calculate the size of the formatted string,
|
||||
allocate a chunk for it and format the string.
|
||||
|
||||
ep_strsplit(): will split a string based on a certain separator returning an
|
||||
|
@ -74,6 +74,6 @@ ep_stack_peek() : returns the top element of the stack without popping it.
|
|||
|
||||
3.4 tvbuff related functions
|
||||
|
||||
ep_tvb_memdup(): create an ephemeral duplicate of part of the tvbuff
|
||||
ep_tvb_memdup(): create an ephemeral duplicate of part of the tvbuff.
|
||||
|
||||
|
||||
|
|
|
@ -35,7 +35,7 @@ your package complies with this license, or we send in the marmots.
|
|||
In versions up to and including 0.99.6, it was necessary to run
|
||||
Wireshark with elevated privileges in order to be able to capture
|
||||
traffic. With version 0.99.7, all function calls that require elevated
|
||||
privliges have been moved out of the GUI to dumpcap.
|
||||
privileges have been moved out of the GUI to dumpcap.
|
||||
|
||||
WIRESHARK CONTAINS OVER ONE POINT FIVE MILLION LINES OF SOURCE CODE. DO
|
||||
NOT RUN THEM AS ROOT.
|
||||
|
|
|
@ -257,7 +257,7 @@ scripts. These now generate the additional code needed for plugin
|
|||
encapsulation in plugin.c. When using the new style build scripts,
|
||||
stips the parts outlined below:
|
||||
|
||||
o Remove the following include statments:
|
||||
o Remove the following include statements:
|
||||
|
||||
#include <gmodule.h>
|
||||
#include "moduleinfo.h"
|
||||
|
|
|
@ -143,18 +143,18 @@ stats_tree_parent_id_by_name( st, parent_name)
|
|||
Node functions
|
||||
==============
|
||||
|
||||
All the functions that opearate on nodes return a parent_id
|
||||
All the functions that operate on nodes return a parent_id
|
||||
|
||||
stats_tree_create_node(st, name, parent_id, with_children)
|
||||
Creates a node in the tree (to be used in the in init_cb)
|
||||
name: the name of the new node
|
||||
parent_id: the id of the parent_node (NULL for root)
|
||||
with_children: TRUE if this node will have "dynamically created" children
|
||||
(i.e. it will be a candidate parrent)
|
||||
(i.e. it will be a candidate parent)
|
||||
|
||||
|
||||
stats_tree_create_node_by_pname(st, name, parent_name, with_children);
|
||||
As before but creates a node using it's parent's name
|
||||
As before but creates a node using its parent's name
|
||||
|
||||
|
||||
stats_tree_create_range_node(st, name, parent_id, ...)
|
||||
|
|
|
@ -45,11 +45,11 @@ do and is done in four easy steps;
|
|||
4, In the actual dissector for that protocol, after any child dissectors
|
||||
have returned, just add 'tap_queue_packet(<protocol>_tap, pinfo, <pointer>);'
|
||||
|
||||
<pointer> is used if the tap has any special additional data to provide to
|
||||
the tap listeners. What this points to is dependent on the protocol that
|
||||
is tapped, or if there are no useful extra data to provide just specify NULL.
|
||||
For packet-rpc.c what we specify there is the persistent structure 'rpc_call'
|
||||
which contains lots of useful information the rpc layer that a listener might
|
||||
<pointer> is used if the tap has any special additional data to provide to the
|
||||
tap listeners. What this points to is dependent on the protocol that is tapped,
|
||||
or if there are no useful extra data to provide just specify NULL. For
|
||||
packet-rpc.c what we specify there is the persistent structure 'rpc_call' which
|
||||
contains lots of useful information from the rpc layer that a listener might
|
||||
need.
|
||||
|
||||
|
||||
|
@ -153,10 +153,10 @@ Redissection occurs when you apply a new display filter or if you
|
|||
change and Save/Apply a preference setting that might affect how
|
||||
packets are dissected.
|
||||
After each individual packet has been completely dissected and all
|
||||
dissectors have returned, all the tap listeners that has been flagged
|
||||
dissectors have returned, all the tap listeners that have been flagged
|
||||
to receive tap data during the dissection of the frame will be called in
|
||||
sequence.
|
||||
The order of which the tap listeners will be called is not defined.
|
||||
The order in which the tap listeners will be called is not defined.
|
||||
Not until all tap listeners for the frame has been called and returned
|
||||
will Wireshark continue to dissect the next packet.
|
||||
This is why it is important to make the *_packet() callbacks execute as
|
||||
|
|
|
@ -29,8 +29,8 @@ PDML
|
|||
====
|
||||
The PDML that wireshark produces is known not to be loadable into Analyzer.
|
||||
It causes Analyzer to crash. As such, the PDML that wireshark produces
|
||||
is be labled with a version number of "0", which means that the PDML does
|
||||
not fully follow the PDML spec. Furthemore, a creator attribute in the
|
||||
is be labeled with a version number of "0", which means that the PDML does
|
||||
not fully follow the PDML spec. Furthermore, a creator attribute in the
|
||||
"<pdml>" tag gives the version number of wireshark/tshark that produced the PDML.
|
||||
In that way, as the PDML produced by wireshark matures, but still does not
|
||||
meet the PDML spec, scripts can make intelligent decisions about how to
|
||||
|
@ -43,7 +43,7 @@ A protocol might contain one or more fields, denoted by the "<field>" tag.
|
|||
|
||||
A pseudo-protocol named "geninfo" is produced, as is required by the PDML
|
||||
spec, and exported as the first protocol after the opening "<packet>" tag.
|
||||
Its information comes from wireshark's "frame" protocol, which servers
|
||||
Its information comes from wireshark's "frame" protocol, which serves
|
||||
the similar purpose of storing packet meta-data. Both "geninfo" and
|
||||
"frame" protocols are provided in the PDML output.
|
||||
|
||||
|
@ -66,9 +66,9 @@ The "<proto>" tag
|
|||
but it can be modified by dissectors to include more data
|
||||
(tcp can do this)
|
||||
pos - the starting offset within the packet data where this
|
||||
protocol starts
|
||||
protocol starts
|
||||
size - the number of octets in the packet data that this protocol
|
||||
covers.
|
||||
covers.
|
||||
|
||||
The "<field>" tag
|
||||
=================
|
||||
|
@ -77,11 +77,11 @@ The "<field>" tag
|
|||
name - the display filter name for the field
|
||||
showname - the label used to describe this field in the protocol
|
||||
tree. This is usually the descriptive name of the protocol,
|
||||
followed by some represention of the value.
|
||||
followed by some representation of the value.
|
||||
pos - the starting offset within the packet data where this
|
||||
field starts
|
||||
field starts
|
||||
size - the number of octets in the packet data that this field
|
||||
covers.
|
||||
covers.
|
||||
value - the actual packet data, in hex, that this field covers
|
||||
show - the representation of the packet data ('value') as it would
|
||||
appear in a display filter.
|
||||
|
@ -137,7 +137,7 @@ In PDML, the "Data" protocol would become another field under HTTP:
|
|||
|
||||
tools/WiresharkXML.py
|
||||
====================
|
||||
This is a python module which provides some infrastructor for
|
||||
This is a python module which provides some infrastructure for
|
||||
Python developers who wish to parse PDML. It is designed to read
|
||||
a PDML file and call a user's callback function every time a packet
|
||||
is constructed from the protocols and fields for a single packet.
|
||||
|
@ -154,7 +154,7 @@ def my_callback(packet):
|
|||
fh = open(xml_filename)
|
||||
WiresharkXML.parse_fh(fh, my_callback)
|
||||
|
||||
# Now that the script has the packet data, do someting.
|
||||
# Now that the script has the packet data, do something.
|
||||
------------------------------------------------------------
|
||||
|
||||
The object that is passed to the callback function is an
|
||||
|
@ -180,7 +180,7 @@ Field objects, if any, that are contained. The "children" list can be
|
|||
directly accessed by calling users. It will be empty of this Protocol
|
||||
or Field contains no Fields.
|
||||
|
||||
Furthemore, the Packet class is a sub-class of the PacketList class.
|
||||
Furthermore, the Packet class is a sub-class of the PacketList class.
|
||||
The PacketList class provides methods to look for protocols and fields.
|
||||
The term "item" is used when the item being looked for can be
|
||||
a protocol or a field:
|
||||
|
@ -196,10 +196,10 @@ the PDML output of tshark, pass a read filter with "-R" to tshark to
|
|||
try to reduce as much as possible the number of packets coming out of tshark.
|
||||
The less your script has to process, the faster it will be.
|
||||
|
||||
'tools/msnchat' is a sample Python program that uses WiresharkXML to parse PDML.
|
||||
Given one or more capture files, it runs tshark on each of them, providing
|
||||
a read filter to reduce tshark's output. It finds MSN Chat conversations
|
||||
in the capture file and produces nice HTML showing the conversations. It has
|
||||
only been tested with capture files containing non-simultaneous chat sessions,
|
||||
but was written to more-or-less handle any number of simultanous chat
|
||||
sessions.
|
||||
'tools/msnchat' is a sample Python program that uses WiresharkXML to parse
|
||||
PDML. Given one or more capture files, it runs tshark on each of them,
|
||||
providing a read filter to reduce tshark's output. It finds MSN Chat
|
||||
conversations in the capture file and produces nice HTML showing the
|
||||
conversations. It has only been tested with capture files containing
|
||||
non-simultaneous chat sessions, but was written to more-or-less handle any
|
||||
number of simultaneous chat sessions.
|
||||
|
|
|
@ -88,7 +88,7 @@ static void *discard_const(const void *const_ptr)
|
|||
or else filtering will not work (they would be ignored since tree\
|
||||
would be NULL). \
|
||||
DONT try to fake a node where PITEM_FINFO(pi) is NULL \
|
||||
since dissectors that want to do proto_item_set_len() ot \
|
||||
since dissectors that want to do proto_item_set_len() or \
|
||||
other operations that dereference this would crash. \
|
||||
We dont fake FT_PROTOCOL either since these are cheap and \
|
||||
some stuff (proto hier stat) assumes they always exist. \
|
||||
|
|
Loading…
Reference in New Issue