aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2011-10-11 23:15:45 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2011-10-11 23:15:45 +0300
commit24a87761b4398c48d554ae44861b33a98c4c39e4 (patch)
treee2c719f29aa2f48afde056c1b1a508738d312520
parent17372c73a7605c1a2815c7389259cab3b8443f3f (diff)
downloadcflow-24a87761b4398c48d554ae44861b33a98c4c39e4.tar.gz
cflow-24a87761b4398c48d554ae44861b33a98c4c39e4.tar.bz2
Final cleanup before the release.release-1_4
* NEWS: Update. * README: Update. * doc/cflow.texi: Update. * src/main.c (symbol_override): pass allocated argument to install. * src/parser.c (yyparse): Return 0.
-rw-r--r--NEWS2
-rw-r--r--README16
-rw-r--r--doc/cflow.texi184
-rw-r--r--src/main.c2
-rw-r--r--src/parser.c4
5 files changed, 115 insertions, 93 deletions
diff --git a/NEWS b/NEWS
index 3e334c2..4bfa96b 100644
--- a/NEWS
+++ b/NEWS
@@ -2,13 +2,13 @@ GNU cflow NEWS -- history of user-visible changes. 2011-10-11
Copyright (C) 2005, 2006, 2007, 2009, 2010, 2011 Sergey Poznyakoff
See the end of file for copying conditions.
Please send cflow bug reports to <bug-cflow@gnu.org>.
-Version 1.4 (Git)
+Version 1.4, 2011-10-11
* Symbol aliases
The `--symbol' option has been extended to allow for defining
symbol aliases. Aliases are useful for declaring reserved
words such as `__restrict' or `__inline'. For example,
diff --git a/README b/README
index 12adbe7..e4b89ca 100644
--- a/README
+++ b/README
@@ -1,22 +1,20 @@
GNU cflow README
-Copyright (C) 2005, 2010 Sergey Poznyakoff
+Copyright (C) 2005, 2010, 2011 Sergey Poznyakoff
See the end of file for copying conditions.
* Introduction
This file contains brief information about configuring, and installing
GNU cflow. It is *not* intended as a replacement for the
documentation, instead it is provided as a brief reference only.
Please be sure to read the accompanuing documentation before using the
utility. See section `Documentation' below.
-Please read *all* sections of this `README' file before starting
-configuration. Also make sure you read `INSTALL' if you are not
-familiar with them already. Refer to file `ABOUT-NLS' for information
-regarding internationalization.
+For the generic configuration options, see the file `INSTALL'.
+Refer to file `ABOUT-NLS' for information regarding internationalization.
* History
The GNU cflow was initially written in 1997, when I needed a utility
that could display the control flow in a C program. The latest updates
date back to 1999. Then, as I no longer needed the package, it fell into
@@ -51,12 +49,18 @@ configuration option: --enable-debug, which compiles the package with
cflow.
* Installation
After running `./configure' and `make', run `make install'.
+* Configuration File
+
+The file src/cflow.rc provides a working configuration file for use
+with gcc. See the documentation, sections 6.1 "Syntactic classes" and
+6.3 "GCC Initialization", for more information.
+
* Documentation
Complete user manual in texinfo format is provided. After the
installation, it will be accessible by running `info cflow'. To read it
before installing the package, run `info -f doc/cflow' from the
package source root directory.
@@ -67,13 +71,13 @@ http://www.gnu.org/software/texinfo for information on where to obtain it.
* Bug reporting.
Send bug reports and suggestions to <bug-cflow@gnu.org>.
* Copyright Information:
-Copyright (C) 2005, Sergey Poznyakoff
+Copyright (C) 2005, 2010, 2011 Sergey Poznyakoff
Permission is granted to anyone to make or distribute verbatim copies
of this document as received, in any medium, provided that the
copyright notice and this permission notice are preserved,
thus giving the recipient permission to redistribute in turn.
diff --git a/doc/cflow.texi b/doc/cflow.texi
index 82bd028..dfb1fdf 100644
--- a/doc/cflow.texi
+++ b/doc/cflow.texi
@@ -1,8 +1,7 @@
\input texinfo @c -*-texinfo-*-
-@smallbook
@c %**start of header
@setfilename cflow.info
@settitle GNU cflow
@c %**end of header
@setchapternewpage odd
@@ -141,56 +140,56 @@ files. It is a good idea to add a node @samp{POSIX} discussing this.}
@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:
-@smallexample
+@example
@verbatiminclude whoami.c
-@end smallexample
+@end example
Running @command{cflow} produces the following output:
@cindex GNU Output Format, an example
-@smallexample
+@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 smallexample
+@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
-@smallexample
+@example
main() <int main (int argc,char **argv) at whoami.c:25>:
-@end smallexample
+@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 fixed amount of white space
-(by default four spaces) for each nesting level.
+@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
@@ -198,15 +197,15 @@ 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:
-@smallexample
+@example
main() <int () at whoami.c:25>:
-@end smallexample
+@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
@@ -214,29 +213,29 @@ 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. @command{Cflow}
allows to select such function using @option{--main} (@option{-m})
command line option. Thus, running
-@smallexample
+@example
cflow --main who_am_i whoami.c
-@end smallexample
+@end example
@noindent
on the above file will produce following graph:
-@smallexample
+@example
@group
who_am_i() <int who_am_i (void) at whoami.c:8>:
getpwuid()
geteuid()
getenv()
fprintf()
printf()
@end group
-@end smallexample
+@end example
@node Direct and Reverse
@chapter Two Types of Flow Graphs.
@cindex @option{--reverse}
@cindex @option{-r}
In the previous chapter we have discussed @dfn{direct graphs},
@@ -245,13 +244,13 @@ displaying @i{caller---callee} dependencies. Another type of
@dfn{callee---caller} dependencies. To produce a reverse graph, run
@command{cflow} with @option{--reverse} (@option{-r}) command line
option. For example, using a sample @file{whoami.c}:
@cindex reverse graph, example
@cindex reverse tree, example
-@smallexample
+@example
@group
$ @kbd{cflow --reverse whoami.c}
fprintf():
who_am_i() <int who_am_i (void) at whoami.c:8>:
main() <int main (int argc,char **argv) at whoami.c:26>
main() <int main (int argc,char **argv) at whoami.c:26>
@@ -268,30 +267,30 @@ main() <int main (int argc,char **argv) at whoami.c:26>
printf():
who_am_i() <int who_am_i (void) at whoami.c:8>:
main() <int main (int argc,char **argv) at whoami.c:26>
who_am_i() <int who_am_i (void) at whoami.c:8>:
main() <int main (int argc,char **argv) at whoami.c:26>
@end group
-@end smallexample
+@end example
This output consists of several subgraphs, each describing callers
for a particular function. Thus, the first subgraph tells that the
function @code{fprintf} is called from two functions: @code{who_am_i}
and @code{main}. First of them is, in turn, also called directly by
@code{main}.
@cindex @option{--brief} command line option introduced
@cindex @option{-b} command line option introduced
@anchor{--brief}
The first thing that draws attention in the above output is that
the subgraph starting with @code{who_am_i} function is repeated several
-times. This is @dfn{verbose} output. To make it brief, use
+times. This is a @dfn{verbose} output. To make it brief, use
@option{--brief} (@option{-b}) command line option. For example:
@cindex brief output, an example of
-@smallexample
+@example
@group
$ @kbd{cflow --brief --reverse whoami.c}
fprintf():
who_am_i() <int who_am_i (void) at whoami.c:8>:
main() <int main (int argc,char **argv) at whoami.c:26>
main() <int main (int argc,char **argv) at whoami.c:26> [see 3]
@@ -303,32 +302,32 @@ getpwuid():
who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
main() <int main (int argc,char **argv) at whoami.c:26> [see 3]
printf():
who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
@end group
-@end smallexample
+@end example
@cindex brief output described
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 @dfn{reference} to the output line where the
expanded subgraph can be found.
@cindex @option{--number} command line option introduced
@cindex @option{-n} command line option introduced
@anchor{--number}
- If the output graph is large it can be tedious to find out the
+ If the output graph is large, it can be tedious to find out the
required line number (unless you use @dfn{Emacs cflow-mode},
@pxref{Emacs}). For such cases a special option
@option{--number} (@option{-n}) is provided, which makes
@command{cflow} begin each line of the output with a @dfn{reference
number}, that is the ordinal number of this line in the output. With
this option, the above output will look like:
-@smallexample
+@example
$ @kbd{cflow --number --brief --reverse whoami.c}
@group
1 fprintf():
2 who_am_i() <int who_am_i (void) at whoami.c:8>:
3 main() <int main (int argc,char **argv) at whoami.c:26>
4 main() <int main (int argc,char **argv) at whoami.c:26> [see 3]
@@ -340,13 +339,13 @@ $ @kbd{cflow --number --brief --reverse whoami.c}
10 who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
11 main() <int main (int argc,char **argv) at whoami.c:26> [see 3]
12 printf():
13 who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
14 who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
@end group
-@end smallexample
+@end example
Of course, @option{--brief} and @option{--number} options
take effect for both direct and reverse flow graphs.
@node Output Formats
@chapter Various Output Formats.
@@ -375,23 +374,23 @@ found, the line ends with an empty pair of angle brackets.
@option{--format=posix} (@option{-f posix}) has been given, or
environment variable @env{POSIXLY_CORRECT} was set.
The output graph in POSIX format for our sample @file{whoami.c}
file will look as follows:
-@smallexample
+@example
$ @kbd{cflow --format=posix whoami.c}
1 main: int (int argc,char **argv), <whoami.c 26>
2 fprintf: <>
3 who_am_i: int (void), <whoami.c 8>
4 getpwuid: <>
5 geteuid: <>
6 getenv: <>
7 fprintf: <>
8 printf: <>
-@end smallexample
+@end example
It is not clear from the @acronym{POSIX} specification whether
the output should contain argument lists in function declarations, or
not. By default @command{cflow} will print them. However, some programs,
analyzing @command{cflow} output expect them to be absent. If you use
such a program, add @option{--omit-arguments} option to
@@ -418,33 +417,33 @@ with exactly one horizontal tabulation character per nesting level,
with an additional tab character for zeroth level and without argument
lists in function declaration. So, to produce an output suitable for
@command{cflow2vcg}, invoke @command{cflow} as
follows@footnote{(@xref{ASCII Tree, level-indent}, for the detailed
description of @option{--level-indent} option}:
-@smallexample
+@example
@group
@kbd{cflow --format=posix --omit-arguments \
--level-indent='0=\t' --level-indent='1=\t' \
--level-indent=start='\t'}
@end group
-@end smallexample
+@end example
You can use the following script to visualize call graphs using
the three tools:
-@smallexample
+@example
@group
#! /bin/sh
cflow --format=posix --omit-arguments \
--level-indent='0=\t' --level-indent='1=\t' \
--level-indent=start='\t' $* |
cflow2vcg | xvcg -
@end group
-@end smallexample
+@end example
@node Recursive Calls
@chapter Handling Recursive Calls.
@cindex Recursive functions
Sometimes programs contain functions that recursively call
themselves. GNU output format provides a special indication for such
@@ -456,20 +455,20 @@ reference line number where the @dfn{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:
-@smallexample
+@example
@verbatiminclude d.c
-@end smallexample
+@end example
Running @command{cflow} on this program produces the following graph:
@anchor{sample flowchart}
-@smallexample
+@example
$ @kbd{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()
@@ -486,13 +485,13 @@ $ @kbd{cflow --number d.c}
16 S_ISDIR()
17 putchar()
18 printdir()
<void printdir (int level,char *name) at d.c:42>
(recursive: see 4)
19 closedir()
-@end smallexample
+@end example
The @code{printdir} description in line 4 shows that the function
is recursive. The recursion call is shown in line 18.
@node Symbols
@chapter Controlling Symbol Types
@@ -502,13 +501,13 @@ above output: the function @code{_exit} is missing, although according
to the source file it is called twice by @code{printdir}. It is
because by default @command{cflow} omits from its output all symbols
beginning with underscore character. To include these symbols as well,
specify @option{-i _} (or @option{--include _}) command line option.
Continuing our example:
-@smallexample
+@example
$ @kbd{cflow --number -i _ 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()
@@ -526,13 +525,13 @@ $ @kbd{cflow --number -i _ d.c}
17 S_ISDIR()
18 putchar()
19 printdir()
<void printdir (int level,char *name) at d.c:42>
(recursive: see 4)
20 closedir()
-@end smallexample
+@end example
@cindex @option{-i} introduced
@cindex @option{--include} introduced
@cindex Symbol classes defined
@anchor{--include}
In general, @option{--include} takes an argument specifying a
@@ -552,13 +551,13 @@ is a single option, in spite of @code{-s} beginning with a minus sign.
Since this might be confusing, we prefer using @samp{^} instead of
@samp{-} to denote symbol exclusion.})
command line option. Our sample program @file{d.c} defines static
function @code{isdir}, running @command{cflow -i ^s}, completely omits
this function and its callees from the resulting graph:
-@smallexample
+@example
$ @kbd{cflow --number -i ^s 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()
@@ -571,13 +570,13 @@ $ @kbd{cflow --number -i ^s d.c}
12 strcmp()
13 putchar()
14 printdir()
<void printdir (int level,char *name) at d.c:42>
(recursive: see 4)
15 closedir()
-@end smallexample
+@end example
Actually, the exclusion sign (@samp{^} or @samp{-}) can be used
any place in @option{-i} argument, not only at the beginning. Thus,
option @option{-i _^s} means ``@i{include symbols, beginning with
underscore and exclude static functions}''. Several @option{-i} options
accumulate, so the previous example can also be written as
@@ -587,13 +586,13 @@ accumulate, so the previous example can also be written as
contain only functions. You can, however, request displaying variables
as well, by using symbol class @samp{x}. This class contains all @dfn{data
symbols}, both global and static, so to include these in the output,
use option @option{-i x}. For example:
@anchor{x flowchart}
-@smallexample
+@example
$ @kbd{cflow --number -i x d.c}
1 main() <int main (int argc,char **argv) at d.c:85>:
2 fprintf()
3 stderr
4 max_level <int max_level at d.c:37>
5 atoi()
@@ -617,13 +616,13 @@ $ @kbd{cflow --number -i x d.c}
23 max_level <int max_level at d.c:37>
24 putchar()
25 printdir()
<void printdir (int level,char *name) at d.c:42>
(recursive: see 6)
26 closedir()
-@end smallexample
+@end example
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 @code{DIR} and automatic variable @code{dir} are listed as
data?
@@ -635,15 +634,15 @@ encountering a @code{typedef}, it registers the defined symbol as a
@dfn{type}.
Now, @code{DIR} is not declared in @file{d.c}, so @command{cflow}
has no way of knowing it is a data type. So, it supposes it is a
variable. But then the input:
-@smallexample
+@example
DIR *dir;
-@end smallexample
+@end example
@noindent
is parsed as an @emph{expression}, meaning ``multiply @code{DIR} by
@code{dir}''.
Of course, it is wrong. There are two ways to help
@@ -658,52 +657,52 @@ concentrate on the first method.
@cindex @option{--symbol} introduced
@anchor{--symbol}
The command line option @option{--symbol} (@option{-s}) declares a
@dfn{syntactic class} of the symbol. Its argument consists of two
strings separated by a colon:
-@smallexample
+@example
--symbol @var{sym}:@var{class}
-@end smallexample
+@end example
@noindent
The first string, @var{sym} is a @code{C} identifier to be recorded in
the symbol table. The second string, @var{class}, specifies a class to
be associated with this symbol. In particular, if @var{class} is
@samp{type}, the symbol @var{sym} will be recorded as a @code{C} type
definition. Thus, to fix the above output, run:
-@smallexample
+@example
$ @kbd{cflow --number -i x --symbol DIR:type d.c}
-@end smallexample
+@end example
@cindex Parameter wrapper defined
@cindex @code{__P}, special handling using @option{--symbol}
Another important symbol type is a @dfn{parameter wrapper}. It is
a kind of a macro, often used in sources that are meant to be
compatible with pre-@acronym{ANSI} compilers to protect parameter
declarations in function prototypes. For example, in the declaration
below, taken from @file{/usr/include/resolv.h}, @code{__P} is a
parameter wrapper:
-@smallexample
+@example
void res_npquery __P((const res_state, const u_char *, int, FILE *));
-@end smallexample
+@end example
For @command{cflow} to be able to process such declarations,
declare @code{__P} as a wrapper, for example:
-@smallexample
+@example
cflow --symbol __P:wrapper *.c
-@end smallexample
+@end example
In both examples above the reason for using the
@option{--symbol} option was that @command{cflow} was unable to
-determine what the given symbol was either because it did not
+determine what the given symbol was, either because it did not
see the type definition, as it was in case with @samp{DIR}, or
-the macro definition was not expanded. Both cases are better
+because the macro definition was not expanded. Both cases are better
solved by using @dfn{preprocess mode}, described in the next
chapter. Nevertheless, even with preprocessor, the
@option{--symbol} option remains useful, as shown in the following
sections.
@menu
@@ -723,20 +722,21 @@ following classes:
@table @asis
@item keyword
@itemx kw
A keyword, like @samp{if}, @samp{when} etc.
@item modifier
-Type modifier, i.e. a symbol appearing after data type to modify its
+Type modifier, i.e. the symbol appearing after a data type to modify its
meaning, like @samp{*}.
@item qualifier
Declaration qualifier. Can appear both before C declaration (much like
@samp{static} or @samp{extern}) and after a data type (like
modifiers).
+@cindex __extension__
You would usually declare a @command{gcc} keyword @samp{__extension__}
as a qualifier:
@example
--symbol __extension__:qualifier
@end example
@@ -745,12 +745,13 @@ as a qualifier:
A C identifier.
@item type
A C data type, like @samp{int}, @samp{char}, etc.
@item wrapper
+@cindex __attribute__
That has two meanings. First, it can be used to declare parameter
wrappers when running @command{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.
@@ -771,22 +772,34 @@ construct:
--symbol @var{newsym}:=@var{oldsym}
@end example
As a result of this option, the symbol @var{newsym} is declared to be
the equivalent of @var{oldsym}.
+@cindex __restrict
Symbol aliasing can be regarded as defining the symbol class by
example of another symbol. It is useful for some special keywords,
such as @samp{__restrict}:
@example
--symbol __restrict:=restrict
@end example
@node GCC Initialization
@section GCC Initialization
+@cindex gcc
+@cindex __inline
+@cindex __inline__
+@cindex __const__
+@cindex __const
+@cindex __restrict
+@cindex __extension__
+@cindex __attribute__
+@cindex __asm__
+@cindex __nonnull
+@cindex __wur
The following is a recommended set of @command{cflow} initialization
options for use with @command{gcc}. We suggest you to put them in your
@file{cflow.rc} file (@pxref{Configuration}).
@example
--symbol __inline:=inline
@@ -815,13 +828,13 @@ avoiding the necessity to define special symbols using
preprocessing, run the utility with @option{--cpp}
(@option{--preprocess}) command line option. For our sample file
@file{d.c}, this mode gives:
@cindex @option{--cpp} option, an example
@cindex @option{--preprocess} option, an example
-@smallexample
+@example
$ @kbd{cflow --cpp -n 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()
@@ -837,13 +850,13 @@ $ @kbd{cflow --cpp -n d.c}
15 perror()
16 putchar()
17 printdir()
<void printdir (int level,char *name) at d.c:42>
(recursive: see 4)
18 closedir()
-@end smallexample
+@end example
Compare this graph with the one obtained without @option{--cpp}
option (@pxref{sample flowchart}). As you see, the reference to
@code{S_ISDIR} is gone: the macro has been expanded. Now, try
running @code{cflow --cpp --number -i x d.c} and compare the result
with the graph obtained without preprocessing (@pxref{x
@@ -870,15 +883,15 @@ output flow graph using @option{--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:
-@smallexample
+@example
cflow --level-indent 2 d.c
-@end smallexample
+@end example
@noindent
It can be used, for instance, to keep the graph within the page
margins.
However, @option{--level-indent} can do much more than that. Each
@@ -916,17 +929,17 @@ nesting level). The @dfn{end marker 0} is for non-terminal nodes, and
As for indent fills, @dfn{indent fill 1} is used to represent
graph edge, whereas @dfn{fill 0} is used to keep the output properly
aligned.
To demonstrate this, let's consider following sample program:
-@smallexample
+@example
@group
@verbatiminclude foo.c
@end group
-@end smallexample
+@end example
@noindent
Now, let's represent line elements by the following strings:
@multitable @columnfractions 0.2 0.8
@item start @tab @samp{::}
@@ -948,33 +961,33 @@ allowed in @var{string} is the notation @code{@var{C}x@var{N}}, where
notation means ``@i{repeat character @var{C} @var{N}
times}''. However, character @samp{x} looses its special meaning if
used at the beginning of the string.
This command will produce the following output:
-@smallexample
+@example
@group
::+-main() <int main () at foo.c:3>:
:: +-f() <int f () at foo.c:11>:
:: | \-h()
:: \-g()
@end group
-@end smallexample
+@end example
@cindex @option{--tree} introduced
@cindex @option{-T} introduced
Thus, we obtained an @dfn{ASCII art} representation of the call
tree. GNU @command{cflow} provides a special option @option{--tree}
(@option{-T}), which is a shortcut for @code{--level '0= ' --level
'1=| ' --level end0='+-' --level end1='\\-'}. The following is an
example of flow graph produced with this option. The source file
@file{wc.c} is a simple implementation of UNIX @command{wc} command,
@xref{Source of wc command}.
@anchor{ascii tree}
-@smallexample
+@example
@group
$ @kbd{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>
@@ -998,13 +1011,13 @@ $ @kbd{cflow --tree --brief --cpp wc.c}
| count_t wcount,count_t lcount) at wc.c:57>
| \-printf()
\-report()
<void report (char *file,count_t ccount,
count_t wcount,count_t lcount) at wc.c:57> [see 17]
@end group
-@end smallexample
+@end example
@node Cross-References
@chapter Cross-Reference Output.
@cindex Cross-References introduced
@cindex @option{--xref} option introduced
@@ -1012,20 +1025,20 @@ $ @kbd{cflow --tree --brief --cpp wc.c}
GNU @command{cflow} is also able to produce @dfn{cross-reference
listings}. This mode is enabled by @option{--xref} (@option{-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 cross-reference
+the definition. For example, here is a fragment of a cross-reference
output for @file{d.c} program:
-@smallexample
+@example
printdir * d.c:42 void printdir (int level,char *name)
printdir d.c:74
printdir d.c:102
-@end smallexample
+@end example
It shows that the function @code{printdir} is defined in line 42
and referenced twice, in lines 74 and 102.
The symbols included in cross-reference listings are controlled
by @option{--include} option (@pxref{--include}). In addition to
@@ -1077,25 +1090,30 @@ configuration file. The value of the @option{-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:
``@i{use the same quoting you would have used in the shell command line}''.
For example, to run @command{cc -E} as a preprocessor, you can use the
following configuration file:
-@smallexample
+@example
@group
--cpp='cc -E'
-DHAVE_CONFIG_H
--DSQUARE\\\(x\\\)=x*x
+-D__extension__\\\(c\\\)=
@end group
-@end smallexample
+@end example
+
+@cindex __extension__()
+ By the way, the above example shows a way of coping
+with the @samp{__extension__()} construct used by @command{gcc}, i.e. by
+defining it to an empty string.
@cindex Option cancellation
It may sometimes be necessary to cancel the effect of a command
line option. For example, you might specify @option{--brief} in your
configuration file, but then occasionally need to obtain verbose
-graph. To cancel effect of any GNU @command{cflow} option that does
+graph. To cancel the effect of any GNU @command{cflow} option that does
not take arguments, prepend @samp{no-} to the corresponding long
option name. Thus, specifying @option{--no-brief} cancels the effect
of the previous @option{--brief} option.
@node Makefiles
@chapter Using @command{cflow} in Makefiles.
@@ -1118,57 +1136,57 @@ options you wish to use. The variable can be empty, its main purpose
is making it possible to override @command{cflow} options by running
@command{make CFLOW_FLAGS=@dots{} chart}.
@item For each @var{program} from your @code{@var{dir}_PROGRAMS} list,
for which you want to generate a flow chart, add the following statements:
-@smallexample
+@example
@group
@var{program}_CFLOW_INPUT=$(@var{program}_OBJECTS:.$(OBJEXT)=.c)
@var{program}.cflow: @var{program}_CFLOW_INPUT cflow.rc Makefile
CFLOWRC=@var{path-to-your-cflow.rc} \
cflow -o$@@ $(CFLOW_FLAGS) $(DEFS) \
$(DEFAULT_INCLUDES) $(INCLUDES) $(AM_CPPFLAGS) \
$(CPPFLAGS) \
$(@var{program}_CFLOW_INPUT)
@end group
-@end smallexample
+@end example
@noindent
Replace @var{program} with program name and
@var{path-to-your-cflow.rc} with the full file name of your
@file{cflow.rc} file (if any). If you do not wish to use
preprocessing, remove from the @command{cflow} command line all
variables, except @code{CFLOW_FLAGS}.
@item If there are several programs built by this @file{Makefile.am},
you may wish to add a special rule, allowing to create all flow charts
with a single command, for example:
-@smallexample
+@example
flowcharts: @var{prog1}.cflow @var{prog2}.cflow ...
-@end smallexample
+@end example
@end itemize
As an example, here are the relevant statements which we use in
@command{cflow} @file{src/Makefile.am}:
-@smallexample
+@example
@group
EXTRA_DIST=cflow.rc
CFLOW_FLAGS=-i^s
cflow_CFLOW_INPUT=$(cflow_OBJECTS:.$(OBJEXT)=.c)
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) \
$(cflow_CFLOW_INPUT)
@end group
-@end smallexample
+@end example
@node Options
@chapter Complete Listing of @command{cflow} Options.
This chapter contains an alphabetical listing of all
@command{cflow} command line options, with brief descriptions and cross
references to more in-depth explanations in the body of the
@@ -1208,26 +1226,26 @@ declarations}. This might speed up the processing in some cases.
@bullet{} Run the specified preprocessor command. @xref{Preprocessing}.
@cindex @option{-D}
@cindex @option{--define}
@item -D @var{name}[=@var{defn}]
@itemx --define=@var{name}[=@var{defn}]
- Predefine @var{name} as a macro. Implies @option{-cpp}
+ Predefine @var{name} as a macro. Implies @option{--cpp}
(@pxref{Preprocessing}).
@cindex @option{-d}
@cindex @option{--depth}
@item -d @var{number}
@itemx --depth=@var{number}
Set the depth at which the flow graph is cut off. For example,
@option{--depth=5} means the graph will contain function calls up to
the 5th nesting level.
@cindex @option{--debug}
@item --debug[=@var{number}]
- Set debugging level. Default @var{number} is 1. Use this option
+ Set debugging level. The default @var{number} is 1. Use this option
if you are developing and/or debugging @command{cflow}.
@cindex @option{--emacs}
@cindex @option{--no-emacs}
@item --emacs
@bullet{} Prepend the output with a line telling Emacs to use @code{cflow}
@@ -1292,13 +1310,13 @@ For more information, @xref{Symbols}.
@item --level-indent=@var{string}
Use @var{string} when indenting to each new level. @xref{ASCII Tree}.
@cindex @option{-m}
@cindex @option{--main}
@item -m @var{name}
-@item --main=@var{name}
+@itemx --main=@var{name}
Assume main function to be called @var{name}. @xref{start symbol}.
@cindex @option{-n}
@cindex @option{--number}
@cindex @option{--no-number}
@item -n
@@ -1364,13 +1382,13 @@ use this option.
@cindex @option{-s}
@cindex @option{--symbol}
@item -s @var{sym}:@var{class}
@itemx --symbol=@var{sym}:@var{class}
@itemx --symbol=@var{newsym}:=@var{oldsym}
@anchor{symbol types}
- In first form, registers symbol @var{sym} in the syntactic class
+ In the first form, registers symbol @var{sym} in the syntactic class
@var{class}. Valid class names are: @samp{keyword} (or @samp{kw}),
@samp{modifier}, @samp{qualifier}, @samp{identifier}, @samp{type},
@samp{wrapper}. Any unambiguous abbreviation of the above is also
accepted. @xref{Syntactic classes}.
In the second form (with the @samp{:=} separator), defines
@@ -1443,19 +1461,19 @@ sources.
providing a major mode for visiting flow charts in GNU Emacs. If you
have a working @command{emacs} on your machine, the module will be
installed somewhere in your Emacs @code{load-path}. To load the module
at startup, add the following lines to your @file{.emacs} or
@file{site-start.el} file:
-@smalllisp
+@lisp
@group
(autoload 'cflow-mode "cflow-mode")
(setq auto-mode-alist (append auto-mode-alist
'(("\\.cflow$" . cflow-mode))))
@end group
-@end smalllisp
+@end lisp
@noindent
@cindex @option{--emacs} introduced
@anchor{--emacs}
The second statement associates @code{cflow-mode} with any file having
suffix @file{.cflow}. If you prefer to have another suffix for flow
@@ -1516,15 +1534,15