NAME

cflow - generate a C-language flowgraph (DEVELOPMENT)

 SYNOPSIS

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

 DESCRIPTION

The cflow utility analyses a collection of object files or assembler, C-language, lex or yacc source files, and attempts to build a graph, written to standard output, charting the external references.

 OPTIONS

The cflow utility supports the XBD specification, Utility Syntax Guidelines  , except that the order of the -D, -I and -U options (which are identical to their interpretation by c89) is significant. The following options are supported:

-d num

Indicate the depth at which the flowgraph is cut off. The argument num is a decimal integer. By default this is a very large number (typically greater than 32000). Attempts to set the cut-off depth to a non-positive integer will be ignored.

-i incl

Increase the number of included symbols. The incl option-argument is one of the following characters:

x

Include external and static data symbols. The default is to include only functions in the flowgraph.

_

(Underscore) Include names that begin with an underscore. The default is to exclude these functions (and data if -ix is used).

-r

Reverse the caller:callee relationship, producing an inverted listing showing the callers of each function. The listing is also sorted in lexicographical order by callee.

 OPERANDS

The following operand is supported:

file

The pathname of a file for which a graph is to be generated. Files suffixed in .l, .y, .c and .i are processed by lex and yacc and preprocessed by the c89 preprocessor phase (bypassed for .i files) as appropriate, and then run through the first pass of lint. Files suffixed with .s are assembled and information is extracted (as in .o files) from the symbol table.

 STDIN

Not used.

 INPUT FILES

The input files are object files or assembler, C-language, lex or yacc source files.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of cflow:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_COLLATE

Determine the locale for the ordering of the output when the -r option is used.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files).

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

The flowgraph written to standard output is formatted as follows:

"%d %s:%s\n", <reference number>, <global>, <definition>

Each line of output begins with a reference (that is, line) number, followed by a suitable amount of indentation indicating the level. This is followed by the name of the global, a colon and its definition. Normally globals are only functions not defined as an external or beginning with an underscore; see the OPTIONS section for the -i inclusion option. For information extracted from C-language source, the definition consists of an abstract type declaration (for example, char *) and, delimited by angle brackets, the name of the source file and the line number where the definition was found. Definitions extracted from object files indicate the filename and location counter under which the symbol appeared (for example, text).

Once a definition of a name has been written, subsequent references to that name contain only the reference number of the line where the definition can be found. For undefined references, only <> is written.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

Files produced by lex and yacc cause the reordering of line number declarations, and this can confuse cflow. To obtain proper results, the input of yacc or lex must be directed to cflow.

 EXAMPLES

Given the following in file.c:

int i;

main()
{
    f();
    g();
    f();
}

f()
{
    i = h();
}

The command:

cflow -i x file.c

produces the output:

1 main: int(), <file.c 4>
2     f: int(), <file.c 11>
3         h: <>
4         i: int, <file.c 1>
5     g: <>

 FUTURE DIRECTIONS

None.

 SEE ALSO

cc, c89, lex, yacc.