1coan(1) User Commmands coan(1)
2
6 coan - C/C++ configuration analyser
7
9 coan COMMAND [OPTION...] [file...] [directory...]
10 Where no files or directories are specified, input will be read from
12 the standard input. The output of a command is written either to the
13 standard output or to new files, depending upon the command and the
14 options.
15
17 Coan is a tool for investigating configurations of C or C++ source
18 code. A configuration is a (possibly empty) list of assumptions about
19 the status of some preprocessor symbols when the source code is
20 compiled. It may be assumed that a symbol is defined for the
21 preprocessor, possibly with a specified value, or it may be assumed
22 that a symbol is undefined. It is important to understand that coan
23 shall consider a symbol to be undefined only if there is an assumption
24 to that effect. If a symbol is not mentioned in any assumption, coan
25 considers its status to be undetermined.
26 Given a configuration and some source code, coan can answer a range of
28 questions about how the source code would appear to the C/C++
29 preprocessor if that configuration of preprocessor symbols had been
30 applied in advance.
31 The most useful of the questions that coan can answer is: What would
33 the source code look like if re-written with all of the simplifications
34 that follow from the given configuration? Coan can produce the
35 simplified re-write that answers this question. So, if the source code
36 contains redundant preprocessor complexities that hinge on the status
37 of some preprocessor symbols, coan can be given a configuration that
38 expresses the settled status of those symbols, and it will output an
39 new version of the source code from which those redundant complexities
40 have been eliminated. Or, if the source code is obscured by
41 preprocessor logic that differentiates several variants by reference to
42 preprocessor symbols, coan can be given a configuration that specifies
43 any of these variants and will be able to generate a simpler version of
44 the source code that represents only the specifed variant.
45 Source code re-written by coan is not pre-processed code as produced by
47 the C preprocessor. It still contains comments, macro-invocations, and
48 #-directives. It is still source code, but simplified.
49 Other questions that coan can answer include ones about the
51 preprocessor symbols that appear in the source code and their
52 properties under a given configuration. For example: What symbols would
53 appear within active preprocessor directives under a given
54 configuration, and could thus influence the preprocessor under that
55 configuration? What values would accrue to the symbols that can be
56 evaluated under a given configuration?
57 Coan can also answer a range of questions about any category of
59 preprocessor directive that might appear in the source code, e.g. What
60 #include directives that import system header files would be active
61 under a given configuration? When coan is invoked to identify the
62 symbols or directives that satisfy certain criteria, it will output a
63 list of the symbols or directives of interest, and optionally their
64 locations in the source code.
65
67 help
68 Display a usage summary and exit.
69 version
71 Display version information and exit.
72 source [OPTION...] [file...] [directory...]
74 Read the input files and re-write them in accordance with the
75 options.
76 symbols [OPTION...] [file...] [directory...]
78 Select preprocessor symbols from the input files in accordance with
79 the options and report them on the standard output in accordance
80 with the options.
81 includes [OPTION...] [file...] [directory...]
83 Select #include directives from the input files in accordance with
84 the options and report them on the standard output in accordance
85 with the options.
86 defs [OPTION...] [file...] [directory...]
88 Select #define and #undef directives from the input files in
89 accordance with the options and report them on the standard output
90 in accordance with the options.
91 pragmas [OPTION...] [file...] [directory...]
93 Select #pragma directives from the input files in accordance with
94 the options and report them on the standard output in accordance
95 with the options.
96 errors [OPTION...] [file...] [directory...]
98 Select #error directives from the input files in accordance with
99 the options and report them on the standard output in accordance
100 with the options.
101 directives [OPTION...] [file...] [directory...]
103 Select preprocessor directives from the input files in accordance
104 with the options and report them on the standard output in
105 accordance with the options.
106
108 GENERAL OPTIONS
109 These options may be given with any command.
110 fargfile, --file argfile
112 Read (more) arguments from file argfile. Arguments may be written
113 free-form, separated by whitespace, in argfile. These arguments
114 will be parsed exactly as if they were listed on the commandline at
115 the position of -fargfile.
116 -Dsymbol[=string], --define symbol[=string]
118 Assume that the macro definition symbol[=string] is in force for
119 processing the input file(s). If =string is unspecified then string
120 defaults to the empty string.
121 -Usymbol, --undef symbol
123 Assume that the macro symbol is undefined for processing the input
124 file(s).
125 -m, --implicit
127 Assume that any symbol that is not --define-ed is implicitly
128 --undef-ed.
129 -R, --recurse
131 Recurse into directories to find input files. (With the source
132 command, --recurse implies --replace). With --recurse, the input
133 files may include directories: otherwise a directory provokes a
134 non-fatal error.
135 All files beneath a directory will be selected for input unless the
137 --filter option is given: otherwise all files will be selected that
138 match the --filter option.
139 When --recurse is in effect, coan builds a graph of all unique
141 input files once and for all as it parses the filenames that are
142 explicitly supplied and before it processes any of them. New files
143 that may later appear in input directories during execution will
144 not be processed, and files that have disappeared from input
145 directories when they are due to be processed will provoke fatal
146 errors.
147 -Fext1[,ext2...], --filter ext1[,ext2...]
149 Process only input files that have one of the file extensions
150 ext1,ext2... A file extension may be any terminal segment of a
151 filename that immediately follows a '.'.
152 -g[p|i|w|e|a], --gag [progress | info | warning | error | abend]
154 Suppress diagnostics no worse than [progress | info | warning |
155 error | abend].
156 -gs, --gag summary.
158 Suppress summary diagnostics at end of input.
159 -V, --verbose
161 Output all diagnostics,
162 If neither -V nor -garg is specified defaults are -gp -gi -gs.
164 -E, --evalconsts
166 Constants occurring as truth-functional operands in #if expressions
167 shall be evaluated and eliminated. By default constants as truth-
168 functional operands are treated as unknowns, i.e. like macros that
169 are not subject to any assumptions. Constants are always evaluated
170 and eliminated when they are arithmetic or bitwise operands.
171 The default behaviour preserves "work-in-progress" directives such
173 as #if 1 and #if 0 along with the code they control. With
174 --evalconsts these directives are evaluated.
175 -d, --debug
177 Write debugging information to stderr.
178 -K, --keepgoing
180 If a parse error is encountered in an input file, continue
181 processing subsequent input files. An event of severity abend will
182 terminate processing regardless of --keepgoing.
183 -P, --pod
185 Apart from #-directives, input is to be treated as Plain Old Data.
186 C or C++ comments and quotations will not be parsed.
187 OPTIONS FOR THE source COMMAND
189 -r, --replace
190 Replace each input file with the corresponding output file. This
191 option must be specified to process multiple input files.
192 The option changes the default behaviour of the command when no
194 input files are specified. In that case, input is acquired from the
195 standard input. If --replace is not specified, then a single input
196 file is read from the standard input. If --replace is specified
197 then the names of the input files are read from the standard input.
198 Note that the --recurse option implies --replace.
199 If the names of the input files are read from stdin, the filenames
201 are delimited by whitespace unless enclosed in double-quotes.
202 -Bsuffix, --backup suffix
204 Backup each input file before replacing it, the backup file having
205 the same name as the input file with suffix appended to it.
206 -x[d|c|e], --conflict [delete | comment | error]
208 Select the action to be taken when a #define or #undef directive is
209 encountered in an input file that conflicts with one of the -D or
210 -U assumptions:
211 d, delete: Delete the conflicting directive.
213 c, comment: Replace the conflicting directive with a diagnostic
215 comment (default).
216 e, error: Replace the conflicting directive with a diagnostic
218 #error directive.
219 -k[d|b|c], --discard [drop | blank | comment]
221 Select the policy for discarding lines from output:
222 d, drop: Drop discarded lines.
224 b, blank: Blank discarded lines.
226 c, comment: Comment out discarded lines.
228 --line
230 Output #line directives in place of discarded lines to preserve the
231 line numbers of retained lines.
232 -c, --complement
234 Ouput the lines that ought to be dropped and vice versa.
235 OPTIONS FOR THE symbols COMMAND
237 -i, --ifs
238 List symbols that occur in #if, #if[n]def and #elif directives.
239 -d, --defs
241 List symbols that occur in #define directives.
242 -u, --undefs
244 List symbols that occur in #undef directives.
245 --includes
247 List symbols that occur in #include directives.
248 If none of -i, -d or -u is given then they are all defaults.
250 -o, --once
252 List only the first occurrence of each symbol. Default: List all
253 occurrences.
254 -A, --active
256 List only symbols from operative directives.
257 -I, --inactive
259 List only symbols from inoperative directives.
260 -L, --locate
262 Report the source file and line number of each listed occurrence.
263 -e, --evalsyms
265 Report the most resolved form of each symbol. A most-resolved form
266 will be reported for the symbol symbol if symbol is configured by a
267 -Dsymbol[=string] option or a -Usymbol option.
268 In the case -Dsymbol, the most-resolved form of symbol is the empty
270 string (since that is the C preprocessor's default definition for
271 defined symbols).
272 In the case -Usymbol, the most-resolved form of symbol is the
274 numeral 0 (since 0 is the value assigned by the preprocessor to an
275 undefined symbol).
276 In the case -Dsymbol=string, if string is an expression that is
278 free of configured symbols and can be resolved to an integer value
279 N then the most-resolved form is the numeral denoting N. Otherwise
280 the most-resolved form results from string by replacing each
281 occurrence of a configured symbol in string with the most-resolved
282 form of that symbol and each maximally large expression with the
283 most resolved form of that expression.
284 If a symbol is not configured by any -Dsymbol[=string] option or
286 any -Usymbol then it is reported as undefined.
287 OPTIONS FOR THE includes COMMAND
289 -s, --system
290 List system headers, e.g. <header.h>
291 -L, --local
293 List local headers, e.g. "header.h"
294 If neither -s or -L is given then both are defaults.
296 -o, --once
298 List only the first occurrence of each header. Default: List all
299 occurrences.
300 -A, --active
302 List only headers from operative directives.
303 -I, --inactive
305 List only headers from inoperative directives.
306 -L, --locate
308 Report the source file and line number of each listed occurrence
309 OPTIONS FOR THE defs COMMAND
311 -o, --once
312 List only the first occurrence of each distinct #define or #undef
313 directive. Default: List all occurrences.
314 For the purpose of determining whether two occurrences express the
316 same directive or not, coan reduces the text of each occurrence to
317 a canonical form, i.e. all comments are stripped out, all
318 whitespace sequences are collapsed to a single space and all tokens
319 are separated by a single space. This applies for all commands that
320 accept the --once option.
321 -A, --active
323 List only operative #define and #undef directives.
324 -I, --inactive
326 List only inoperative #define and #undef directives.
327 -L, --locate
329 Report the source file and line number of each listed occurrence.
330 OPTIONS FOR THE pragmas COMMAND
332 -o, --once
333 List only the first occurrence of each distinct pragma. Default:
334 List all occurrences.
335 -A, --active
337 List only operative pragmas.
338 -I, --inactive
340 List only inoperative pragmas.
341 -L, --locate
343 Report the source file and line number of each listed occurrence.
344 OPTIONS FOR THE errors COMMAND
346 -o, --once
347 List only the first occurrence of each #error directive. Default:
348 List all occurrences.
349 -A, --active
351 List only operative #error directives.
352 -I, --inactive
354 List only inoperative #error directives.
355 -L, --locate
357 Report the source file and line number of each listed occurrence.
358 OPTIONS FOR THE directives COMMAND
360 -o, --once
361 List only the first occurrence of each distinct directive. Default:
362 List all occurrences.
363 -A, --active
365 List only operative directives.
366 -I, --inactive
368 List only inoperative directives.
369 -L, --locate
371 Report the source file and line number of each listed occurrence.
372
374 Diagnostics written to stderr are classified by severity. Each
375 diagnostic includes a distinct hexadecimal code of the form 0xXXXXX
376 that encodes its severity. The 5 severities are:
377 progress: Progress messages (0xXXXXX & 0x00800 is true)
379 info: Noteworthy information (0xXXXXX & 0x01000 is true)
381 warning: Indicating problematic input (0xXXXXX & 0x02000 is true)
383 error: Indicating invalid input (0xXXXXX & 0x04000 is true)
385 abend: Indicating a fatal environment or internal error (0xXXXXX &
387 0x08000 is true)
388 If --gag summary is not in force, coan can write summary diagnostics at
390 the end of processing. A summary diagnostic has a hexadecimal code S
391 that encodes one of the severities and in addition S & 0x10000 is true.
392 Even if --gag summary is not in force, a summary will not be written if
393 its severity is suppressed by one of the specified or default --gag
394 options. Since all summaries have severity info or warning, and since
395 the --gag defaults are info, warning and summary, you should specify
396 --gag info to see only warning summaries, and to see all summaries you
397 should specify --verbose. The summaries include:
398 info: The number of input files that were reached and the number
400 that were not reached (due to abend).
401 info: The number of input files reached that were abandoned (due to
403 errors).
404 If there was no abend or error, then additional summaries are written
406 (unless suppressed) indicating each of the following outcomes that has
407 occurred:
408 info: Input lines were dropped through simplification.
410 info: Input lines were changed through simplification.
412 warning: Input lines were changed to #error directives.
414 warning: #error directives were operative (either in the input
416 source or as a result of simplification).
417 Coan returns a system code SC of which the low order half of the low
419 order byte is always meaningful:
420 SC & 1: Informational diagnostics accrued.
422 SC & 2: Warnings diagnostics accrued.
424 SC & 4: Error diagnostics accrued. (Input files provoking errors
426 will be unchanged notwithstanding the --replace option.)
427 SC & 8: An abend occurred. Some input files may not have been
429 reached.
430 If no error or abend is indicated, then the high order half of the low
432 order byte is also meaningful:
433 SC & 16: Input lines were dropped through simplification.
435 SC & 32: Input lines were changed through simplification.
437 SC & 64: Input lines were changed to #error directives.
439 SC & 128: #error directives were operative.
441 The system code reflects diagnostics that were provoked even if they
443 were not actually output due to --gag options.
444
446 The conditional operator ?...:... is not parsed.
447 Trigraphs are not parsed.
449 #define and #undef directives that are found to be active are not
451 factored into the evalation of subsequent #if directives.
452 Please report bugs to bugs dot coan at strudl dot org
454
456 Mike Kinghan imk at strudl dot org
457NOVEMBER 2007 strudl.org coan(1)