The xtitrace program reads the trace information generated by the XTI trace from one or more files. xtitrace processes this trace information according to the options specified for xtitrace and outputs the result to the standard output.
The status is 0 after successful execution of xtitrace, otherwise not equal to 0.
Calling the xtitrace program
You call the xtitrace program as follows:
xtitrace[ -option] file ... |
-option
You use option to define which information of the trace file(s) specified by file ... is to be output. You can specify one or more of the following values for option with each xtitrace call.
You can enter the following two values for option:
c
Outputs the trace information of XTI calls for the following actions:
- Installation/deinstallation of a communications application
- Setup/shutdown of a connection
The XTI functions affected are: t_accept(), t_bind(), t_close(), t_connect(), t_listen(), t_open(), t_rcvconnect(), t_rcvdis(), t_rcvrel(), t_snddis(), t_sndrel() and t_unbind().
d
Outputs the trace information of XTI calls for data exchange.
The XTI functions affected are: t_rcv(), t_rcvudata(), t_rcvuderr(), t_snd() and t_sndudata().
m
Outputs the trace information of XTI calls not covered by the c and d options.
The XTI functions affected are: t_alloc(), t_error(), t_free(), t_getinfo(), t_getstate(), t_look(), t_optmgmt() and t_sync().
If none of the above option values are specified, all of the above trace information is printed as if
-cdm
had been specified.
v
Outputs the trace information of all XTI calls and the values of the parameters and options concerned. If parameters occur which are passed as pointers, the values of the objects addressed by the pointers are also output. However, the last requires that the data concerned was recorded during tracing (see section "Setting the XTITRACE environment variable parameters".
If the
S
option was set for XTITRACE, you should specify the value
v
for option. Specifying only
-v
has the same effect as specifying
-cdmv
.
file ...
You use file to specify the name of a file which contains binary trace data. You can also specify several file names.
XTI trace output format
The xtitrace program always starts its output with a header. After this, xtitrace writes the trace information for the separate XTI calls. Depending on the parameters set in the XTITRACE environment variable and xtitrace program, xtitrace outputs either a single line or several lines in different formats.
Header format
The header contains the following information:
XTI library version number
trace start date and time
specified values of the xtitrace output option
name(s) of the trace file(s) whose contents are output by xtitrace
Example:
XTI TRACE (V5.0) Wed Jul 26 16:29:56 2023 OPTIONS 'cdm' TRACE FILE './XTIF00677'
Format of the first output line for a logged XTI call
The trace information for an XTI call always starts with a line that has the following format:
The line starts with a time stamp:
minutes:seconds.milliseconds (e.g. 24:16.324)The millisecond accuracy depends on the hardware used.
After the time stamp comes the recorded XTI call (e.g. t_bind()). This is followed by a list enclosed in parentheses and containing the parameters and their values for the XTI call concerned (in the order required by XTI). The parameter values shown are either in decimal (%d), hexadecimal (0x%x) or symbolic (%s) form. A parameter shown in hexadecimal notation always starts with 0x.
The following applies for showing the parameters and their values:Values of pointers are shown in hexadecimal.
With parameters of type integer (e.g. fd), the corresponding value can be shown in hexadecimal, decimal or symbolic form. Parameters and their values are separated by a blank.
With XTI functions whose execution depends on the state of the transport endpoint, the trace log informs on whether the call blocks (default) or not (specification: O_NDELAY or O_NONBLOCK).
Format of additional output lines for a logged XTI call
xtitrace only outputs the trace information described below if the two following conditions are satisfied:
The XTITRACE variable parameters were set with the S option for creating the trace.
The xtitrace program parameters were set with the v option.
For parameters passed as pointers, xtitrace outputs the names and values of the data objects addressed by these pointers. The values of the data objects (e.g. structure components) are output in hexadecimal.
The trace information on structure components also contains a few special characters which have the following meaning:
>
The component concerned must be assigned a value by the calling communications application before the logged XTI function is called.
<
A value is returned in the component concerned by the logged XTI function if the XTI function executes correctly.
-
The value of the component concerned is meaningless for the logged XTI function.
---
If this is output instead of a component value, the component concerned has no value assigned.
Format of the last output line for a logged XTI call
The return value of the XTI function concerned is always output in the last line for a logged XTI call. If errors occur, t_errno, possibly errno and information on the error position (errpos) are output.
Examples
Example of a brief report
$ xtitrace -c ./XTIF00677
XTI TRACE (V5.0) Wed Jul 26 16:29:56 2023
OPTIONS 'c' TRACE FILE './XTIF00677'
29:56.000 t_open(name /dev/tcp, oflag BLOCK [0x2], info 0x0)
return: 4
29:56.000 t_bind(fd 4, req 0x0, ret 0x0)
return: 0
29:56.000 t_connect(fd 4, sndcall 0x12ee598, rcvcall 0x0) BLOCK
return: 0
$
Example of a verbose report
$ xtitrace -cv ./XTIF00677
XTI TRACE (V5.0) Wed Jul 26 16:29:56 2023
OPTIONS 'cv' TRACE FILE './XTIF00677'
29:56.000 t_open(name /dev/tcp, oflag BLOCK [0x2], info 0x0)
return: 4
29:56.000 t_bind(fd 4, req 0x0, ret 0x0)
qlen (>) 0
return: 0
29:56.000 t_connect(fd 4, sndcall 0x12ee598, rcvcall 0x0) BLOCK
sndcall: addr.maxlen(-) addr.len(>) addr.buf(>)
--- 16 0x12ee5d8
0 0002270f 7f000001 00000000 00000000 |
return: 0
$