DragonFly On-Line Manual Pages
EGYPT(1) User Contributed Perl Documentation EGYPT(1)
NAME
egypt - create call graph from gcc RTL dump
SYNOPISIS
egypt [--omit function,function,...] [--include-external] <rtl-file>... | dotty -
egypt [--omit function,function,...] [--include-external] <rtl-file>... | dot <dot-options>
DESCRIPTION
Egypt is a simple tool for creating call graphs of C programs.
OPTIONS
omit Omit the given functions from the call graph. Multiple
function names may be given separated by commas.
include-external
Include calls to external functions in the call graph. A
function is considered external if it is not defined in any of
the input files. For example, functions in the standard C
library are external. Only direct function calls will be
displayed; there is no way to display the action of taking the
address of an external function.
HOW IT WORKS
The two major tasks in creating a call graph are analyzing the syntax
of the source code to find the function calls and laying out the graph,
but Egypt actually does neither. Instead, it delegates the source code
analysis to GCC and the graph layout to Graphviz, both of which are
better at their respective jobs than egypt could ever hope to be
itself. Egypt itself is just a small Perl script that acts as glue
between these existing tools.
Egypt takes advantage of GCC's capability to dump an intermediate
representation of the program being compiled into a file (a RTL file);
this file is much easier to extract information from than a C source
file. Egypt extracts information about function calls from the RTL
file and massages it into the format used by Graphviz.
GENERATING THE RTL FILE
Compile the program or source file you want to create a call graph for
with gcc, adding the option "-fdump-rtl-expand" to CFLAGS. This option
causes gcc to dump its intermediate code representation of each file it
compiles into a a file. In old versions of GCC this option was called
accepted "-dr", but GCC 4.4.0 and newer accept only the
"-fdump-rtl-expand" form.
For example, the following works for many programs:
make clean
make CFLAGS=-fdump-rtl-expand
Depending on the GCC version, the RTL file for a source file foo.c may
be called something like foo.c.rtl, foo.c.00.rtl, or foo.c.00.expand.
VIEWING THE CALL GRAPH
To view the call graph in an X11 window, run egypt with one or more RTL
files as command line arguments and pipe its output to the dotty
program from the Graphviz package. For example, if you compiled foo.c
with "gcc -fdump-rtl-expand" to generate foo.c.00.expand, use
egypt foo.c.00.expand | dotty -
PRINTING THE CALL GRAPH
To generate a PostScript version of the call graph for printing, use
the dot program from the Graphviz package. For example, to generate a
callgraph in the file callgraph.ps fitting everything on a US letter
size page in landscape mode, try
egypt foo.c.00.rtl | dot -Grotate=90 -Gsize=11,8.5 -Tps -o callgraph.ps
Sometimes, the graph will fit better if function calls go from left to
right instead of top to bottom. The dot option -Grankdir=LR will do
that:
egypt foo.c.00.rtl | dot -Gsize=8.5,11 -Grankdir=LR -Tps -o callgraph.ps
For nontrivial programs, the graph may end up too small to comfortably
read. If that happens, try N-up printing:
egypt foo.c.00.rtl | dot -Gpage=8.5,11 -Tps -o callgraph.ps
You can also try playing with other dot options such as -Gratio, or for
a different style of graph, try using neato instead of dot. See the
Graphwiz documentation for more information about the various options
available for customizing the style of the graph.
READING THE CALL GRAPH
Function calls are displayed as solid arrows. A dotted arrow means
that the function the arrow points from takes the address of the
function the arrow points to.
INDIRECT FUNCTION CALLS
Egypt does not display indirect function calls. Doing that is
impossible in the general case: determining which functions will call
each other indirectly at runtime would require solving the halting
problem.
The dotted arrows generated by egypt are sometimes misunderstood to
represent indirect calls, but that's not the case; they represent
taking the address of a function, resulting in a function pointer.
That function pointer will typically be used to make an indirect
function call at some later time, but the call is not necessarily made
from the same function where there address was taken, and it is
generally not possible to determine where or even whether that call
will take place.
The dotted arrows may or may not be useful for understanding the
program structure depending on the particular style of programming
used. One case where they are often useful is with event-driven
programs where a sequence of events is handled by a chain of callback
functions, each one registering the address of the next with the event
handling framework before returning to the event loop. In such a
program, the dotted arrows will indicate which callbacks cause which
other callbacks to be invoked; such a graph may to be more useful than
a graph of the actual indirect calls, which would just show the event
loop calling every callback.
C++ SUPPORT
Egypt provides limited support for C++. When used with GCC version 4
or newer, egypt will automatically demangle C++ member function names
and display them in in the native C++ syntax, e.g., "C::f()". Egypt
will not display virtual function calls, because there is no easy way
to determine which virtual function is being called based on the RTL.
WHY IS IT CALLED EGYPT?
Egypt was going to be called rtlcg, short for RTL Call Graph, but it
turned out to be one of those rare cases where ROT13'ing the name made
it easier to remember and pronounce.
SEE ALSO
gcc, dotty, dot, neato
COPYRIGHT
Copyright 1994-2011 Andreas Gustafsson
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
AUTHOR
Andreas Gustafsson
perl v5.20.2 2015-08-30 EGYPT(1)