Mkfunctmap

About Mkfunctmap

Mkfunctmap is a Perl script that produces a graphical map of functions and function calls in a C program that was written by James Hoagland. Only those calls made to functions within the program are mapped out, so "printf" calls would not show up on the map. The functions that are in the same file (module) are shown grouped together.

Here is an example of the output for a 1000+ line program in 4 files:

Mkfunctmap was used in a study of static call graph extractors by Gail Murphy, Davis Notkin, and Erica S.-C Lan of the University of Washington. The report is here.

Implementation

Mkfunctmap is written in Perl.

The output of Mkfunctmap is a DOT language file. DOT is a directed graph layout program from AT&T Bell Labs.

Uses of Mkfunctmap

As a visualization tool, Mkfunctmap has several conceivable uses:

Documentation of structure of program with respect to functions.
Analysis of the overall module structure. The fewer arcs between modules, the better (usually).
Analysis of the placement of functions in modules. Maybe a function should be put in another module. Or perhaps a new module should be created or two combined.
The frequency of calls to functions.
Seeing if local functions truly are local.

Limitations

For ease of parsing (the program uses lexical scanning), the program (currently) makes a few assumptions about the format of the program which some classes of C programs should meet without modification. These assumptions are:

function calls need to be one line or continued with a "\"
function header needs to be at the start of a line (no spaces but return type is okay)
macros ignored so function calls within them are ignored
"}" closing a function body needs to be at the start of a line
if might fail if what looks like a function call or declaration is in a multi-line comment
? tell me of any others you find

Another assumption that is made in this version is that all function names are distinct, even across files.

Version History

Version 0.1 was written in January 1995 by James Hoagland.

Version 0.2 allows several format options for the graph. It was beta-tested by the students in ECS 165A, Database Systems, taught by Prof. Walters in Winter 1995.

Version 1.0 added the output options -mail, -dot, -mailto, and -lang, was released on February 3, 1995 and is now available (see below) .

Availability

Mkfunctmap is free for non-commercial uses. The only restriction is that you send me e-mail or a postcard telling me you are using it. If you want to use it for commercial uses, contact me.

You are free to modify the program as you wish as long as you clearly mark your changes and send me your modified version.

You can redistribute the program for no change as long as you include are reference to this WWW page.

Here is version 1.0 [4k]. Remember to name the download "mkfunctmap.pl" and to make the file executable (i.e. "chmod +x mkfunctmap.pl").

Usage

mkfunctmap.pl { source_file } [-portrait|-landscape] [-concentrate|-noconcentrate] [-fill|-nofill] [{-Ggraph_attr=value}] [{-Nnode_attr=value}] [{-Eedge_attr=value}]  [-mail|-dot] [-mailto=email_addr] [-lang=outputlang] [-help]

The -help options shows this usage.

General Usage

If you have DOT locally you can use it, otherwise, you will need to use the DOT mail server.

The C source files to be mapped are passed as input on the command line. The output is either a output language file (i.e. Postscript), a DOT language file, or sent to DOT mail server.

Getting the output language directly

If you have DOT locally, you can do this:

% mkfunctmap.pl -dot *.c > map.ps

Other output formats are available. See below.

Getting the output language code in the mail

If you don't have DOT locally, you can get the output in the mail from the mail server.

% mkfunctmap.pl -mail *.c

Then you wait for mail to arrive from the server. This typically takes 20 minutes, longer during East Coast (US) business hours. Save the body of the mail message as a postscript file.

You can control the destination of the mail message. See below.

Getting the DOT language file as output


% mkfunctmap.pl *.c > map.dot

You can now modify the output if you desire. The language is fairly intuitive, but here is a manual.

Then, if you have DOT locally:

% dot -Tps map.dot > map.ps

Otherwise, use the DOT mail server:

% Mail -s "dot -Tps" drawdag@toucan.research.att.com < map.dot

Graph formatting customization options

The following options change the way that DOT does the graph layout and the style. Most of these can be abbreviated to 4 letters. See the DOT manual for more layout and attribute info.

-portrait, -landscape: These specify that the output should be in portrait or landscape orientation. Landscape is the default.
-concentrate, -noconcentrate: These specify the DOT should or should not try to save space by concentrating edges. Default is to concentrate.
-fill, -nofill: These specify whether the graph output should fill up the page or not. Default is to not.
-Ggraph_attr=value: This specifies some graph attribute to set to some value. For example, -Gcenter=false and -Gfontsize=14. Attributes listed are on page 6 of the User's Manual.
-Nnode_attr=value: This specifies some default node attribute to set to some value. For example, -Nshape=box and -Ncolor=palevioletred. Attributes listed are on page 6 of the User's Manual.
-Eedge_attr=value: This specifies some default graph attribute to set to some value. For example, -Elabel="calls" and -Estyle=dotted. Attributes listed are on page 6 of the User's Manual.

Mkfunctmap Output Options

These options affect the output method of the program. The default is to output the DOT graph.

-dot: This indicates that the output should be passed directly into the local copy of DOT. Stdout will now be the output of DOT. This option is exclusive of -mail.
-mail: This indicates that the output should be mailed directly to somewhere in the format used with the DOT mail server. This option is exclusive of -dot.
-mailto=emailaddr: When used with -mail, this option indicates where to e-mail the output. The default is the DOT mail server.
-language=emailaddr: When used with -dot or -mail, this option indicates the language that DOT should output in. The default is postscript (ps).

Conclusion and future work

I hope you find this program useful and remember the postcard or e-mail.

Some possible future additions to the program include:

Reducing the number of limitations on the input format.
Limiting the graph presented to functions accessible from specified functions.
Providing more DOT format options.
Display of global data on the graph.
Add new languages: Perl, Pascal, C++, ...

See other programs the Jim has written

March 7, 1995