cflow(1)
cflow - generate C flowgraph
Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.
NAME cflow - generate C flowgraph SYNOPSIS cflow [-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 ) -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; } 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. 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.* 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. 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 ALSO cc(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.