|Hans-Joerg Schurr 522ff91119|
Dotrace is a library which allows users to trace function calls during
the execution of a C program by utilizing GCCs
functionality. The execution generates a trace file containing
addresses. This trace file can then be decoded using the provided
The tool has been tested with GCC version 6.4.0, but any more or less
recent version should work. The decoding scrip requires Python 3. It
was tested with version 3.6.4. Furthermore, the
addr2line utility is
required by the decoding script. On many platforms this utility is part
Nix users can use the provided
default.nix file with the
command to get a shell with the packages required for decoding present.
First the program and
dotrace.c must be compiled with the compilation
-finstrument-functions. The provided
dotrace.h should also
be available in the include paths of the compile.
Here is how to do this with the provided examples:
> gcc -I. -finstrument-functions examples/example1.c dotrace.c > ./a.out
This generates a file
e 0x4006c0 0x7fe810ed07e0 e 0x400840 0x4006df x 0x400840 0x4006df x 0x4006c0 0x7fe810ed07e0
This can then be decoded:
> ./dotrace_decode.py -b a.out -t trace.out Processing lines 1-4 [final block]. > cat trace.decoded Enter main from ?? (??:0) Enter square from main (??:?) Exit square Exit main
dotrace_decode script provides various command line arguments to
customize the output. This is especially helpful when comparing bigger
The filename of the trace file can be changed by overwriting the
Furthermore the two functions
dotrace.h can be used to turn tracing on and off. The
calls to these functions is not traced. To have tracing turned off
at the start of the program the
DOTRACE_SUSPEND must be set.
examples/example2.c file uses this functionality. To compile
> gcc -I. -finstrument-functions -DDOTRACE_SUSPEND examples/example2.c dotrace.c
After running the resulting program, the trace file contains only the
one call to the
square function where tracing is activated.
For a documentation of the instrumentation functionality provided by GCC see the online documentation.
The functionality of
dotrace is heavily inspired by
The etrace tool provides a similar functionality, but has not been maintained for some years.