CFLOW(1) Silicon Graphics CFLOW(1)NAMEcflow - generate C flowgraph
SYNOPSIScflow [-r] [-ix] [-i_ ] [-dnum] files
DESCRIPTION
The cflow command analyzes a collection of C, yacc, and lex files and
attempts to build a graph charting the external references. Files
suffixed with .y, .l, .c, or .i are yacced, lexed, and compiled as
appropriate. The results are collected and turned into a graph which is
displayed upon the standard output.
If the environment variable _XPG is defined, cflow operates in
conformance with the X/Open XPG4 specifications. The format of the
output may differ in accordance to the XPG4 standards.
In addition to the -D, -I, and -U options [which are interpreted just as
they are by cc(1) and cpp(1)], the following options are interpreted by
cflow:
-r Reverse the ``caller:callee'' relationship producing an inverted
listing showing the callers of each function. The listing is
sorted in lexicographical order by callee.
-ix Include external and static data symbols. The default is to
include only functions in the flowgraph. If _XPG is set, then
there could be 0 or more spaces between -i and x.
-i_ Include names that begin with an underscore. The default is to
exclude these functions (and data if -ix is used). If _XPG is
set, then there could be 0 or more spaces between -i and _.
-dnum The num decimal integer indicates the depth at which the flowgraph
is cut off. By default this is a very large number. Attempts to
set the cutoff depth to a nonpositive integer are ignored. If
_XPG is set, then there could be 0 or more spaces between -d and
num.
-suppress suppressfile
Eliminates reporting of functions named in the file suppressfile.
The format of the file is discussed below.
-narrow
The output is narrowed by removing the function type output,
changing all filenames to show only the filename (no directory
path) and by changing indentation to be two spaces (indentation is
not changed for -r ).
-base basefunction
The flow reported starts at the function basefunction and only
reports descendents of that function. (This option ignored for -r
Page 1 Release 6.4
CFLOW(1) Silicon Graphics CFLOW(1)
)
-raw Instead of being processed into a cflow output, the raw cflow
information from the C compiler is passed directly to the output.
The format of this data is described below.
-rawin file
Pass in to cflow for formatting the file as if it were the output
of cflow-raw. The file must be in the proper format: if it is
not, the result will likely be chaos.
-v Print on standard error the arguments passed to sub-passes and
such other information as seems interesting.
GRAPH FORMAT
Each line of output begins with a reference number, followed by a
suitable number of tabs indicating the level, then the name of the global
symbol followed by a colon and its definition. Normally only function
names that do not begin with an underscore are listed (see the -i options
below). For information extracted from C source, the definition consists
of an abstract type declaration (e.g., char *), and, delimited by angle
brackets, the name of the source file and the line number where the
definition was found. Definitions extracted from object files indicate
type information (if possible), followed by the name of the file in which
the symbol appeared enclosed in angle brackets. Leading underscores in
C-style external names are deleted.
Once a definition of a name has been printed, subsequent references to
that name contain only the reference number of the line where the
definition may be found. For undefined references, only <> is printed.
As an example, given the following in file.c:
int i;
static int localstat;
int main(int argc, char **argv)
{
f();
g(argc,argv);
f();
return(0);
}
int f()
{
i = h();
localstat = j();
return 0;
}
Page 2 Release 6.4
CFLOW(1) Silicon Graphics CFLOW(1)
the command
cflow-ix file.c
produces the output
1 main: int (int , char *(*)), <file.c 4>
2 g: int (), <file.c 7>
3 f: int (), <file.c 12>
4 i: int, <file.c 1>
5 h: int (), <file.c 14>
6 localstat<file.c,0>: int, <file.c 2>
7 j: int (), <file.c 15>
When the nesting level becomes too deep, the output of cflow can be piped
to pr(1), using the -e option, to compress the tab expansion to something
less than every eight spaces.
To keep file-local static variables and functions from being confused
from variables and functions in other files, statics are shown with the
compilation unit name and a unique number. In the above,
localstat<file.c,0> is an example of this convention.
To be clear about functions or variables defined inside functions, the
file and line of the actual definition is mentioned and, if it is a
#include-ed file, the name of the compilation-unit file is mentioned in
parentheses. Example:
<stati1.h (in stati1.c) 2>
Static variables defined inside a function and function-local variables
and parameters are never mentioned in the cflow output.
When analyzing the structure of a program, focusing on what a single
function does (myfunc for example) is sometimes helpful. In such a case
a command like
cflow-narrow -base myfunc -suppress libcstuff file.c
may be useful. This reports only on myfunc, it keeps the output narrow
to avoid line-wrapping, and if libc.so functions are named in the file
libcstuff those (presumably well known and therefore uninteresting for
your analysis) will not be shown.
DIAGNOSTICS
Most diagnostic messages come from the C compiler. The C compiler is not
the same as cc.
Diagnostics may also come from yaccor lex, and generally appear on
standard error.
Page 3 Release 6.4
CFLOW(1) Silicon Graphics CFLOW(1)
The following come from cflow:
Static y defined in <stati1.h (in stati1.c) 2> <stati1.h (in stati2.c) 2>
<stati1.h (in stati3.c) 2> means that the variable y is defined as static
in the listed files at the listed line numbers. The parenthesized name
is the source file being compiled: whenever the source file of the
message is a #include-ed file cflow shows the name of both the the
included file and the file name presented to the C compiler front-end.
cflow Warning: Redefinitions of anotherzed : <st2.c 2> <st3.c 3> means
that the variable anotherzed is defined in the listed source files at the
specified line numbers.
cflow Warning: External zed <st2.c 1> is static in <st1.c 1> means that
the external variable zed is static in the listed file(s), which is a
little unusual.
cflow Warning: Declaration type mismatch x: means that the variable x is
declared with different types in different source files. The types and
declaration locations are shown in the message.
SUPPRESS OPTION FILE FORMAT
Any line beginning with whitespace (blank, tab, or newline) is considered
a comment and all characters in the line (up through the next newline)
are ignored.
If a line begins with other than whitespace, all characters up to the
first whitespace character are considered part of a name-to-be-
suppressed. (Any characters on the line beginning at the first
whitespace character are considered comment and (up through the next
newline) are ignored.)
The file of names to be ignored can contain as many names as desired. A
file containing zero lines or zero names-to-be-suppressed is also
allowed.
Now we turn to a description of the processing of any name-to-be-
suppressed that may have been found by the above character scanning.
Each name to be suppressed is processed by regcmp(3G) and regex(3G) and
cflow supplies a leading "^" and a trailing "$". See the regex(3G) man
page for further information about the available matching capabilities.
For example, to match strlen, one could use (strings are left justified
in the file but indented here so they stand out):
strlen
To match all functions beginning with str, one could use
str.*
To match all functions with zzyzz in the name, one could use
.*zzyzz.*
Page 4 Release 6.4
CFLOW(1) Silicon Graphics CFLOW(1)RAW DATA FORMAT
A cflow raw reference record (the format may change from release to
release) is a line of white-space separated fields. Each record
documents a single cflow instance and is terminated with a new-line. All
data is in plain text. All numbers are in decimal.
data-record-address
is the integer internal address of a compiler structure as a decimal
number. Not used by cflow.
identifier
is the name of a variable or function or is "{" if this is the
beginning of a compilation unit, or is "}" if this is the end of a
compilation unit.
code is one of D,M,A, or R. D if this is a declaration. M if this is a
modification of the variable. A if the address is taken. R if this
is a reference to the variable or function. If this is the
beginning or end of a compilation unit, the code is D.
filename
is the source file name where found.
line-number
is the line number where the reference was found. If this is the
beginning or end of a compilation unit, line-number is 0.
column-number
is the column number where the reference was found. If this is the
beginning or end of a compilation unit, column-number is 0.
type is one of B, F, or N. B means this is a function body (so code
above is D). F means this is a function, not a data variable, and
not a function body (code may be D, as a declaration, or A, or R).
N means this is not a function. If this is the beginning or end of
a compilation unit, the type is is N.
scope-level
is an integer giving the current local scope level. Local (inner)
scopes with no declarations are not interesting so they are not
counted. If this is the beginning or end of a compilation unit, the
scope is 0.
include-depth
is an integer giving the current #include nesting depth. If this is
the beginning or end of a compilation unit, the depth is 0.
data-type
is the data type represented as a C declaration with whitespace in
the declaration replaced by '~' (tilde) characters. If this is the
beginning or end of a compilation unit, data-type is "?" or, if
available, the full path name of the compilation unit.
Page 5 Release 6.4
CFLOW(1) Silicon Graphics CFLOW(1)
static-flag
is S if the item is a static function or variable or N if it is not.
If this is the beginning or end of a compilation unit, the static-
flag is N.
decl-flag
is C if this is a deClaration, F if this is a deFinition, or N if
this is neither. If this is the beginning or end of a compilation
unit, the decl-flag is N.
FILES
/usr/bin/cflow
/usr/lib/ecfe
SEE ALSOcc(1), lex(1), yacc(1), pr(1).
OPTION NOTES
The -acpp option is ignored.
The -nocpp option is ignored. However, cflow accepts files suffixed with
.i as C files. Also the -nostdinc option does not work.
cflow attempts to understand many of the options normally passed to
cc(1). Many options are irrelevant to cflow so they are silently
ignored. Others must simply be avoided on the cflow command line.
Since the compiler predefines know and created by cc are not identical
to those built into cflow, it is wise to use -show option to cc to
create a script file with the -D and -U options shown as being passed to
the compiler. Invoke cflow via the script (there are too many -D items
to do this command creation reliably on the command line). Edit the
script to remove options that cflow does not understand.
Some #pragmas known to the regular cc command are not known to cflow, so
useless warnings about unknown pragmas may appear at times.
Page 6 Release 6.4
