1CFLOW(1P)                  POSIX Programmer's Manual                 CFLOW(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       cflow — generate a C-language flowgraph (DEVELOPMENT)
13

SYNOPSIS

15       cflow [-r] [-d num] [-D name[=def]]... [-i incl] [-I dir]...
16           [-U dir]... file...
17

DESCRIPTION

19       The cflow utility shall analyze a collection of object files or  assem‐
20       bler,  C-language,  lex,  or  yacc source files, and attempt to build a
21       graph, written to standard output, charting the external references.
22

OPTIONS

24       The cflow utility shall conform  to  the  Base  Definitions  volume  of
25       POSIX.1‐2017,  Section 12.2, Utility Syntax Guidelines, except that the
26       order of the -D, -I, and -U  options  (which  are  identical  to  their
27       interpretation by c99) is significant.
28
29       The following options shall be supported:
30
31       -d num    Indicate  the  depth  at  which the flowgraph is cut off. The
32                 application shall ensure that the argument num is  a  decimal
33                 integer.  By  default  this is a very large number (typically
34                 greater than 32000). Attempts to set the cut-off depth  to  a
35                 non-positive integer shall be ignored.
36
37       -i incl   Increase  the  number  of  included symbols. The incl option-
38                 argument is one of the following characters:
39
40                 x     Include external and static data symbols.  The  default
41                       shall be to include only functions in the flowgraph.
42
43                 _     (Underscore)  Include  names that begin with an <under‐
44                       score>.  The default shall be to  exclude  these  func‐
45                       tions (and data if -i x is used).
46
47       -r        Reverse the caller:callee relationship, producing an inverted
48                 listing showing the callers of  each  function.  The  listing
49                 shall also be sorted in lexicographical order by callee.
50

OPERANDS

52       The following operand is supported:
53
54       file      The  pathname of a file for which a graph is to be generated.
55                 Filenames suffixed by .l shall  shall  be  taken  to  be  lex
56                 input,  .y as yacc input, .c as c99 input, and .i as the out‐
57                 put of c99 -E.  Such files shall be processed as appropriate,
58                 determined by their suffix.
59
60                 Files  suffixed  by  .s (conventionally assembler source) may
61                 have more limited information extracted from them.
62

STDIN

64       Not used.
65

INPUT FILES

67       The input files shall be object files or assembler, C-language, lex, or
68       yacc source files.
69

ENVIRONMENT VARIABLES

71       The  following  environment  variables  shall  affect  the execution of
72       cflow:
73
74       LANG      Provide a default value for  the  internationalization  vari‐
75                 ables  that are unset or null. (See the Base Definitions vol‐
76                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
77                 ables  for  the  precedence of internationalization variables
78                 used to determine the values of locale categories.)
79
80       LC_ALL    If set to a non-empty string value, override  the  values  of
81                 all the other internationalization variables.
82
83       LC_COLLATE
84                 Determine  the locale for the ordering of the output when the
85                 -r option is used.
86
87       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
88                 bytes of text data as characters (for example, single-byte as
89                 opposed to  multi-byte  characters  in  arguments  and  input
90                 files).
91
92       LC_MESSAGES
93                 Determine the locale that should be used to affect the format
94                 and contents  of  diagnostic  messages  written  to  standard
95                 error.
96
97       NLSPATH   Determine the location of message catalogs for the processing
98                 of LC_MESSAGES.
99

ASYNCHRONOUS EVENTS

101       Default.
102

STDOUT

104       The flowgraph written to standard output shall be formatted as follows:
105
106
107           "%d %s:%s\n", <reference number>, <global>, <definition>
108
109       Each line of output begins with a reference  (that  is,  line)  number,
110       followed  by  indentation  of  at  least one column position per level.
111       This is followed by the name of the global, a <colon>, and its  defini‐
112       tion. Normally globals are only functions not defined as an external or
113       beginning with an <underscore>; see the  OPTIONS  section  for  the  -i
114       inclusion option. For information extracted from C-language source, the
115       definition consists of an abstract type declaration (for example,  char
116       *)  and,  delimited  by angle brackets, the name of the source file and
117       the line number where the definition was found.  Definitions  extracted
118       from  object  files  indicate  the  filename and location counter under
119       which the symbol appeared (for example, text).
120
121       Once a definition of a name has been written, subsequent references  to
122       that name contain only the reference number of the line where the defi‐
123       nition can be found. For undefined references, only "<>" shall be writ‐
124       ten.
125

STDERR

127       The standard error shall be used only for diagnostic messages.
128

OUTPUT FILES

130       None.
131

EXTENDED DESCRIPTION

133       None.
134

EXIT STATUS

136       The following exit values shall be returned:
137
138        0    Successful completion.
139
140       >0    An error occurred.
141

CONSEQUENCES OF ERRORS

143       Default.
144
145       The following sections are informative.
146

APPLICATION USAGE

148       Files produced by lex and yacc cause the reordering of line number dec‐
149       larations, and this can confuse cflow.  To obtain proper  results,  the
150       input of yacc or lex must be directed to cflow.
151

EXAMPLES

153       Given the following in file.c:
154
155
156           int i;
157           int f();
158           int g();
159           int h();
160           int
161           main()
162           {
163               f();
164               g();
165               f();
166           }
167           int
168           f()
169           {
170               i = h();
171           }
172
173       The command:
174
175
176           cflow -i x file.c
177
178       produces the output:
179
180
181           1 main: int(), <file.c 6>
182           2    f: int(), <file.c 13>
183           3        h: <>
184           4        i: int, <file.c 1>
185           5    g: <>
186

RATIONALE

188       None.
189

FUTURE DIRECTIONS

191       None.
192

SEE ALSO

194       c99, lex, yacc
195
196       The  Base  Definitions  volume  of POSIX.1‐2017, Chapter 8, Environment
197       Variables, Section 12.2, Utility Syntax Guidelines
198
200       Portions of this text are reprinted and reproduced in  electronic  form
201       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
202       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
203       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
204       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
205       event of any discrepancy between this version and the original IEEE and
206       The Open Group Standard, the original IEEE and The Open Group  Standard
207       is  the  referee document. The original Standard can be obtained online
208       at http://www.opengroup.org/unix/online.html .
209
210       Any typographical or formatting errors that appear  in  this  page  are
211       most likely to have been introduced during the conversion of the source
212       files to man page format. To report such errors,  see  https://www.ker
213       nel.org/doc/man-pages/reporting_bugs.html .
214
215
216
217IEEE/The Open Group                  2017                            CFLOW(1P)
Impressum