Linux Certif

Toute la documentation sur la certification Linux LPI

coan

NAME

coan - C/C++ configuration analyser

SYNOPSIS

coan COMMAND [OPTION...] [file...] [directory...]

Where no files or directories are specified, input will be read from the standard input. The output of a command is written either to the standard output or to new files, depending upon the command and the options.

DESCRIPTION

Coan is a tool for investigating configurations of C or C++ source code. A configuration is a (possibly empty) list of assumptions about the status of some preprocessor symbols when the source code is compiled. It may be assumed that a symbol is defined for the preprocessor, possibly with a specified value, or it may be assumed that a symbol is undefined. It is important to understand that coan shall consider a symbol to be undefined only if there is an assumption to that effect. If a symbol is not mentioned in any assumption, coan considers its status to be undetermined.

Given a configuration and some source code, coan can answer a range of questions about how the source code would appear to the C/C++ preprocessor if that configuration of preprocessor symbols had been applied in advance.

The most useful of the questions that coan can answer is: What would the source code look like if re-written with all of the simplifications that follow from the given configuration? Coan can produce the simplified re-write that answers this question. So, if the source code contains redundant preprocessor complexities that hinge on the status of some preprocessor symbols, coan can be given a configuration that expresses the settled status of those symbols, and it will output an new version of the source code from which those redundant complexities have been eliminated. Or, if the source code is obscured by preprocessor logic that differentiates several variants by reference to preprocessor symbols, coan can be given a configuration that specifies any of these variants and will be able to generate a simpler version of the source code that represents only the specifed variant.

Source code re-written by coan is not pre-processed code as produced by the C preprocessor. It still contains comments, macro-invocations, and #-directives. It is still source code, but simplified.

Other questions that coan can answer include ones about the preprocessor symbols that appear in the source code and their properties under a given configuration. For example: What symbols would appear within active preprocessor directives under a given configuration, and could thus influence the preprocessor under that configuration? What values would accrue to the symbols that can be evaluated under a given configuration?

Coan can also answer a range of questions about any category of preprocessor directive that might appear in the source code, e.g. What #include directives that import system header files would be active under a given configuration? When coan is invoked to identify the symbols or directives that satisfy certain criteria, it will output a list of the symbols or directives of interest, and optionally their locations in the source code.

COMMANDS

help

Display a usage summary and exit.

version

Display version information and exit.

source [OPTION...] [file...] [directory...]

Read the input files and re-write them in accordance with the options.

symbols [OPTION...] [file...] [directory...]

Select preprocessor symbols from the input files in accordance with the options and report them on the standard output in accordance with the options.

includes [OPTION...] [file...] [directory...]

Select #include directives from the input files in accordance with the options and report them on the standard output in accordance with the options.

defs [OPTION...] [file...] [directory...]

Select #define and #undef directives from the input files in accordance with the options and report them on the standard output in accordance with the options.

pragmas [OPTION...] [file...] [directory...]

Select #pragma directives from the input files in accordance with the options and report them on the standard output in accordance with the options.

errors [OPTION...] [file...] [directory...]

Select #error directives from the input files in accordance with the options and report them on the standard output in accordance with the options.

directives [OPTION...] [file...] [directory...]

Select preprocessor directives from the input files in accordance with the options and report them on the standard output in accordance with the options.

OPTIONS

GENERAL OPTIONS

These options may be given with any command.

fargfile, --file argfile

Read (more) arguments from file argfile. Arguments may be written free-form, separated by whitespace, in argfile. These arguments will be parsed exactly as if they were listed on the commandline at the position of -fargfile.

-Dsymbol[=string], --define symbol[=string]

Assume that the macro definition symbol[=string] is in force for processing the input file(s). If =string is unspecified then string defaults to the empty string.

-Usymbol, --undef symbol

Assume that the macro symbol is undefined for processing the input file(s).

-m, --implicit

Assume that any symbol that is not --define-ed is implicitly --undef-ed.

-R, --recurse

Recurse into directories to find input files. (With the source command, --recurse implies --replace). With --recurse, the input files may include directories: otherwise a directory provokes a non-fatal error.

All files beneath a directory will be selected for input unless the --filter option is given: otherwise all files will be selected that match the --filter option.

When --recurse is in effect, coan builds a graph of all unique input files once and for all as it parses the filenames that are explicitly supplied and before it processes any of them. New files that may later appear in input directories during execution will not be processed, and files that have disappeared from input directories when they are due to be processed will provoke fatal errors.

-Fext1[,ext2...], --filter ext1[,ext2...]

Process only input files that have one of the file extensions ext1,ext2... A file extension may be any terminal segment of a filename that immediately follows a '.'.

-g[p|i|w|e|a], --gag [progress | info | warning | error | abend]

Suppress diagnostics no worse than [progress | info | warning | error | abend].

-gs, --gag summary.

Suppress summary diagnostics at end of input.

-V, --verbose

Output all diagnostics,

If neither -V nor -garg is specified defaults are -gp -gi -gs.

-E, --evalconsts

Constants occurring as truth-functional operands in #if expressions shall be evaluated and eliminated. By default constants as truth-functional operands are treated as unknowns, i.e. like macros that are not subject to any assumptions. Constants are always evaluated and eliminated when they are arithmetic or bitwise operands.

The default behaviour preserves ``work-in-progress'' directives such as #if 1 and #if 0 along with the code they control. With --evalconsts these directives are evaluated.

-d, --debug

Write debugging information to stderr.

-K, --keepgoing

If a parse error is encountered in an input file, continue processing subsequent input files. An event of severity abend will terminate processing regardless of --keepgoing.

-P, --pod

Apart from #-directives, input is to be treated as Plain Old Data. C or C++ comments and quotations will not be parsed.

OPTIONS FOR THE source COMMAND

-r, --replace

Replace each input file with the corresponding output file. This option must be specified to process multiple input files.

The option changes the default behaviour of the command when no input files are specified. In that case, input is acquired from the standard input. If --replace is not specified, then a single input file is read from the standard input. If --replace is specified then the names of the input files are read from the standard input. Note that the --recurse option implies --replace.

If the names of the input files are read from stdin, the filenames are delimited by whitespace unless enclosed in double-quotes.

-Bsuffix, --backup suffix

Backup each input file before replacing it, the backup file having the same name as the input file with suffix appended to it.

-x[d|c|e], --conflict [delete | comment | error]

Select the action to be taken when a #define or #undef directive is encountered in an input file that conflicts with one of the -D or -U assumptions:

d, delete: Delete the conflicting directive.

c, comment: Replace the conflicting directive with a diagnostic comment (default).

e, error: Replace the conflicting directive with a diagnostic #error directive.

-k[d|b|c], --discard [drop | blank | comment]

Select the policy for discarding lines from output:

d, drop: Drop discarded lines.

b, blank: Blank discarded lines.

c, comment: Comment out discarded lines.

--line

Output #line directives in place of discarded lines to preserve the line numbers of retained lines.

-c, --complement

Ouput the lines that ought to be dropped and vice versa.

OPTIONS FOR THE symbols COMMAND

-i, --ifs

List symbols that occur in #if, #if[n]def and #elif directives.

-d, --defs

List symbols that occur in #define directives.

-u, --undefs

List symbols that occur in #undef directives.

--includes

List symbols that occur in #include directives.

If none of -i, -d or -u is given then they are all defaults.

-o, --once

List only the first occurrence of each symbol. Default: List all occurrences.

-A, --active

List only symbols from operative directives.

-I, --inactive

List only symbols from inoperative directives.

-L, --locate

Report the source file and line number of each listed occurrence.

-e, --evalsyms

Report the most resolved form of each symbol. A most-resolved form will be reported for the symbol symbol if symbol is configured by a -Dsymbol[=string] option or a -Usymbol option.

In the case -Dsymbol, the most-resolved form of symbol is the empty string (since that is the C preprocessor's default definition for defined symbols).

In the case -Usymbol, the most-resolved form of symbol is the numeral 0 (since 0 is the value assigned by the preprocessor to an undefined symbol).

In the case -Dsymbol=string, if string is an expression that is free of configured symbols and can be resolved to an integer value N then the most-resolved form is the numeral denoting N. Otherwise the most-resolved form results from string by replacing each occurrence of a configured symbol in string with the most-resolved form of that symbol and each maximally large expression with the most resolved form of that expression.

If a symbol is not configured by any -Dsymbol[=string] option or any -Usymbol then it is reported as undefined.

OPTIONS FOR THE includes COMMAND

-s, --system

List system headers, e.g. <header.h>

-L, --local

List local headers, e.g. ``header.h''

If neither -s or -L is given then both are defaults.

-o, --once

List only the first occurrence of each header. Default: List all occurrences.

-A, --active

List only headers from operative directives.

-I, --inactive

List only headers from inoperative directives.

-L, --locate

Report the source file and line number of each listed occurrence

OPTIONS FOR THE defs COMMAND

-o, --once

List only the first occurrence of each distinct #define or #undef directive. Default: List all occurrences.

For the purpose of determining whether two occurrences express the same directive or not, coan reduces the text of each occurrence to a canonical form, i.e. all comments are stripped out, all whitespace sequences are collapsed to a single space and all tokens are separated by a single space. This applies for all commands that accept the --once option.

-A, --active

List only operative #define and #undef directives.

-I, --inactive

List only inoperative #define and #undef directives.

-L, --locate

Report the source file and line number of each listed occurrence.

OPTIONS FOR THE pragmas COMMAND

-o, --once

List only the first occurrence of each distinct pragma. Default: List all occurrences.

-A, --active

List only operative pragmas.

-I, --inactive

List only inoperative pragmas.

-L, --locate

Report the source file and line number of each listed occurrence.

OPTIONS FOR THE errors COMMAND

-o, --once

List only the first occurrence of each #error directive. Default: List all occurrences.

-A, --active

List only operative #error directives.

-I, --inactive

List only inoperative #error directives.

-L, --locate

Report the source file and line number of each listed occurrence.

OPTIONS FOR THE directives COMMAND

-o, --once

List only the first occurrence of each distinct directive. Default: List all occurrences.

-A, --active

List only operative directives.

-I, --inactive

List only inoperative directives.

-L, --locate

Report the source file and line number of each listed occurrence.

DIAGNOSTICS

Diagnostics written to stderr are classified by severity. Each diagnostic includes a distinct hexadecimal code of the form 0xXXXXX that encodes its severity. The 5 severities are:

progress: Progress messages (0xXXXXX & 0x00800 is true)
info: Noteworthy information (0xXXXXX & 0x01000 is true)
warning: Indicating problematic input (0xXXXXX & 0x02000 is true)
error: Indicating invalid input (0xXXXXX & 0x04000 is true)
abend: Indicating a fatal environment or internal error (0xXXXXX & 0x08000 is true)

If --gag summary is not in force, coan can write summary diagnostics at the end of processing. A summary diagnostic has a hexadecimal code S that encodes one of the severities and in addition S & 0x10000 is true. Even if --gag summary is not in force, a summary will not be written if its severity is suppressed by one of the specified or default --gag options. Since all summaries have severity info or warning, and since the --gag defaults are info, warning and summary, you should specify --gag info to see only warning summaries, and to see all summaries you should specify --verbose. The summaries include:

info: The number of input files that were reached and the number that were not reached (due to abend).
info: The number of input files reached that were abandoned (due to errors).

If there was no abend or error, then additional summaries are written (unless suppressed) indicating each of the following outcomes that has occurred:

info: Input lines were dropped through simplification.
info: Input lines were changed through simplification.
warning: Input lines were changed to #error directives.
warning: #error directives were operative (either in the input source or as a result of simplification).

Coan returns a system code SC of which the low order half of the low order byte is always meaningful:

SC & 1: Informational diagnostics accrued.
SC & 2: Warnings diagnostics accrued.
SC & 4: Error diagnostics accrued. (Input files provoking errors will be unchanged notwithstanding the --replace option.)
SC & 8: An abend occurred. Some input files may not have been reached.

If no error or abend is indicated, then the high order half of the low order byte is also meaningful:

SC & 16: Input lines were dropped through simplification.
SC & 32: Input lines were changed through simplification.
SC & 64: Input lines were changed to #error directives.
SC & 128: #error directives were operative.

The system code reflects diagnostics that were provoked even if they were not actually output due to --gag options.

BUGS

The conditional operator ?...:... is not parsed.

Trigraphs are not parsed.

#define and #undef directives that are found to be active are not factored into the evalation of subsequent #if directives.

Please report bugs to bugs dot coan at strudl dot org

AUTHOR

Mike Kinghan imk at strudl dot org