\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename cflow.info
@settitle GNU cflow
@c %**end of header
@setchapternewpage odd
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@include version.texi
@include rendition.texi
@ifinfo
@dircategory GNU programming tools
@direntry
* cflow: (cflow). Create a graph of control flow within a program.
@end direntry
@dircategory Emacs
@direntry
* cflow mode: (cflow)Emacs. Major mode for visiting cflow charts.
@end direntry
@end ifinfo
@copying
Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA
Copyright @copyright{} 2005--2022 Sergey Poznyakoff
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover texts. A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying
@titlepage
@title GNU cflow
@subtitle version @value{VERSION}, @value{UPDATED}
@author Sergey Poznyakoff.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@page
@summarycontents
@page
@contents
@ifnottex
@node Top
@top GNU cflow
This edition of the @cite{GNU Cflow Manual}, last updated @value{UPDATED},
documents GNU cflow Version @value{VERSION}.
@end ifnottex
@menu
* Intro:: Introduction to @command{cflow}.
* Quick Start:: Simple Ways to Analyze Programs with @command{cflow}.
* Direct and Reverse:: Two Types of Flow Graphs.
* Output Formats:: Supported Output Formats.
* Recursive Calls:: Handling Recursive Calls.
* Symbols:: Controlling Symbol Input and Output.
* Preprocessing:: Source Files Can Be Preprocessed Before Analyzing.
* ASCII Tree:: Using ASCII Art to Produce Flow Graphs.
* Cross-References:: Cross-Reference Output.
* Configuration:: Configuration Files and Variables.
* Makefiles:: Using @command{cflow} in Makefiles.
* Options:: Complete Listing of @command{cflow} Options.
* Exit Codes:: Exit Codes,
* Emacs:: Using @command{cflow} with GNU Emacs.
* Reporting Bugs:: How to Report a Bug.
Appendices
* Source of wc command::
* Copying This Manual:: The GNU Free Documentation License.
* Concept Index:: Index of Concepts.
@detailmenu
--- The Detailed Node Listing ---
Controlling Symbol Types
* Syntactic classes::
* Symbol aliases::
* GCC Initialization::
@end detailmenu
@end menu
@node Intro
@chapter Introduction to cflow
@pindex cflow
@cindex cflow, a description of
The @command{cflow} utility analyzes a collection of source files
written in @code{C} programming language and outputs a graph charting
dependencies between various functions.
@cindex direct tree defined
@cindex direct graph defined
@cindex reverse graph defined
@cindex reverse tree defined
The program is able to produce two kind of graphs: direct
and reverse. @dfn{Direct graph} begins with the main function
(@code{main}), and displays recursively all functions called by it.
In contrast, @dfn{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 @dfn{trees}.
In addition to these two output modes, @command{cflow} is able to
produce a @dfn{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.
@FIXME{Some notes about when the user might need the utility? For
example, to get a quick acquaintance with the program, etc.}
@FIXME{The utility should also be able to process following input file
formats: @command{yacc} and @command{lex} sources, and object
files. It is a good idea to add a node @samp{POSIX} discussing this.}
@node Quick Start
@chapter Simple Ways to Analyze Programs with @command{cflow}.
Let's begin our acquaintance with the GNU @command{cflow} utility
with an example. Suppose you have a simple implementation of
@command{whoami} command and you wish to obtain a graph of function
dependencies. Here is the program:
@example
@verbatiminclude whoami.c
@end example
Running @command{cflow} produces the following output:
@cindex GNU Output Format, an example
@example
@group
$ @kbd{cflow whoami.c}
main() <int main (int argc,char **argv) at whoami.c:26>:
fprintf()
who_am_i() <int who_am_i (void) at whoami.c:8>:
getpwuid()
geteuid()
getenv()
fprintf()
printf()
@end group
@end example
@cindex GNU Output Format described
@anchor{GNU Output Format}
This is a direct call graph showing @dfn{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
@dfn{signature} and the location of its definition. If the function
calls another functions, the line ends with a colon. For example, the
line
@example
main() <int main (int argc,char **argv) at whoami.c:25>:
@end example
@noindent
shows that function @code{main} is defined in file @file{whoami.c}
at line 25, as @code{int main (int argc, char **argv)}. Terminating
colon indicates that @code{main} invokes other functions.
The lines following this one show which functions are called by
@code{main}. Each such line is indented by a fixed amount of white space
(by default, four spaces) for each nesting level.
@cindex @option{--omit-symbol-names} option introduced
@cindex @option{--omit-arguments} option introduced
@anchor{omit signature parts}
Usually @command{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 @option{--omit-symbol-names} option. To omit argument list, use
@option{--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 @option{--omit-} options:
@example
main() <int () at whoami.c:25>:
@end example
@cindex start symbol
@cindex @option{--main} command line option introduced
@cindex @option{-m} command line option introduced
@anchor{start symbol}
By default, @command{cflow} starts outputting direct graph from
the function called @code{main}. It is convenient when analyzing a set
of input files comprising an entire @code{C} program. However, there
are circumstances where a user would want to see only a part of
the graph starting on particular function. One can instruct @command{cflow}
to start output from the desiredfunction using @option{--main} (@option{-m})
command line option. Thus, running
@example
cflow --main who_am_i whoami.c
@end example
@noindent
on the above file will produce following graph:
@example
@group
who_am_i() <int who_am_i (void) at whoami.c:8>:
getpwuid()
geteuid()
getenv()
fprintf()
printf()
@end group
@end example
Multiple @option{--main} options can be used to introduce several
start functions.
@cindex end symbol
@cindex @option{--target} command line option introduced
You
|