# cflow

## PROLOG



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


## 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 shall analyze a collection of object files or
           assembler, C-language, _lex_ , or _yacc_ source files, and attempt to
           build a graph, written to standard output, charting the external
           references.
    


## OPTIONS



           The _cflow_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_ , except that
           the order of the **-D** , **-I** , and **-U** options (which are identical to
           their interpretation by _c99_) is significant.
    
           The following options shall be supported:
    
           **-d** _num_    Indicate the depth at which the flowgraph is cut off.
                     The application shall ensure that 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 shall 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 shall be to include only functions in the
                           flowgraph.
    
                     _     (Underscore) Include names that begin with an
                           <underscore>.  The default shall be to exclude
                           these functions (and data if **-i x** is used).
    
           **-r** Reverse the caller:callee relationship, producing an
                     inverted listing showing the callers of each function.
                     The listing shall also be 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.  Filenames suffixed by **.l** shall shall be
                     taken to be _lex_ input, **.y** as _yacc_ input, **.c** as _c99_
                     input, and **.i** as the output of _c99_ **-E**.  Such files shall
                     be processed as appropriate, determined by their suffix.
    
                     Files suffixed by **.s**(conventionally assembler source)
                     may have more limited information extracted from them.
    


## STDIN



           Not used.
    


## INPUT FILES



           The input files shall be object files or assembler, C-language,
           _lex_ , or _yacc_ source files.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _cflow_ :
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization 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-byte 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 catalogs for the
                     processing of _LC_MESSAGES_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           The flowgraph written to standard output shall be 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 indentation of at least one column position
           per 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 **" <>" **shall be written.
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    Successful completion.
    
           >0    An error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## 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;
               int f();
               int g();
               int h();
               int
               main()
               {
                   f();
                   g();
                   f();
               }
               int
               f()
               {
                   i = h();
               }
    
           The command:
    
               cflow -i x file.c
    
           produces the output:
    
               1 main: int(), <file.c 6>
               2    f: int(), <file.c 13>
               3        h: <>
               4        i: int, <file.c 1>
               5    g: <>
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *