A simple tracing tool for C code using the 'instrument-functions' feature of GCC.
Go to file
Hans-Joerg Schurr 522ff91119 Add LICENSE file 2018-03-05 11:48:34 +01:00
examples Add documentation and examples 2018-03-05 11:33:57 +01:00
LICENSE Add LICENSE file 2018-03-05 11:48:34 +01:00
README.md Add documentation and examples 2018-03-05 11:33:57 +01:00
default.nix Add default.nix 2018-02-23 19:14:35 +01:00
dotrace.c Add C files for tracing 2018-02-23 19:14:04 +01:00
dotrace.h Add documentation and examples 2018-03-05 11:33:57 +01:00
dotrace_decode.py Add error checks and more comments 2018-03-03 16:50:46 +01:00



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.


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.


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.


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.