CAPITRACE(8)

NAME
capitrace - CAPI tracing program

SYNOPSIS
capitrace [-h | -]?
capitrace [options] -i [options] <trace file>
capitrace [options] {-a | -c#} [options] <trace file> [...]

DESCRIPTION
The capitrace program is used to trace CAPI calls from applications to the kernel CAPI manager and CAPI messages exchanged between them. Trace data will be saved to a file. The contents of this file can be evaluated and decoded into human readable format later with another call to capitrace.

To create CAPI traces there are two possibilities: Start an application level trace or a controller level trace. To understand the difference one must take into account the task of the kernel CAPI manager kcapimgr. It is the mediator between CAPI applications and the controller device drivers. Messages and / or function calls may be modified or delayed by the CAPI manager, according to the needs of the device driver or because of a specific situation. Thus it makes a difference at which reference point a CAPI trace is created.

Normal users are only allowed to create CAPI traces at the application level and only for applications running under their account or under a group they are a member of. Controller level traces are reserved to the root user. A root user may trace everything, even data for applications not running under his account. When interpreting a trace file created earlier there will be no check for sufficient access rights. If a user has read access to a trace file he will be able to interpret and decode the data in it.

capitrace supports the following main options on the command line:

-h | -?
    Print out some usage information about capitrace.

-a  Start an application trace. The name of a trace file must follow this option. All traced information will be written in raw binary format into this file. Some additional options may be specified between -a and the trace file name, but none of -a or -c#. They may alter the default settings for the amount of information to be traced. All additional option values specified before the trace file name are used when starting a trace.

    Only one application level trace may be started within a single call to capitrace. But additional controller level traces can be started by specifying -c# later on the command line (assumed the user has sufficient rights).

-c# Start a controller level trace. Like for starting an application trace the name of a trace file must be specified after this option. Some additional options may be specified between these two command line arguments to alter the settings for the detail mode of the trace.

    More than one trace can be started through a single program call. In order to do this one simply has to specify the options -a or -c# a second or third time on the command line, each time with a new trace file name.

-i  Interpret a formerly created CAPI trace file. This option is mutual exclusive to the two options -a and -c#. One can only create traces or interpret a trace, but not both at the same time.

    When interpreting a trace file additional options to alter the detail mode for the output may also be specified. Certainly it is not possible to invent data that is not available in the trace file. But it is possible to further reduce the detail level for the output. As an example one can create a trace with all possible information. In the later interpretation run one can extract only the specific information needed, even multiple times with different settings.

For all main commands the following additional options may be specified in place of ‘[options]’ in the lines in section SYNOPSIS. Sometimes the meaning slightly differs when given for an interpretation or a trace creation program run.

-bl#
    This option sets the maximum length of a Data-B3 block to be traced or printed in the output. The default value is 48 bytes. The setting has only an effect if Data-B3 blocks are trace or printed.

-o <file name>
    This option is only meaningful when interpreting a formerly created trace file. By default the output goes to standard output. If this option is specified, the output goes to the file with the name specified.

-tb[+|-]
    Include data blocks in the trace file or in the output. If none of ‘+’ or ‘-’ is given behind the flag the inclusion of data blocks is enabled. A ‘-’ disables and a ‘+’ enables it explicitly. The default is not to include data blocks. This setting has only an effect if Data-B3 CAPI messages are traced or printed, too.

-td[+|-]
    Include Data-B3 CAPI messages in the trace file or in the output. If none of ‘+’ or ‘-’ is given behind the flag the inclusion of Data-B3 CAPI messages is enabled. A ‘-’ disables and a ‘+’ enables it explicitly. The default is not to include Data-B3 CAPI messages. This setting has only an effect if CAPI messages in general are traced or printed, too.

-tf[+|-]
    Include CAPI function calls in the trace file or in the output. If none of ‘+’ or ‘-’ is given behind the flag the inclusion of CAPI function calls is enabled. A ‘-’ disables and a ‘+’ enables it explicitly. The default is to include CAPI function calls.

-tm[+|-]
    Include general CAPI messages in the trace file or in the output. If none of ‘+’ or ‘-’ is given behind the flag the inclusion of CAPI messages is enabled. A ‘-’ disables and a ‘+’ enables it explicitly. The default is to include general CAPI messages.

-x[+|-]
    Include a hexdump for CAPI messages in the output. If none of ‘+’ or ‘-’ is given behind the flag a hexdump for CAPI messages is enabled. A ‘-’ disables and a ‘+’ enables it explicitly. The default is to include a CAPI message hexdump. This option is only relevant when interpreting a formerly created trace file.

EXAMPLES
The following is an example for creating an application trace with all possible information:

    capitrace -a -td -tb -bl2048 output.trc

The next example creates two controller traces, one containing only function calls, the other only consisting of CAPI messages, but with all output.

    capitrace -c1 -tm- c1.trc -tf- -tm+ -c 2 -td -tb -bl 2048 c2.trc

The last example shows how to decode a trace file:

    capitrace -i c1.trc > c1.txt

SEE ALSO
capi20(3), c4b(4), kcapimgr(4), capi-trc(7). CAPI Association e.V., Common ISDN API v2.0 4th Edition, June 2001, see http://www.capi.org.

HISTORY
The capitrace tool first appeared as an add-on for FreeBSD 4.6.

AUTHORS
This manual page and capitrace were written by Thomas Wintergerst <twinterg@gmx.de>.

BUGS
Not all CAPI message constructs are currently decoded. This is especially true for the whole bunch of messages for the supplementary services, line interconnection and echo cancellation.