summaryrefslogtreecommitdiffabout
path: root/doc/cflow.texi
blob: a62fecfaeffb7406d4b10779c037cf673cc0b03b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
\input texinfo @c -*-texinfo-*-
@smallbook
@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)cflow mode. 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 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, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
this GNU Manual, like GNU software.  Copies published by the Free
Software Foundation raise funds for GNU development.''
@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

@node Top, Intro, (dir), (dir)

@ifinfo
@chapter GNU cflow
This edition of the @cite{GNU Cflow Manual}, last updated @value{UPDATED},
documents GNU cflow Version @value{VERSION}.
@end ifinfo

@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.
* 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.

@end menu

@node Intro, Quick Start, Top, Top
@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, Direct and Reverse, Intro, Top
@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
@verbatiminclude whoami.c
@end smallexample

     Running @command{cflow} produces the following output:

@cindex GNU Output Format, an example
@smallexample
@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

@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
main() <int main (int argc,char **argv) at whoami.c:25>:
@end smallexample

@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.

@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:

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

@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. @command{Cflow}
allows to select such function using @option{--main} (@option{-m})
command line option. Thus, running

@smallexample
cflow --main who_am_i whoami.c
@end smallexample

@noindent
on the above file will produce following graph:

@smallexample
@group
who_am_i() <int who_am_i (void) at whoami.c:8>:
    getpwuid()
    geteuid()
    getenv()
    fprintf()
    printf()
@end group
@end smallexample

@node Direct and Reverse, Output Formats, Quick Start, Top
@chapter Two Types of Flow Graphs.
@cindex @option{--reverse}
@cindex @option{-r}
     In the previous chapter we have discussed @dfn{direct graphs},
displaying @i{caller---callee} dependencies. Another type of
@command{cflow} output, called @dfn{reverse graph}, charts
@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
@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>
getenv():
    who_am_i() <int who_am_i (void) at whoami.c:8>:
        main() <int main (int argc,char **argv) at whoami.c:26>
geteuid():
    who_am_i() <int who_am_i (void) at whoami.c:8>:
        main() <int main (int argc,char **argv) at whoami.c:26>
getpwuid():
    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>
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

     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
@option{--brief} (@option{-b}) command line option. For example:

@cindex brief output, an example of
@smallexample
@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]
getenv():
    who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
geteuid():
    who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
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

@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
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
$ @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]
    5 getenv():
    6     who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
    7 geteuid():
    8     who_am_i() <int who_am_i (void) at whoami.c:8>: [see 2]
    9 getpwuid():
   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

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

@node Output Formats, Recursive Calls, Direct and Reverse, Top
@chapter Various Output Formats.
@cindex POSIX Output described
@anchor{POSIX Output Format}
     The output format described in previous chapters is called
@dfn{GNU Output}. Beside this, @command{cflow} is also
able to produce output format defined in POSIX standard
(@url{http://www.opengroup.org/onlinepubs/009695399/utilities/cflow.html,The
Open Group Base Specifications Issue 6: cflow utility}).
In this format, each line of output
begins with a @dfn{reference number}, i.e. the ordinal number of this
line in the output, followed by indentation of fixed amount of columns
per level (@pxref{setting indentation}). Following this are the
name of the function, a colon and the function definition, if
available. The function definition is followed by the location of the
definition (file name and line number). Both definition and location
are enclosed in angle brackets. If the function definition is not
found, the line ends with an empty pair of angle brackets.

@cindex @option{--format=posix}
@cindex @option{-f posix}
@vindex POSIXLY_CORRECT
@cindex POSIX Output Format, generating
     This output format is used when either a command line option
@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
$ @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

     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
@command{cflow} command line (@pxref{omit signature parts}).
     
@FIXME{Discuss the differences and the reason
for existence of each output format. Explain that more formats
will appear in the future.}

     Future versions of @command{cflow} will offer more output
formats, including @acronym{XML} and @acronym{HTML}
outputs. Currently, you can use @command{VCG} tool
(@url{http://rw4.cs.uni-sb.de/@/users/@/sander/@/html/gsvcg1.html})
to create graphical representation of the produced graphs. To
transform @command{cflow} output to @command{xvcg} input syntax, use
@command{cflow2vcg} program
(@url{http://cflow2vcg.sourceforge.net/}). Both programs are available
under GPL.

@cindex @command{cflow2vcg}, using with @command{cflow}
@cindex @command{xvcg}, using with @command{cflow}
     @command{Cflow2vcg} expects @acronym{POSIX} call graphs, indented
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
@group
@kbd{cflow --format=posix --omit-arguments \
      --level-indent='0=\t' --level-indent='1=\t' \
      --level-indent=start='\t'}
@end group
@end smallexample

     You can use the following script to visualize call graphs using
the three tools:

@smallexample
@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

@node Recursive Calls, Symbols, Output Formats, Top
@chapter Handling Recursive Calls.
@cindex Recursive functions
     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
@samp{(R)} at the end of line (before terminating colon). Subsequent
recursive calls to this function are marked with a @samp{(recursive: see
@var{refline})} at the end of line. Here, @var{refline} stands for the
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
@verbatiminclude d.c
@end smallexample

     Running @command{cflow} on this program produces the following graph:

@anchor{sample flowchart}     
@smallexample
$ @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()
    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()
                <void printdir (int level,char *name) at d.c:42>
                (recursive: see 4)
   19         closedir()
@end smallexample

     The @code{printdir} description in line 4 shows that the function
is recursive. The recursion call is shown in line 18. 
     
@node Symbols, Preprocessing, Recursive Calls, Top
@chapter Controlling Symbol Types

     An alert reader has already noticed something strange in the
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
$ @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()
    6         perror()
    7         _exit()
    8         chdir()
    9         opendir()
   10         readdir()
   11         printf()
   12         ignorent() <int ignorent (char *name) at d.c:28>:
   13             strcmp()
   14         isdir() <int isdir (char *name) at d.c:12>:
   15             stat()
   16             perror()
   17             S_ISDIR()
   18         putchar()
   19         printdir()
                <void printdir (int level,char *name) at d.c:42>
                (recursive: see 4)
   20         closedir()
@end smallexample

@cindex @option{-i} introduced
@cindex @option{--include} introduced
@cindex Symbol classes defined
@anchor{--include}
     In general, @option{--include} takes an argument specifying a
list of @dfn{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.

@cindex Including symbols that begin with an underscore
@cindex Excluding symbol classes
     The symbol class @samp{_} includes symbols whose names begin with an
underscore. Another useful symbol class is @samp{s}, representing
@dfn{static functions or data}. By default, static functions are
always included in the output. To omit them, one can give
@option{-i ^s} (or @option{-i -s}@footnote{Notice that @option{-i -s}
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
$ @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()
    6         perror()
    7         chdir()
    8         opendir()
    9         readdir()
   10         printf()
   11         ignorent() <int ignorent (char *name) at d.c:28>:
   12             strcmp()
   13         putchar()
   14         printdir()
                <void printdir (int level,char *name) at d.c:42>
                (recursive: see 4)
   15         closedir()
@end smallexample

     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
@option{-i _ -i ^s}.

     It is important to notice that by default @command{cflow} graphs
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
$ @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()
    6     printdir() <void printdir (int level,char *name) at d.c:42> (R):
    7         DIR
    8         dir
    9         getcwd()
   10         perror()
   11         chdir()
   12         opendir()
   13         readdir()
   14         printf()
   15         ignorent() <int ignorent (char *name) at d.c:28>:
   16             ignored_names <char *ignored_names[] at d.c:24>
   17             strcmp()
   18         isdir() <int isdir (char *name) at d.c:12>:
   19             stat()
   20             perror()
   21             S_ISDIR()
   22             NULL
   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

     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? 

     To answer this question, let's first describe the @command{cflow}
notion of symbols. The program keeps its @dfn{symbol tables}, which
are initially filled with @code{C} predefined keywords. When parsing
input files, @command{cflow} updates these tables. In particular, upon
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
  DIR *dir;
@end smallexample

@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
@command{cflow} out of this confusion. You can either explicitly
declare @code{DIR} as data type, or let @command{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 (@pxref{Preprocessing}). In the present chapter we will
concentrate on the first method. 

@cindex @option{-s} introduced
@cindex @option{--symbol} introduced
@anchor{--symbol}
     Command line option @option{--symbol} (@option{-s}) declares a
type of the symbol. Its argument consists of two strings separated by
a colon:

@smallexample
  --symbol @var{sym}:@var{t}
@end smallexample

@noindent
The first string, @var{sym} is a @code{C} identifier to be recorded in
the symbol table. The second string, @var{t}, specifies a type to
be associated with this symbol. If @var{t} is a string @samp{type},
the symbol @var{sym} will be recorded as a @code{C} type
definition. Thus, to fix the above output, run:

@smallexample
$ @kbd{cflow --number -i x --symbol DIR:type d.c}
@end smallexample

@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
void res_npquery __P((const res_state, const u_char *, int, FILE *));
@end smallexample

     For @command{cflow} to be able to process such declarations,
declare @code{__P} as a wrapper, for example:

@smallexample
cflow --symbol __P:wrapper *.c
@end smallexample

@cindex @code{__attribute__}, special handling using @option{--symbol}
     Another usage for @code{wrapper} symbol type is to declare
special @dfn{attributes} often used with @command{gcc}. For example,
the following declaration:

@smallexample
void fatal_exit (void) __attribute__ ((noreturn));
@end smallexample

@noindent
will confuse @command{cflow}. To correctly process it, use option
@option{--symbol __attribute__:wrapper}.

     For the complete list of @option{--symbol} supported types,
@xref{symbol types}.

     Notice, finally, that when using @dfn{preprocess mode}, there is
no need to use @option{--symbol}, since in this mode @command{cflow}
is able to correctly determine all symbol types by itself.

@node Preprocessing, ASCII Tree, Symbols, Top
@chapter Running Preprocessor
@cindex Preprocess mode introduced
@cindex Running preprocessor
@cindex @option{--cpp} option introduced
@cindex @option{--preprocess} option introduced
     @command{Cflow} can preprocess input files before analyzing them,
the same way @command{cc} does before compiling. Doing so allows
@command{cflow} to correctly process all symbol declarations, thus
avoiding the necessity to define special symbols using
@option{--symbol} option, described in the previous chapter. To enable
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
$ @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()
    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         putchar()
   17         printdir()
                <void printdir (int level,char *name) at d.c:42>
                (recursive: see 4)
   18         closedir()
@end smallexample

     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
flowchart}). You will see that it produces correct results without
using @option{--symbol} option.

@FIXME{To preprocess or not to preprocess?}

@cindex Default preprocessor command
@cindex Preprocessor command, overriding the default
     By default @option{--cpp} runs @file{/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, @command{cflow --cpp='cc
-E'} will run the @code{C} compiler as a preprocessor.

@node ASCII Tree, Cross-References, Preprocessing, Top
@chapter Using ASCII Art to Produce Flow Graphs.
@cindex @option{--level-indent} option introduced.
@cindex output indentation level, configuring
@cindex configuring output indentation level
@anchor{setting indentation}
     You can configure the exact appearance of @command{cflow}
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
cflow --level-indent 2 d.c
@end smallexample

@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
line in the flow graph consists of the following graphical elements: a
@dfn{start marker}, an @dfn{end marker}, with several @dfn{indent fills}
between them. By default, both start and end markers are empty, and
each indent fill contains four spaces. 

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

@cindex @option{--level-indent} keywords
@vindex start, @option{--level-indent} keyword
@vindex 0, @option{--level-indent} keyword
@vindex 1, @option{--level-indent} keyword
@vindex end0, @option{--level-indent} keyword
@vindex end1, @option{--level-indent} keyword
@multitable @columnfractions 0.2 0.8
@item start @tab Start marker
@item 0     @tab Indent fill 0
@item 1     @tab Indent fill 1
@item end0  @tab End marker 0
@item end1  @tab End marker 1
@end multitable

     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 (@dfn{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 @dfn{end marker 0} is for non-terminal nodes, and
@dfn{end marker 1} is for terminal nodes.

     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
@group
@verbatiminclude foo.c
@end group
@end smallexample

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

@multitable @columnfractions 0.2 0.8
@item start @tab @samp{::}
@item 0     @tab @samp{  } (two spaces)
@item 1     @tab @samp{| } (a vertical bar and a space)
@item end0  @tab @samp{+-}
@item end1  @tab @samp{\-}
@end multitable

@cindex @option{--level-indent} string syntax
     The corresponding command line will be: @code{cflow --level
begin=:: --level '0=  ' --level '1=| ' --level end0='+-' --level
end1='\\-' foo.c}. Notice escaping the backslash characters in
@code{end1}: generally speaking, @var{string} in
@option{--level-option} can contain usual @code{C} escape sequences,
so the backslash character itself must be escaped. Another shortcut,
allowed in @var{string} is the notation @code{@var{C}x@var{N}}, where
@var{C} is any single character and @var{N} is a decimal number. This
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
@group
::+-main() <int main () at foo.c:3>:
::  +-f() <int f () at foo.c:11>:
::  | \-h()
::  \-g()
@end group
@end smallexample

@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
@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>
  |   +-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()
  \-report()
       <void report (char *file,count_t ccount,
         count_t wcount,count_t lcount) at wc.c:57> [see 17]
@end group
@end smallexample
 

@node Cross-References, Configuration, ASCII Tree, Top
@chapter Cross-Reference Output.
@cindex Cross-References introduced
@cindex @option{--xref} option introduced
@cindex @option{-x} option introduced
     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
output for @file{d.c} program:

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

     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
character classes discussed in chapter ``Controlling Symbol Types''
(@pxref{Symbols}), an additional symbol class @code{t} controls
listing of type names defined by @code{typedef} keyword.

@node Configuration, Makefiles, Cross-References, Top
@chapter Configuration Files and Variables.
     As shown in the previous chapters, GNU @command{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 (@xref{Options}, for a
full list of options).

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

@cindex Configuration file
@vindex CFLOWRC
@cindex @file{.cflowrc}
     There is also another possibility to specify your default
options. After incorporating eventual content of @env{CFLOW_OPTIONS}
variable, @command{cflow} checks the value of the environment variable
@env{CFLOWRC}. This value, if not empty, specifies the name of
the @dfn{configuration file} to read. If @env{CFLOWRC} is not defined or
is empty, the program attempts to read file @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, @command{cflow} will issue an explicit error message.

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

     Pay attention when using such options as @option{-D} in the
configuration file. The value of @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
@group
--symbol __const:type
--symbol __restrict:type
--cpp='cc -E'
-D__extension__=
-D__attribute__\\\(c\\\)=
-D__asm__\\\(c\\\)=
@end group
@end smallexample

@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
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, Options, Configuration, Top
@chapter Using @command{cflow} in Makefiles.
@cindex @file{Makefile.am}
     If you wish to use @command{cflow} to analyze your project
sources, @file{Makefile} or @file{Makefile.am} is the right place to
do so. In this chapter we will describe a generic rule for
@file{Makefile.am}. If you do not use @command{automake}, you can
deduce the rule for plain @file{Makefile} from this one.

     Here is a check list of steps to do to set up a @file{Makefile.am}
framework:

@itemize @minus
@item If you use a configuration file, add it to @code{EXTRA_DIST}
variable.

@item Add variable @code{CFLOW_FLAGS} with any special @command{cflow}
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
@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

@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
flowcharts: @var{prog1}.cflow @var{prog2}.cflow ...
@end smallexample
@end itemize

     As an example, here are the relevant statements which we use in
@command{cflow} @file{src/Makefile.am}:

@smallexample
@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

@node Options, Emacs, Makefiles, Top
@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
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 @dfn{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 @option{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 (@bullet{}).

@table @option
@cindex @option{-a}
@cindex @option{--ansi}
@cindex @option{--no-ansi}
@item -a
@itemx --ansi
     @bullet{} Assume input to be written in @acronym{ANSI} @code{C}. Currently
this means disabling code that parses @dfn{K&R function
declarations}. This might speed up the processing in some cases.

@cindex @option{-b}
@cindex @option{--brief}
@cindex @option{--no-brief}
@item -b
@itemx --brief
     @bullet{} Brief output. @xref{--brief}.

@cindex @option{--cpp}
@cindex @option{--no-cpp}
@anchor{--cpp}
@item --cpp[=@var{command}]
     @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}
(@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
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}
mode when visiting this file. Implies @option{--format=gnu}. @xref{--emacs}.

@cindex @option{-f}
@cindex @option{--format}
@item -f @var{name}
@itemx --format=@var{name}
     Use given output format @var{name}. Valid names are @code{gnu}
(@pxref{GNU Output Format}) and @code{posix} (@pxref{POSIX Output Format}).

@cindex @option{-?}
@cindex @option{--help}
@item -?
@itemx --help
     Display usage summary with short explanation for each option.

@cindex @option{-I}
@cindex @option{--include-dir}     
@item -I @var{dir}
@itemx --include-dir=@var{dir}
     Add the directory @var{dir} to the list of directories to be
searched for header files. Implies @option{--cpp} (@pxref{Preprocessing}).

@cindex @option{-i}
@cindex @option{--include}
@item -i @var{spec}
@itemx --include=@var{spec}
     Control the number of included symbols. @var{Spec} is a string
consisting of characters, specifying what class of symbols to
include in the output. Valid @var{spec} symbols are:

@table @asis
@item -
@itemx ^
     Exclude symbols denoted by the following letters.

@item +
     Include symbols denoted by the following letters (default).

@item _
     Symbols whose names begin with an underscore.

@item s
     Static symbols.

@item t
     Typedefs (for cross-references only, @pxref{Cross-References}).

@item x
     All data symbols, both external and static.
@end table

For more information, @xref{Symbols}.

@cindex @option{-l}     
@item -l
     @xref{--print-level}.

@cindex @option{--level-indent}     
@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}
     Assume main function to be called @var{name}. @xref{start symbol}.

@cindex @option{-n}
@cindex @option{--number}
@cindex @option{--no-number}
@item -n
@itemx --number
     @bullet{} Print line numbers. @xref{--number}.

@cindex @option{-o}
@cindex @option{--output}     
@item -o @var{file}
@itemx --output=@var{file}
     Set output file name. Default is @samp{-}, meaning standard output.

@cindex @option{--omit-arguments}
@item --ommit-arguments
     @bullet{} Do not print argument lists in function
declarations. @xref{omit signature parts}. 

@cindex @option{--omit-symbol-names}
@item --omit-symbol-names
     @bullet{} Do not print symbol names in declarations. @xref{omit
signature parts}. This option is turned on in @samp{posix} output
mode (@pxref{POSIX Output Format}.
          
@FIXME{I am not sure whether the one below is needed:     
@verbatim
@cindex @option{-P}
@cindex @option{--print}     
@item -P @var{opt}
@itemx --print=@var{opt}
     Set printing option. Valid @var{opt} values are: @samp{xref} (or
@samp{cross-ref}) and @samp{tree}. Any unambiguous abbreviation of the
above is also accepted.
@end verbatim
}

@cindex @option{-r}
@cindex @option{--reverse}
@cindex @option{--no-reverse}
@item -r
@itemx --reverse
     @bullet{} Print reverse call graph. @xref{Direct and Reverse}.

@cindex @option{-x}
@cindex @option{--xref}
@cindex @option{--no-xref}
@item -x
@itemx --xref
     @bullet{} Produce cross-reference listing only. @xref{Cross-References}.

@cindex @option{-p}
@cindex @option{--pushdown}     
@item -p @var{number}
@itemx --pushdown=@var{number}
     Set initial token stack size to @var{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. 

@cindex @option{--preprocess}
@item --preprocess[=@var{command}]
     Run the specified preprocessor command. @xref{--cpp}.

@cindex @option{-s}
@cindex @option{--symbol}     
@item -s @var{sym}:@var{type}
@itemx --symbol=@var{sym}:@var{type}
@anchor{symbol types}
     Define symbol @var{sym} as having type @var{type}. Valid types
are: @samp{keyword} (or @samp{kw}), @samp{modifier},
@samp{identifier}, @samp{type}, @samp{wrapper}. Any unambiguous
abbreviation of the above is also accepted. @xref{--symbol}.

@cindex @option{-S}
@cindex @option{--use-indentation}
@cindex @option{--no-use-indentation}
@item -S
@itemx --use-indentation
     @bullet{} Use source file indentation as a hint. Currently this means that
the closing curly brace (@samp{@}}) in the column zero forces
@command{cflow} to close current function definition. Use this option
sparingly, it may cause misinterpretation of some sources.

@cindex @option{-U}
@cindex @option{--undefine}
@item -U @var{name}
@itemx --undefine=@var{name}
     Cancel any previous definition of @var{name}. Implies
@option{--cpp} (@pxref{Preprocessing}).

@cindex @option{--print-level}
@cindex @option{-l}
@cindex @option{--no-print-level}
@item --print-level
@itemx -l
@anchor{--print-level}
     @bullet{} Print nesting level along with the call graph. The level is
printed after output line number (if @option{--number} or
@option{--format=posix} is used, enclosed in curly braces.

@cindex @option{-T}
@cindex @option{--tree}
@cindex @option{--no-tree}
@item -T
@itemx --tree
     @bullet{} Use ASCII art to print graph. @xref{ASCII Tree}.
 
@cindex @option{--usage}    
@item --usage
     Give a short usage message.

@cindex @option{-v}
@cindex @option{--verbose}
@cindex @option{--no-verbose}
@item -v
@itemx --verbose
     @bullet{} Verbosely list any errors encountered in the input files. The
@command{cflow} notion of an error does not match that of @code{C}
compiler, so by default error messages are turned off. It is useful to
enable them if you suspect that @command{cflow} misinterprets the
sources.

@cindex @option{-V}
@cindex @option{--version}
@item -V
@itemx --version
     Print program version.
@end table

@node Emacs, Reporting Bugs, Options, Top
@chapter Using @command{cflow} with GNU Emacs.
@cindex cflow-mode introduced
@cindex Emacs
     GNU @command{cflow} comes with an @command{emacs} module
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
@group
(autoload 'cflow-mode "cflow-mode")
(setq auto-mode-alist (append auto-mode-alist
                              '(("\\.cflow$" . cflow-mode))))
@end group
@end smalllisp

@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
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 @option{--emacs} command line option. This option
generates the first line telling Emacs to use @code{cflow} major mode
when visiting the file.

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

@table @key
@item E
     Temporarily exits from @code{cflow} mode and allows you to edit
the graph file. To resume @code{cflow} mode type @key{M-x} cflow-mode
@key{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 @code{cflow} mode from
correctly tracing line references.

@item x
     Go to expansion of the current graph vertex. Use this key if the
point stands on a line ending with @samp{[see @var{N}]} reference. It
will bring you directly to the referenced line. Use
@code{exchange-point-and-mark} (by default @key{C-x C-x}) to return to
the line you examined.

@item R
     If the point is standing on a recursive function, go to the next
recursion. Sets mark.

@item r
     If the point is standing on a recursive function, return to its
definition (a @dfn{recursion root}). Sets mark.

@item s
     Visit the referenced source file and find the function definition.
@end table

@node Reporting Bugs, Source of wc command, Emacs, Top
@chapter How to Report a Bug

Send bug reports via electronic mail to @email{bug-cflow@@gnu.org}.

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:

@itemize
@item Version of the package you are using.
@item Compilation options used when configuring the package.
@item Detailed description of the bug.
@item Conditions under which the bug appears (command line options,
input file contents, etc.)
@end itemize

@node Source of wc command, Copying This Manual, Reporting Bugs, Top
@appendix Source of @command{wc} command

     The source file @file{wc.c}, used to produce sample ASCII tree
graph (@pxref{ascii tree}).

@smallexample
@verbatiminclude wc.c
@end smallexample

@node Copying This Manual, Concept Index, Source of wc command, Top
@include fdl.texi

@node Concept Index,  , Copying This Manual, Top
@comment node-name,  next,  previous,  up
@unnumbered Concept Index

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

@printindex cp

@bye




Return to:

Send suggestions and report system problems to the System administrator.