|
||
---|---|---|
examples | ||
LICENSE | ||
README.md | ||
default.nix | ||
dotrace.c | ||
dotrace.h | ||
dotrace_decode.py |
README.md
Dotrace
Dotrace is a library which allows users to trace function calls during
the execution of a C program by utilizing GCCs instrument-functions
functionality. The execution generates a trace file containing
addresses. This trace file can then be decoded using the provided
dotrace_decode.py
script.
Dependencies
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
of a binutils
package.
Nix users can use the provided default.nix
file with the nix-shell
command to get a shell with the packages required for decoding present.
Usage
First the program and dotrace.c
must be compiled with the compilation
option -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 trace.out
:
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
The dotrace_decode
script provides various command line arguments to
customize the output. This is especially helpful when comparing bigger
trace files.
The filename of the trace file can be changed by overwriting the
preprocessor variable DOTRACE_FILE
.
Furthermore the two functions dotrace_start
and dotrace_stop
provided in 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.
The provided examples/example2.c
file uses this functionality. To compile
it run:
> 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.
References
For a documentation of the instrumentation functionality provided by GCC see the online documentation.
The functionality of dotrace
is heavily inspired by
this
blog post.
The etrace tool provides a similar functionality, but has not been maintained for some years.