Whenever one has to work with
applications which use more than 10-15 functions, it becomes difficult
to understand the calling relationship between function. This
is more even more so for free software, where the code is often the
work of another person, and sometimes more than one. At times the code
is well documented (comments, design documents, etc ).
But often that is not so and the code is hard to understand for a new developer.
To work with this sort of software, one of the indispensable tools to help understand it is the call tree.
A call tree is - as the name suggests, a tree-like representation of the calls between functions. There are two types of call trees:
The static call tree : it represents all the possible calls
as defined by the source code (including those which are never accessed
because the conditions which would lead to their invocation are never
The dynamic call tree : it represents all of the actual calls invoked when a program is executed.
UNIX© platforms have utilities to produce such call trees ( e.g. cflow and gprof). However, their output (in text format) is, although perfectly usable, somewhat difficult to handle. Particularly, because by their very nature, this information lends itself better to a graphical presentation rather than text.
The graphical representation of a tree is not a simple problem.
Fortunately there is a utility which does the job very nicely: xvcg developed by I. Lemke, G. Sander<email@example.com> and the Compare Consortium and is maintained by Shantanu Tarafdar<firstname.lastname@example.org>.
In keeping with the UNIX philosophy, cflow2vcg provides, as simply as possible, the link between cflow and xvcg.
We only concern ourselves with static call trees because dynamic trees can be produced with Call Graph Drawing Interface developed by Vadim Engelson <email@example.com>.
Note : Even though cflow2vcg is only in its first release, it is still is perfectly usable.I use it in my work on a regular basis as is.
cflow2vcg is developed and distributed under the GNU General Public License - GPL. This, among other things, allows you to adapt cflow2vcg to your needs, if necessary.
In that case, I invite you to contact me at <firstname.lastname@example.org> since your modifications might be of interest to other users as well.
cflow2vcg actually runs on a Sun Solaris™
Considering its simplicity of the interface it employs, it should
present no problems in porting it to other platforms. The major
difficulty will be the output format of cflow which is not necessarily
the same on all platforms. This issue has not been addressed.
Utilities like cflow exist on the GNU/Linux platforms, but are not installed by the distributions. A quick search ought to help you find it rather quickly. For myself, the cflow which I have installed does not produce the same output as the Sun Solaris™ cflow. Ways to analyze these output formats are currently being developed.
One implementation of cflow by Andrew Moore is available at:
The latest version of cflow2vcg can handle this format.
Just like other Open Source projects, cflow2vcg uses the compile facilities offered by configure.
To compile the application, simply run the usual commands :
% gunzip -c cflow2vcg-x-x.tar.gz | tar xf - % cd cflow2vcg-x-x % ./configure % make
As always, you can control the compile with configure.
To view the available parameters, simply execute: ./configure --help.
Install cflow2vcg in /usr/local with :
% make install
Thanks to configure you can control the installation quite finely. For details, just execute :
cflow2vcg [-e | -i] [-h] [-v]
cflow2vcg reads a cflow output file from its standard input and produces an equivalent vcg formatted output file to its standard output.
The resulting file can be further manipulated with other applications which handle the VCG format, in particular by xvcg.
The VCG output file produced by cflow2vcg
allows you to limit the graph to only show calls to internal functions
(defined in the files being analyzed) or only calls to external
functions (system calls, for example). This capability is extremely
useful to understanding the various modules which make up your
Limiting the tree to display only one of these types ((internal;/external???) can be done in xvcg using the "Expose/Hide Edges... "dialog box of xvcg.
The examples are based on the cflow2vcg code.
The intermediary files used to produce these examples are available in the doc directory of the distribution :
cflow2vcg.cflow output from cflow,
cflow2vcg.vcg output produced by cflow2vcg from the previous file.
To display a graph :
% cflow cflow2vcg.c | cflow2vcg | xvcg -
The result :
Selecting only internal nodes (either via xvcg or via cflow2vcg) :
Selecting only external nodes (either via xvcg or via cflow2vcg) :
To print a graph :
% cflow cflow2vcg.c | cflow2vcg | xvcg - -psoutput file.ps % lp file.ps
xvcg provides a host of parameters to control the rendition of a print.
To find out more, consult the on-line documentation.
The principle used by cflow2vcg (at present) is very simple. It converts the cflow output line by line to VCG instructions.
This means we need to recognize whether a line corresponds to :
a declaration or definition of a symbol, in which means we must produce a node,
a simple reference, in which case we do nothing.
Don't hesitate to send me your questions, comments, bug reports and such via e-mail at:
Major changes planned :
enhancing the VCG output file to contain the maximum information produced by cflow (Cf. Section 5.2.1),
internationalization of both the VCG output and the documentation.
At present, cflow2vcg
does not use the file name of the (input??) file. This information
could be stored in one of the node's 'info' fields. It would also be
possible to use this information to limit the graph. This could lead to
producing one graph per file. This would complicate the program since
it would require that the program record this information in a
structure prior to writing it to the output file
add more explanation of the cflow2vcg options
add comments regarding cflow2dot and its options