Using CSjark¶

CSjark can be invoked by running the csjark.py script. The arguments must be specified according to:

csjark.py [-h] [-v] [-d] [-s] [-f [header [header ...]]]
          [-c [config [config ...]]] [-x [path [path ...]]]
          [-o [output]] [-p] [-n] [-C [path]] [-i [header [header ...]]]
          [-I [directory [directory ...]]]
          [-D [name=definition [name=definition ...]]]
          [-U [name [name ...]]] [-A [argument [argument ...]]]
          [header] [config]

Example usage:

python csjark.py -v -o dissectors headerfile.h configfile.yml

Batch mode

One of the most important features of CSjark is processing multiple C header files in one run. That can be easily achieved by specifying a directory instead of a single file as command line argument (see above):

python csjark.py headers configs

In batch mode, CSjark only generates dissectors for structs that have a configuration file with an ID (see section Dissector message ID for information how to specify dissector message ID), and for structs that depend on other structs. This speeds up the generation of dissectors, since it only generates dissectors that Wireshark can use.

Required arguments

header: a C header file to parse or directory which includes header files
config: a configuration file to parse or directory which includes configuration files

Both header and config can be:

file - CSjark processes only the specified file
directory - CSjark recursively searches the directory and processes all the appropriate files found

Optional argument list

`-h`, `--help`	Show a help message and exit.
`-v`, `--verbose`	Print detailed information.
`-d`, `--debug`	Print debugging information.
`-s`, `--strict`	Only generate dissectors for known structs.
`-f`, `--file`	Additional locations of header files.
`-c`, `--config`	Additional locations of configuration files.
`-x`, `--exclude`	File or folders to exclude from parsing.
`-o`, `--output`	Location for storing generated dissectors.
`-p`, `--placeholders`	Automatically generates config files with placeholders.
`-n`, `--nocpp`	Disables the C pre-processor.
`-C`, `--Cpppath`	Specifies the path to C preprocessor.
`-i`, `--include`	Process file as Cpp #include “file” directive
`-I`, `--Includes`	Additional directories to be searched for Cpp includes.
`-D`, `--Define`	Predefine name as a Cpp macro
`-U`, `--Undefine`	Cancel any previous Cpp definition of name
`-A`, `--Additional`	Any additional C preprocessor arguments

Optional argument details

-h, --help¶: Show a help message and exit.

-v, --verbose¶: Print detailed information.

-d, --debug¶: Print debugging information.

-s, --strict¶: Only generate dissectors for known structs. As known structs we consider only structs for which exists valid configuration file with ID defined. Also, CSjark generates dissectors for structs that depend on known structs.

-f [path [path ...]], --file [path [path ...]]¶

Specifies that CSjark looks for struct definitions in the path. There can be more than one path specified, separated by whitespace. As path there can be file and directory. In case of a directory, CSjark searches for header files recursively to maximum possible depth.

All header files found are added to the files specified by the required header argument.

Example:

csjark.py -f hdr/file1.h dir1 file2.h

-c [path [path ...]], --config [path [path ...]]¶

Specifies that CSjark looks for configuration definition files in the path. There can be more than one path specified, separated by whitespace. As path there can be file and directory. In case of a directory, CSjark searches for configuration files recursively to maximum possible depth.

All configuration files found are added to the files specified by the required config argument.

Example:

csjark.py -c etc/conf1.yml dir1 conf2.yml

-x [path [path ...]], --exclude [path [path ...]]¶

File or folders to exclude from parsing.

When using the option, CSjark will not search for header files in the path. There can be more than one path specified, separated by whitespace. As path there can be file and directory. In case of a directory, CSjark will skip header files also in its subdirectories.

-o [path], --output [path]¶

Sets location for storing generated dissectors.

If path is a directory, CSjark saves the output dissectors into this directory, otherwise CSjark saves the output dissectors into one specified file named path. If file with this name already exists, it is rewritten without warning.

Default: CSjark root directory (when the csjark.py file is located)

-p, --placeholders¶

Automatically generates configuration files with placeholders for structs without configuration.

More in section Configuration file format and structure.

-n, --nocpp¶: Disables the C pre-processor.

-C [path], --Cpppath [path]¶

Specifies the path to the external C preprocessor.

Default:

Windows, the path is ../utils/cpp.exe (uses cpp bundled with CSjark).

-i [header [header ...]], --include [header [header ...]]¶: Process header as if #include “header” appeared as the first line of the input header files

-I [directory [directory ...]], --Includes [directory [directory ...]]¶

Additional directories to be searched for Cpp includes.

Add the directory directory to the list of directories to be searched for header files. These directories are added as an argument to the preprocessor. The preprocessor can search there for those files, which are given in an #include directive of the C header input.

-D [name=definition [name=definition ...]], --Define [name=definition [name=definition ...]]¶: Predefine name as a Cpp macro, with definition definition.

-U [name [name ...]], --Undefine [name [name ...]]¶: Cancel any previous Cpp definition of name, either built in or provided with a -D option.

-A [argument [argument ...]], --Additional [argument [argument ...]]¶

Any additional C preprocessor arguments.

Adds any other arguments (additional to -D, -U and -I) to the preprocessor.