Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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.24.1			  2017-07-03			      EGYPT(1)

NAME | SYNOPISIS | DESCRIPTION | OPTIONS | HOW IT WORKS | GENERATING THE RTL FILE | VIEWING THE CALL GRAPH | PRINTING THE CALL GRAPH | READING THE CALL GRAPH | INDIRECT FUNCTION CALLS | C++ SUPPORT | WHY IS IT CALLED EGYPT? | SEE ALSO | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=egypt&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help