GNU cflow

Short Contents

Table of Contents

Next: , Up: (dir)

GNU cflow

This edition of the GNU Cflow Manual, last updated 11 October 2011, documents GNU cflow Version 1.4.


--- The Detailed Node Listing ---

Controlling Symbol Types

Next: , Previous: Top, Up: Top

1 Introduction to cflow

The cflow utility analyzes a collection of source files written in C programming language and outputs a graph charting dependencies between various functions.

The program is able to produce two kind of graphs: direct and reverse. Direct graph begins with the main function (main), and displays recursively all functions called by it. In contrast, reverse graph is a set of subgraphs, charting for each function its callers, in the reverse order. Due to their tree-like appearance, graphs can also be called trees.

In addition to these two output modes, cflow is able to produce a cross-reference listing of all the symbols encountered in the input files.

The utility also provides a detailed control over symbols that will appear in its output, allowing to omit those that are of no interest to the user. The exact appearance of the output graphs is also configurable.

Next: , Previous: Intro, Up: Top

2 Simple Ways to Analyze Programs with cflow.

Let's begin our acquaintance with the GNU cflow utility with an example. Suppose you have a simple implementation of whoami command and you wish to obtain a graph of function dependencies. Here is the program:

     /* whoami.c - a simple implementation of whoami utility */
     #include <pwd.h>
     #include <sys/types.h>
     #include <stdio.h>
     #include <stdlib.h>
     who_am_i (void)
       struct passwd *pw;
       char *user = NULL;
       pw = getpwuid (geteuid ());
       if (pw)
         user = pw->pw_name;
       else if ((user = getenv ("USER")) == NULL)
           fprintf (stderr, "I don't know!\n");
           return 1;
       printf ("%s\n", user);
       return 0;
     main (int argc, char **argv)
       if (argc > 1)
           fprintf (stderr, "usage: whoami\n");
           return 1;
       return who_am_i ();

Running cflow produces the following output:

     $ cflow whoami.c
     main() <int main (int argc,char **argv) at whoami.c:26>:
         who_am_i() <int who_am_i (void) at whoami.c:8>:

This is a direct call graph showing caller—callee dependencies in the input file. Each line starts with a function name, followed by a pair of parentheses to indicate that it is a function. If this function is defined in one of the input files, the line continues by displaying, within a pair of angle brackets, a function signature and the location of its definition. If the function calls another functions, the line ends with a colon. For example, the line

     main() <int main (int argc,char **argv) at whoami.c:25>:

shows that function main is defined in file whoami.c at line 25, as int main (int argc, char **argv). Terminating colon indicates that main invokes other functions.

The lines following this one show which functions are called by main. Each such line is indented by a fixed amount of white space (by default, four spaces) for each nesting level.

Usually cflow prints a full function signature. However, sometimes you may wish to omit some part of it. Several options are provided for this purpose. To print signatures without function names, use --omit-symbol-names option. To omit argument list, use --omit-arguments. These options can be needed for a variety of reasons, one of them being to make the resulting graph more compact. To illustrate their effect, here is how would the first line of the above graph look if you had used both --omit- options:

     main() <int () at whoami.c:25>:

By default, cflow starts outputting direct graph from the function called main. It is convenient when analyzing a set of input files comprising an entire C program. However, there are circumstances where a user would want to see only a part of the graph starting on particular function. Cflow allows to select such function using --main (-m) command line option. Thus, running

     cflow --main who_am_i whoami.c

on the above file will produce following graph:


Next: , Previous: Quick Start, Up: Top

3 Two Types of Flow Graphs.

In the previous chapter we have discussed direct graphs, displaying caller—callee dependencies. Another type of cflow output, called reverse graph, charts callee—caller dependencies. To produce a reverse graph, run cflow with --reverse (-r) command line option. For example, using a sample whoami.c:

     $ cflow --reverse whoami.c

This output consists of several subgraphs, each describing callers for a particular function. Thus, the first subgraph tells that the function fprintf is called from two functions: who_am_i and main. First of them is, in turn, also called directly by main.

The first thing that draws attention in the above output is that the subgraph starting with who_am_i function is repeated several times. This is a verbose output. To make it brief, use --brief (-b) command line option. For example:

     $ cflow --brief --reverse whoami.c
         main() <int main (int argc,char **argv) at whoami.c:26> [see 3]
         who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]

In brief output, once a subgraph for a given function is written, subsequent instances of calls to that function contain only its definition and the reference to the output line where the expanded subgraph can be found.

If the output graph is large, it can be tedious to find out the required line number (unless you use Emacs cflow-mode, see Emacs). For such cases a special option --number (-n) is provided, which makes cflow begin each line of the output with a reference number, that is the ordinal number of this line in the output. With this option, the above output will look like:

     $ cflow --number --brief --reverse whoami.c
         1 fprintf():
         2     who_am_i() <int who_am_i (void) at whoami.c:8>:
         5 getenv():
         7 geteuid():
         9 getpwuid():
        12 printf():

Of course, --brief and --number options take effect for both direct and reverse flow graphs.

Next: , Previous: Direct and Reverse, Up: Top

4 Various Output Formats.




     $ cflow --format=posix whoami.c
         2     fprintf: <>
         3     who_am_i: int (void), <whoami.c 8>
         4         getpwuid: <>
         5         geteuid: <>
         6         getenv: <>
         7         fprintf: <>
         8         printf: <>




     cflow --format=posix --omit-arguments \


     #! /bin/sh
     cflow --format=posix --omit-arguments \
       cflow2vcg | xvcg -

Next: , Previous: Output Formats, Up: Top

5 Handling Recursive Calls.

Sometimes programs contain functions that recursively call themselves. GNU output format provides a special indication for such functions. The definition of the recursive function is marked with an ‘(R)’ at the end of line (before terminating colon). Subsequent recursive calls to this function are marked with a ‘(recursive: see refline)’ at the end of line. Here, refline stands for the reference line number where the recursion root definition was displayed.

To illustrate this, let's consider the following program, that prints recursive listing of a directory, allowing to cut off at the arbitrary nesting level:

     #include <sys/types.h>
     #include <sys/stat.h>
     #include <dirent.h>
     #include <unistd.h>
     #include <stdio.h>
     #include <stdlib.h>
     #include <stdlib.h>
     #include <string.h>
     /* Return true if file NAME is a directory. */
     static int
     isdir (char *name)
       struct stat st;
       if (stat (name, &st))
           perror (name);
           return 0;
       return S_ISDIR (st.st_mode);
     static char *ignored_names[] = { ".", "..", NULL };
     /* Return true if NAME should not be recursed into */
     ignorent (char *name)
       char **p;
       for (p = ignored_names; *p; p++)
         if (strcmp (name, *p) == 0)
           return 1;
       return 0;
     int max_level = -1;
     /* Print contents of the directory PREFIX/NAME.
        Prefix each output line with LEVEL spaces. */
     printdir (int level, char *name)
       DIR *dir;
       struct dirent *ent;
       char cwd[512];
       if (!getcwd(cwd, sizeof cwd)) 
           perror ("cannot save cwd\n");
           _exit (1);
       chdir (name);
       dir = opendir (".");
       if (!dir)
           perror (name);
           _exit (1);
       while ((ent = readdir (dir)))
           printf ("%*.*s%s", level, level, "", ent->d_name);
           if (ignorent (ent->d_name))
             printf ("\n");
           else if (isdir (ent->d_name))
               printf ("/");
               if (level + 1 == max_level)
                 putchar ('\n');
                   printf (" contains:\n");
                   printdir (level + 1, ent->d_name);
             printf ("\n");
       closedir (dir);
       chdir (cwd);
     main (int argc, char **argv)
       if (argc < 2)
           fprintf (stderr, "usage: d [-MAX] DIR [DIR...]\n");
           return 1;
           if (!(argv[1][1] == '-' && argv[1][2] == 0))
             max_level = atoi (&argv[1][1]);
       while (--argc)
         printdir (0, *++argv);
       return 1;

Running cflow on this program produces the following graph:

     $ cflow --number d.c
         1 main() <int main (int argc,char **argv) at d.c:85>:
         2     fprintf()
         3     atoi()
         4     printdir() <void printdir (int level,char *name) at d.c:42> (R):
         5         getcwd()
         6         perror()
         7         chdir()
         8         opendir()
         9         readdir()
        10         printf()
        11         ignorent() <int ignorent (char *name) at d.c:28>:
        12             strcmp()
        13         isdir() <int isdir (char *name) at d.c:12>:
        14             stat()
        15             perror()
        16             S_ISDIR()
        17         putchar()
        18         printdir()
                     (recursive: see 4)
        19         closedir()

The printdir description in line 4 shows that the function is recursive. The recursion call is shown in line 18.

Next: , Previous: Recursive Calls, Up: Top

6 Controlling Symbol Types

An alert reader has already noticed something strange in the above output: the function _exit is missing, although according to the source file it is called twice by printdir. It is because by default cflow omits from its output all symbols beginning with underscore character. To include these symbols as well, specify -i _ (or --include _) command line option. Continuing our example:

     $ cflow --number -i _ d.c
         2     fprintf()
         3     atoi()
         5         getcwd()
         6         perror()
         7         _exit()
         8         chdir()
         9         opendir()
        10         readdir()
        11         printf()
        13             strcmp()
        15             stat()
        16             perror()
        17             S_ISDIR()
        18         putchar()
        19         printdir()
                     (recursive: see 4)
        20         closedir()

In general, --include takes an argument specifying a list of symbol classes. Default option behavior is to include the requested classes to the output. If the argument begins with a minus or caret sign, this behavior is reversed and the requested symbol classes are excluded from the output.

The symbol class ‘_’ includes symbols whose names begin with an underscore. Another useful symbol class is ‘s’, representing static functions or data. By default, static functions are always included in the output. To omit them, one can give -i ^s (or -i -s2) command line option. Our sample program d.c defines static function isdir, running cflow -i ^s, completely omits this function and its callees from the resulting graph:

     $ cflow --number -i ^s d.c
         2     fprintf()
         3     atoi()
         5         getcwd()
         6         perror()
         7         chdir()
         8         opendir()
         9         readdir()
        10         printf()
        12             strcmp()
        13         putchar()
        14         printdir()
                     (recursive: see 4)
        15         closedir()

Actually, the exclusion sign (‘^’ or ‘-’) can be used any place in -i argument, not only at the beginning. Thus, option -i _^s means “include symbols, beginning with underscore and exclude static functions”. Several -i options accumulate, so the previous example can also be written as -i _ -i ^s.

It is important to notice that by default cflow graphs contain only functions. You can, however, request displaying variables as well, by using symbol class ‘x’. This class contains all data symbols, both global and static, so to include these in the output, use option -i x. For example:

     $ cflow --number -i x d.c
         2     fprintf()
         3     stderr
         4     max_level <int max_level at d.c:37>
         5     atoi()
         7         DIR
         8         dir
         9         getcwd()
        10         perror()
        11         chdir()
        12         opendir()
        13         readdir()
        14         printf()
        16             ignored_names <char *ignored_names[] at d.c:24>
        17             strcmp()
        19             stat()
        20             perror()
        21             S_ISDIR()
        22             NULL
        23         max_level <int max_level at d.c:37>
        24         putchar()
        25         printdir()
                     (recursive: see 6)
        26         closedir()

Now, lines 3, 4, 16 and 23 show data symbols, with their definitions when available. Notice, however, lines 7 and 8. Why both type name DIR and automatic variable dir are listed as data?

To answer this question, let's first describe the cflow notion of symbols. The program keeps its symbol tables, which are initially filled with C predefined keywords. When parsing input files, cflow updates these tables. In particular, upon encountering a typedef, it registers the defined symbol as a type.

Now, DIR is not declared in d.c, so cflow has no way of knowing it is a data type. So, it supposes it is a variable. But then the input:

       DIR *dir;

is parsed as an expression, meaning “multiply DIR by dir”.

Of course, it is wrong. There are two ways to help cflow out of this confusion. You can either explicitly declare DIR as data type, or let cflow run preprocessor, so it sees the contents of the include files and determines it by itself. Running preprocessor is covered by the next chapter (see Preprocessing). In the present chapter we will concentrate on the first method.

The command line option --symbol (-s) declares a syntactic class of the symbol. Its argument consists of two strings separated by a colon:

       --symbol sym:class

The first string, sym is a C identifier to be recorded in the symbol table. The second string, class, specifies a class to be associated with this symbol. In particular, if class is ‘type’, the symbol sym will be recorded as a C type definition. Thus, to fix the above output, run:

     $ cflow --number -i x --symbol DIR:type d.c

Another important symbol type is a parameter wrapper. It is a kind of a macro, often used in sources that are meant to be compatible with pre-ANSI compilers to protect parameter declarations in function prototypes. For example, in the declaration below, taken from /usr/include/resolv.h, __P is a parameter wrapper:

     void res_npquery __P((const res_state, const u_char *, int, FILE *));

For cflow to be able to process such declarations, declare __P as a wrapper, for example:

     cflow --symbol __P:wrapper *.c

In both examples above the reason for using the --symbol option was that cflow was unable to determine what the given symbol was, either because it did not see the type definition, as it was in case with ‘DIR’, or because the macro definition was not expanded. Both cases are better solved by using preprocess mode, described in the next chapter. Nevertheless, even with preprocessor, the --symbol option remains useful, as shown in the following sections.

Next: , Up: Symbols

6.1 Syntactic classes

Generally speaking, the syntactic class of a symbol defines where in the C code this symbol can legitimately appear. There are following classes:

A keyword, like ‘if’, ‘when’ etc.
Type modifier, i.e. the symbol appearing after a data type to modify its meaning, like ‘*’.
Declaration qualifier. Can appear both before C declaration (much like ‘static’ or ‘extern’) and after a data type (like modifiers).

You would usually declare a gcc keyword ‘__extension__’ as a qualifier:

          --symbol __extension__:qualifier

A C identifier.
A C data type, like ‘int’, ‘char’, etc.
That has two meanings. First, it can be used to declare parameter wrappers when running cflow without preprocessor. This usage was described above. Second, it indicates any symbol that can appear in a declaration either before an identifier or before a terminating semicolon and optionally followed by a parenthesized expression list.

We recommended to use this class for the gcc__attribute__’ keyword.

Next: , Previous: Syntactic classes, Up: Symbols

6.2 Symbol aliases


     --symbol newsym:=oldsym



     --symbol __restrict:=restrict

Previous: Symbol aliases, Up: Symbols

6.3 GCC Initialization

The following is a recommended set of cflow initialization options for use with gcc. We suggest you to put them in your cflow.rc file (see Configuration).

     --symbol __inline:=inline
     --symbol __inline__:=inline
     --symbol __const__:=const
     --symbol __const:=const
     --symbol __restrict:=restrict
     --symbol __extension__:qualifier
     --symbol __attribute__:wrapper
     --symbol __asm__:wrapper
     --symbol __nonnull:wrapper
     --symbol __wur:wrapper

Next: , Previous: Symbols, Up: Top

7 Running Preprocessor

Cflow can preprocess input files before analyzing them, the same way cc does before compiling. Doing so allows cflow to correctly process all symbol declarations, thus avoiding the necessity to define special symbols using --symbol option, described in the previous chapter. To enable preprocessing, run the utility with --cpp (--preprocess) command line option. For our sample file d.c, this mode gives:

     $ cflow --cpp -n d.c
         2     fprintf()
         3     atoi()
         5         getcwd()
         6         perror()
         7         chdir()
         8         opendir()
         9         readdir()
        10         printf()
        12             strcmp()
        14             stat()
        15             perror()
        16         putchar()
        17         printdir()
                     (recursive: see 4)
        18         closedir()

Compare this graph with the one obtained without --cpp option (see sample flowchart). As you see, the reference to S_ISDIR is gone: the macro has been expanded. Now, try running cflow --cpp --number -i x d.c and compare the result with the graph obtained without preprocessing (see x flowchart). You will see that it produces correct results without using --symbol option.

By default --cpp runs /usr/bin/cpp. If you wish to run another preprocessor command, specify it as an argument to the option, after an equal sign. For example, cflow --cpp='cc -E' will run the C compiler as a preprocessor.

Next: , Previous: Preprocessing, Up: Top

8 Using ASCII Art to Produce Flow Graphs.

You can configure the exact appearance of cflow output flow graph using --level-indent option. The simplest use for this option is to change the default indentation per nesting level. To do so, give the option a numeric argument specifying the number of columns to indent for each nesting level. For example, the following command sets the indentation level to 2, which is half of the default:

     cflow --level-indent 2 d.c

It can be used, for instance, to keep the graph within the page margins.

However, --level-indent can do much more than that. Each line in the flow graph consists of the following graphical elements: a start marker, an end marker, with several indent fills between them. By default, both start and end markers are empty, and each indent fill contains four spaces.

If the argument to --level-indent option has the form element=string, it specifies a character string that should be output in place of a given graph element. The element names are:

start Start marker
0 Indent fill 0
1 Indent fill 1
end0 End marker 0
end1 End marker 1

Why are there two kinds of indent fills and end markers? Remember that the flow graph represents a call tree, so it contains terminal nodes (leaves), i.e. the calls that end a function, and non-terminal nodes (the calls followed by another ones on the same nesting level). The end marker 0 is for non-terminal nodes, and end marker 1 is for terminal nodes.

As for indent fills, indent fill 1 is used to represent graph edge, whereas fill 0 is used to keep the output properly aligned.

To demonstrate this, let's consider following sample program:

     /* foo.c */
         i = h();

Now, let's represent line elements by the following strings:

start ::
0 ’ (two spaces)
1 | ’ (a vertical bar and a space)
end0 +-
end1 \-

The corresponding command line will be: cflow --level begin=:: --level '0= ' --level '1=| ' --level end0='+-' --level end1='\\-' foo.c. Notice escaping the backslash characters in end1: generally speaking, string in --level-option can contain usual C escape sequences, so the backslash character itself must be escaped. Another shortcut, allowed in string is the notation CxN, where C is any single character and N is a decimal number. This notation means “repeat character C N times”. However, character ‘x’ looses its special meaning if used at the beginning of the string.

This command will produce the following output:

     ::+-main() <int main () at foo.c:3>:
     ::  +-f() <int f () at foo.c:11>:
     ::  | \-h()
     ::  \-g()

Thus, we obtained an ASCII art representation of the call tree. GNU cflow provides a special option --tree (-T), which is a shortcut for --level '0= ' --level '1=| ' --level end0='+-' --level end1='\\-'. The following is an example of flow graph produced with this option. The source file wc.c is a simple implementation of UNIX wc command, See Source of wc command.

     $ cflow --tree --brief --cpp wc.c
     +-main() <int main (int argc,char **argv) at wc.c:127>
       +-errf() <void errf (char *fmt,...) at wc.c:34>
       | \-error_print()
       |     <void error_print (int perr,char *fmt,va_list ap) at wc.c:22>
       |   +-vfprintf()
       |   +-perror()
       |   +-fprintf()
       |   \-exit()
       +-counter() <void counter (char *file) at wc.c:108>
       | +-fopen()
       | +-perrf() <void perrf (char *fmt,...) at wc.c:46>
       | | \-error_print()
       | |    <void error_print (int perr,char *fmt,va_list ap)
       | |    at wc.c:22> [see 3]
       | +-getword() <int getword (FILE *fp) at wc.c:78>
       | | +-feof()
       | | \-isword() <int isword (unsigned char c) at wc.c:64>
       | |   \-isalpha()
       | +-fclose()
       | \-report()
       |     <void report (char *file,count_t ccount,
       |       count_t wcount,count_t lcount) at wc.c:57>
       |   \-printf()
            <void report (char *file,count_t ccount,
              count_t wcount,count_t lcount) at wc.c:57> [see 17]

Next: , Previous: ASCII Tree, Up: Top

9 Cross-Reference Output.

GNU cflow is also able to produce cross-reference listings. This mode is enabled by --xref (-x) command line option. Cross-reference output lists each symbol occurrence on a separate line. Each line shows the identifier and the source location where it appears. If this location is where the symbol is defined, it is additionally marked with an asterisk and followed by the definition. For example, here is a fragment of a cross-reference output for d.c program:

     printdir * d.c:42 void printdir (int level,char *name)
     printdir   d.c:74
     printdir   d.c:102

It shows that the function printdir is defined in line 42 and referenced twice, in lines 74 and 102.

The symbols included in cross-reference listings are controlled by --include option (see –include). In addition to character classes discussed in chapter “Controlling Symbol Types” (see Symbols), an additional symbol class t controls listing of type names defined by typedef keyword.

Next: , Previous: Cross-References, Up: Top

10 Configuration Files and Variables.

As shown in the previous chapters, GNU cflow is highly configurable. Different command line options have different effects, as specifying new operation modes or altering some aspects of the output. You will likely use some options frequently, while you will use others from time to time, or not at all (See Options, for a full list of options).

The CFLOW_OPTIONS environment variable specifies default options to be placed in front of any explicit options. For example, if you set CFLOW_OPTIONS="--format=posix --cpp" in your .profile, cflow will behave as if the two options --format=posix and --cpp had been specified before any explicit options.

There is also another possibility to specify your default options. After incorporating eventual content of CFLOW_OPTIONS variable, cflow checks the value of the environment variable CFLOWRC. This value, if not empty, specifies the name of the configuration file to read. If CFLOWRC is not defined or is empty, the program attempts to read file .cflowrc in the user's home directory. It is not an error if any of these files does not exist. However, if the file does exist but cannot be processed, cflow will issue an explicit error message.

The configuration file is read line by line. Empty lines and lines beginning with usual shell comment character (‘#’) are ignored. Otherwise, the line is split into words, the same way shell does, and the resulting words are placed in the command line after any options taken from CFLOW_OPTIONS variable, but before any explicit options.

Pay attention when using such options as -D in the configuration file. The value of the -D option will be added to the preprocessor command line and will be processed by the shell, so be careful to properly quote its argument. The rule of thumb is: “use the same quoting you would have used in the shell command line”. For example, to run cc -E as a preprocessor, you can use the following configuration file:

     --cpp='cc -E'

By the way, the above example shows a way of coping with the ‘__extension__()’ construct used by gcc, i.e. by defining it to an empty string.

It may sometimes be necessary to cancel the effect of a command line option. For example, you might specify --brief in your configuration file, but then occasionally need to obtain verbose graph. To cancel the effect of any GNU cflow option that does not take arguments, prepend ‘no-’ to the corresponding long option name. Thus, specifying --no-brief cancels the effect of the previous --brief option.

Next: , Previous: Configuration, Up: Top

11 Using cflow in Makefiles.

If you wish to use cflow to analyze your project sources, Makefile or is the right place to do so. In this chapter we will describe a generic rule for If you do not use automake, you can deduce the rule for plain Makefile from this one.

Here is a check list of steps to do to set up a framework:

As an example, here are the relevant statements which we use in cflow src/

     cflow.cflow: $(cflow_CFLOW_INPUT) cflow.rc Makefile
     	CFLOWRC=$(top_srcdir)/src/cflow.rc \
     	 cflow -o$@ $(CFLOW_FLAGS) $(DEFS) \
                         $(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \
     	            $(CPPFLAGS) \

Next: , Previous: Makefiles, Up: Top

12 Complete Listing of cflow Options.

This chapter contains an alphabetical listing of all cflow command line options, with brief descriptions and cross references to more in-depth explanations in the body of the manual. Both short and long option forms are listed, so you can use this table as a quick reference.

Most of the options have a negation counterpart, an option with a reverse meaning. The name of a negation option is formed by prefixing the corresponding long option name with a no-. This feature is provided to cancel default options specified in the configuration file.

In the table below, options with negation counterparts are marked with a bullet (•).

• Assume input to be written in ANSI C. Currently this means disabling code that parses K&R function declarations. This might speed up the processing in some cases.

• Brief output. See –brief.

• Run the specified preprocessor command. See Preprocessing.

-D name[=defn]
Predefine name as a macro. Implies --cpp (see Preprocessing).

-d number
Set the depth at which the flow graph is cut off. For example, --depth=5 means the graph will contain function calls up to the 5th nesting level.

Set debugging level. The default number is 1. Use this option if you are developing and/or debugging cflow.

• Prepend the output with a line telling Emacs to use cflow mode when visiting this file. Implies --format=gnu. See –emacs.

-f name
Use given output format name. Valid names are gnu (see GNU Output Format) and posix (see POSIX Output Format).

Display usage summary with short explanation for each option.

-I dir
Add the directory dir to the list of directories to be searched for header files. Implies --cpp (see Preprocessing).

-i spec
Control the number of included symbols. Spec is a string consisting of characters, specifying what class of symbols to include in the output. Valid spec symbols are:
Exclude symbols denoted by the following letters.
Include symbols denoted by the following letters (default).
Symbols whose names begin with an underscore.
Static symbols.
Typedefs (for cross-references only, see Cross-References).
All data symbols, both external and static.

For more information, See Symbols.

See –print-level.

Use string when indenting to each new level. See ASCII Tree.

-m name
Assume main function to be called name. See start symbol.

• Print line numbers. See –number.

-o file
Set output file name. Default is ‘-’, meaning standard output.

• Do not print argument lists in function declarations. See omit signature parts.

• Do not print symbol names in declarations. See omit signature parts. This option is turned on in ‘posix’ output mode (see POSIX Output Format.

• Print reverse call graph. See Direct and Reverse.

• Produce cross-reference listing only. See Cross-References.

-p number
Set initial token stack size to number tokens. Default is 64. The token stack grows automatically when it needs to accommodate more tokens than its current size, so it is seldom necessary to use this option.

Run the specified preprocessor command. See –cpp.

-s sym:class
In the first form, registers symbol sym in the syntactic class class. Valid class names are: ‘keyword’ (or ‘kw’), ‘modifier’, ‘qualifier’, ‘identifier’, ‘type’, ‘wrapper’. Any unambiguous abbreviation of the above is also accepted. See Syntactic classes.

In the second form (with the ‘:=’ separator), defines newsym as an alias to oldsym. See Symbol aliases.

See GCC Initialization, for a practical example of using this option.

• Use source file indentation as a hint. Currently this means that the closing curly brace (‘}’) in the column zero forces cflow to close current function definition. Use this option sparingly, it may cause misinterpretation of some sources.

-U name
Cancel any previous definition of name. Implies --cpp (see Preprocessing).

• Print nesting level along with the call graph. The level is printed after output line number (if --number or --format=posix is used, enclosed in curly braces.

• Use ASCII art to print graph. See ASCII Tree.

Give a short usage message.

• Verbosely list any errors encountered in the input files. The cflow notion of an error does not match that of C compiler, so by default error messages are turned off. It is useful to enable them if you suspect that cflow misinterprets the sources.

Print program version.

Next: , Previous: Options, Up: Top

13 Using cflow with GNU Emacs.

GNU cflow comes with an emacs module providing a major mode for visiting flow charts in GNU Emacs. If you have a working emacs on your machine, the module will be installed somewhere in your Emacs load-path. To load the module at startup, add the following lines to your .emacs or site-start.el file:

     (autoload 'cflow-mode "cflow-mode")
     (setq auto-mode-alist (append auto-mode-alist
                                   '(("\\.cflow$" . cflow-mode))))

The second statement associates cflow-mode with any file having suffix .cflow. If you prefer to have another suffix for flow graph files, use it instead. You can also omit this option, if you do not use any special suffix for your graph files. In this case we recommend using --emacs command line option. This option generates the first line telling Emacs to use cflow major mode when visiting the file.

The buffer opened in cflow mode is made read-only. The following key bindings are defined:

Temporarily exits from cflow mode and allows you to edit the graph file. To resume cflow mode type <M-x> cflow-mode <RET>. This option is provided mainly for debugging purposes. We do not recommend you to edit chart files, since this will change line numbering and thus prevent cflow mode from correctly tracing line references.
Go to expansion of the current graph vertex. Use this key if the point stands on a line ending with ‘[see N]’ reference. It will bring you directly to the referenced line. Use exchange-point-and-mark (by default <C-x C-x>) to return to the line you examined.
If the point is standing on a recursive function, go to the next recursion. Sets mark.
If the point is standing on a recursive function, return to its definition (a recursion root). Sets mark.
Visit the referenced source file and find the function definition.

Next: , Previous: Emacs, Up: Top

14 How to Report a Bug

Send bug reports via electronic mail to

As the purpose of bug reporting is to improve software, please be sure to include maximum information when reporting a bug. The minimal information needed is:

Next: , Previous: Reporting Bugs, Up: Top

Appendix A Source of the wc command

The source file wc.c, used to produce sample ASCII tree graph (see ascii tree).

     /* Sample implementation of wc utility. */
     #include <stdlib.h>
     #include <stdio.h>
     #include <stdarg.h>
     typedef unsigned long count_t;  /* Counter type */
     /* Current file counters: chars, words, lines */
     count_t ccount;
     count_t wcount;
     count_t lcount;
     /* Totals counters: chars, words, lines */
     count_t total_ccount = 0;
     count_t total_wcount = 0;
     count_t total_lcount = 0;
     /* Print error message and exit with error status. If PERR is not 0,
        display current errno status. */
     static void
     error_print (int perr, char *fmt, va_list ap)
       vfprintf (stderr, fmt, ap);
       if (perr)
         perror (" ");
         fprintf (stderr, "\n");
       exit (1);  
     /* Print error message and exit with error status. */
     static void
     errf (char *fmt, ...)
       va_list ap;
       va_start (ap, fmt);
       error_print (0, fmt, ap);
       va_end (ap);
     /* Print error message followed by errno status and exit
        with error code. */
     static void
     perrf (char *fmt, ...)
       va_list ap;
       va_start (ap, fmt);
       error_print (1, fmt, ap);
       va_end (ap);
     /* Output counters for given file */
     report (char *file, count_t ccount, count_t wcount, count_t lcount)
       printf ("%6lu %6lu %6lu %s\n", lcount, wcount, ccount, file);
     /* Return true if C is a valid word constituent */
     static int
     isword (unsigned char c)
       return isalpha (c);
     /* Increase character and, if necessary, line counters */
     #define COUNT(c)       \
           ccount++;        \
           if ((c) == '\n') \
     /* Get next word from the input stream. Return 0 on end
        of file or error condition. Return 1 otherwise. */
     getword (FILE *fp)
       int c;
       int word = 0;
       if (feof (fp))
         return 0;
           if (isword (c))
           COUNT (c);
       for (; c != EOF; c = getc (fp))
           COUNT (c);
           if (!isword (c))
       return c != EOF;
     /* Process file FILE. */
     counter (char *file)
       FILE *fp = fopen (file, "r");
       if (!fp)
         perrf ("cannot open file `%s'", file);
       ccount = wcount = lcount = 0;
       while (getword (fp))
       fclose (fp);
       report (file, ccount, wcount, lcount);
       total_ccount += ccount;
       total_wcount += wcount;
       total_lcount += lcount;
     main (int argc, char **argv)
       int i;
       if (argc < 2)
         errf ("usage: wc FILE [FILE...]");
         counter (argv[i]);
       if (argc > 2)
         report ("total", total_ccount, total_wcount, total_lcount);
       return 0;


Appendix B GNU Free Documentation License

Version 1.2, November 2002
     Copyright © 2000,2001,2002 Free Software Foundation, Inc.
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

























    4. Preserve all the copyright notices of the Document.
    8. Include an unaltered copy of this License.
    15. Preserve any Warranty Disclaimers.

























       Copyright (C)  year  your name.
       under the terms of the GNU Free Documentation License, Version 1.2
       or any later version published by the Free Software Foundation;
       Free Documentation License''.


         with the Invariant Sections being list their titles, with
         being list.



Previous: Copying This Manual, Up: Top

Concept Index

This is a general index of all issues discussed in this manual



[2] Notice that -i -s is a single option, in spite of -s beginning with a minus sign. Since this might be confusing, we prefer using ‘^’ instead of ‘-’ to denote symbol exclusion.