EGYPT(1)

📦 version 1.10, in nixos 26.05, nixpkgs unstable

💖 EGYPT(1) — create call graph from gcc RTL dump, bestie 💖

okay so this is egypt(1) from the User Contributed Perl Documentation, and I'm gonna explain it like we're decoding the group chat. No cap: it's a tiny Perl script with main character energy, and it makes call graphs. Let's go. 🫶

🌸 NAME 🌸

egypt — create a call graph from a gcc RTL dump. That's the whole name, periodt. 💅

✨ SYNOPISIS ✨

not me spelling it exactly like the manual — the typo is canon, iykyk 💀

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. Lowkey does one job and ate. 💖

🌈 OPTIONS 🌈

  • omit (you pass it as --omit) — Omit the given functions from the call graph. Multiple function names may be given separated by commas. ✂️
  • include-external (you pass it as --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. Iconic delegation moment. 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. It's giving middle-management-for-compilers, and honestly? Slay. ✨

🎀 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 file. In old versions of GCC this option was called -dr (the original page says “called accepted -dr”, which is a lil typo moment), 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 -

X11 window, we love a vintage queen. 👑

🍓 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. (Yes, the original page says Graphwiz. We respect the typo.) 💅

🌟 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. Literally halting-problem levels of not-it. 😭

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 the 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 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 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. ROT13 ate and left no crumbs. 🌈

🌸 SEE ALSO 🌸

  • gcc
  • dotty
  • dot
  • neato

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

💌 cute sign-off: this page is from perl v5.42.3, dated 2012-04-14, and it's the EGYPT(1) manual. mwah 💋

📦 where this page comes from