home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 364_01 / readme.ca < prev    next >
Text File  |  1992-05-26  |  53KB  |  1,244 lines
  1.  
  2. C-ACROSS (version 1.02):  README.CA                Page 1
  3.  
  4. /*
  5. HEADER:         ;
  6. TITLE:          C-ACROSS;
  7. VERSION         1.02
  8.  
  9. DESCRIPTION:   "Utility for multiple module programs. Produces
  10.       Six indexes of functions, prototypes, and globals that
  11.       enable user to 'see across' modules for use in checking
  12.       and comparison.  One of these is type of hierarchical
  13.       functions list, a listing by module of functions
  14.       and calls made FROM them; another is alphabetical list
  15.       of functions and calls made TO them. Globals listed
  16.       in schematic descriptors which record all modifiers
  17.       and qualifiers and enable checking of declarators
  18.       across modules. Creates, on request, header file
  19.       consisting of prototypes constructed from function
  20.       definitions. Can list user defined types and some
  21.       preprocessor #defines. Full documentation in README.CA";
  22.  
  23. KEYWORDS:       Utility, Cross Reference, Deubgging;
  24. SYSTEM:         MS-DOS;
  25. FILENAME:       FUNC_CA.C;
  26.  
  27. WARNINGS:      "1. Assumes function definitions conform with
  28.         ANSI standards and have prototype form. See
  29.         also "Caveats and Restrictions" in README.CA.
  30.         2. Assumes syntactically correct source files.
  31.         3. Written and tested using Microsoft QuickC.
  32.         4. Copyright retained.  See Copyright
  33.         information in README.CA.";
  34.  
  35. SEE-ALSO:      EXITS_CA, FUNC_CA.C, GLOB_CA.C, IFDEF_CA.C, INTF_CA.C,
  36.            LINKL_CA.C, PARSE_CA.C, TDEF_CA.C, TYPES_CA.C, UTIL_CA.C,
  37.            UTLG_CA.C, XRF_CA.C, README.CA,
  38.            CA.H, CA.PRJ, CA.RPT, CDECL_CA.H, KEYWORDS.H;
  39. AUTHORS:       Myron Turner;
  40. COMPILERS:     Microsoft C;
  41.  
  42. */
  43.  
  44.  
  45. /***************************  C-ACROSS  ***************************/
  46.                    v. 1.02
  47.                Copyright (C) Myron Turner
  48.  
  49.               333 Bartlet Ave.
  50.               Winnipeg, Manitoba
  51.               Canada R3L 0Z9
  52.               (204) 284-8387
  53.  
  54. /*********************************************************************/
  55.  
  56.  
  57.  
  58.  
  59.  
  60. C-ACROSS (version 1.02):  README.CA                Page 2
  61.  
  62.  
  63. /*********************************************************************/
  64.  
  65.    Version 1.02 of C-ACROSS does essentially the same things as Ver 1.0.
  66.    The major exception to this statement is that it now treats function
  67.    pointers as described in II.V. and V.1.f.
  68.    It has, however, undergone many silent changes and improvements,
  69.    among them, it has:
  70.    1. Expanded treatment of typedfes;
  71.    2. Improved algorithm for treating complex declarators;
  72.    3. Improved algorithm for checking truth values of preprocessor
  73.       conditions (#if/defs);
  74.    4. Added processing of preprocessor conditionals to the parsing
  75.    of function definitions and prototypes, the absence of which in
  76.    version 1.0 was a weakness;
  77.    5. Corrected logical flaw in GLOB_CA, which by both good and
  78.    bad fortune kept things working while it concealed a number of
  79.    places where there was room for improvement;
  80.    6. Added several new switches (and deleted one);
  81.    7. Fixed small glitch which prevented the recording of certain
  82.    initialized structure/union variables.
  83.  
  84.    All in all this is a more accurate and more robust version, offering
  85.    more options.
  86.  
  87.  
  88. C-ACROSS (version 1.02):  README.CA                Page 3
  89.  
  90.  
  91.         INDEX TO HEADINGS
  92.  
  93. PAGE             HEADING
  94.  
  95.  5    I.INTRODUCTION
  96.  6    II. TYPES OF LISTS PRODUCED
  97.  6      II.1.  "I. FUNCTION DECLARATIONS AND GLOBAL VARIABLES"
  98.  7      II.2.  "II.  ALPHABETICAL INDEX OF FUNCTIONS & THEIR MODULES"
  99.  7      II.3.  "III. FUNCTIONS (LISTED BY MODULE) AND CALLS"
  100.  7      II.4.  "IV.  LIST OF FUNCTIONS AND CALLING FUNCTIONS"
  101.  7      II.5.  "V.   LISTINGS OF FUNCTION POINTERS"
  102.  7      II.6.  "VI.   GLOBAL VARIABLES LISTED ALPHABETICALLY"
  103.  7    III. INSTRUCTIONS
  104.  7      III.1. DOS INCLUDE VARIABLE
  105.  8      III.2. PATH OF C FILES
  106.  8      III.3. COMMAND LINE
  107.  10     III.4. Using a PROJECT-FILE
  108.  10     III.5. EXAMPLE COMMAND LINES
  109.  11   IV.  CAVEATS AND RESTRICTIONS
  110.  11    IV.1. PREPROCESSOR
  111.  11      IV.1.a.  Conditionals (#if. . .#ifdef..)
  112.  12     IV.1.b.  User defined types using #define.
  113.  12       IV.1.c. Using #define as compared to typedef.
  114.  12    IV.2.  FORMATTING
  115.  13    IV.3.  REPORT FILE PATHS
  116.  13    IV.4.  COMMENTS
  117.  14   IV.5. FUNCTION DEFINITIONS:  MULTIPLE LINES
  118.  14   V.  READING C-ACROSS REPORTS
  119.  14    V.1. Reading the Main Report File.
  120.  14      V.1.a.  Functions and Globals by Module.
  121.  15      V.1.b. Alphabetical listing of functions and their modules.
  122.  15      V.1.c. A listing of functions by module, in the order in whic
  123.  15      V.1.d. Alphabetical listing of functions and the functions wh
  124.  16      V.1.e. Alphabetical listing of globals, showing type, storage
  125.  20      V.1.f  The Listing and Treatment of Function Pointers.
  126.  22    V.2.  The SCRNOUT Report.
  127.  22   VI.   ERRORS
  128.  22   VII.  FILES INCLUDED ON C-ACROSS DISKS
  129.  23   VIII. COPYRIGHT
  130.  
  131.  
  132.  
  133. C-ACROSS (version 1.02):  README.CA                Page 4
  134.  
  135.  
  136.  
  137.  
  138. I.INTRODUCTION
  139.  
  140.   1. C-ACROSS is a utility for multiple module programs.  It states
  141. relationships between functions and produces annotated listings of
  142. global variables.  Its purpose is not to produce a hierarchical list
  143. of functions (although it in part does that) but to enable the programmer
  144. to see across modules in order to cross-check functions and variables.
  145. C-ACROSS reads source files and (at the user's discretion) include files.
  146. Therefore, it does not treat library functions, either standard C library
  147. functions or functions drawn from a library of the user's own. Nor, for
  148. the same reason, does it read other symbols, i.e., variables,
  149. embedded in object files.
  150.    1.a.  The term Global is used in this document to refer to all
  151.    variables which are characterized by file scope and external storage,
  152.    i.e. variables declared outside of functions and which are exported
  153.    to the linker.  This distinguishes them from static variables which
  154.    have file scope but are known only to the files in which they are
  155.    defined.  C-ACROSS does, however, list all static variables as
  156.    well as globals, even when they appear within functions.
  157.    1.b.  C-ACROSS assumes that function declarations follow the ANSI
  158.    format:
  159.         int function_1(int i, char *p)
  160.         {
  161.    It may not read the old form reliably:
  162.         int function (i, p)
  163.              int i;
  164.              char *p;
  165.          {
  166.    The reason for this is that it does not expect to find declarations
  167.    between the closed parenthesis and the opening bracket to the function.
  168.    While C-ACROSS will probably read the function names correctly,
  169.    it will treat all or some of the formal parameters as globals.
  170.    The old form will, additionally, not allow for a correct /CDECLARE
  171.    file (See III.3.b.5).
  172.  
  173.   2. Some of the kinds of problems which C-ACROSS will help resolve.
  174.     2.a. In the case of global variables the following declarations
  175.   will be accepted by the compiler and processed by the linker:
  176.  
  177.     FILE_1.C
  178.     int testvariable;
  179.     int *_far testfarintp;
  180.     int i;
  181.  
  182.     FILE_2.C
  183.     extern double testvariable;
  184.     extern int *_near testfarintp;
  185.     int i;
  186.  
  187.   "The C compiler," as Harbison and Steele point out, "cannot verify 
  188.   that declarations in different files are consistent. . . .The lint
  189.   program, usually supplied. . .in UNIX systems, can check multiple 
  190.  
  191. C-ACROSS (version 1.02):  README.CA                Page 5
  192.  
  193.   files for inconsistent declarations." (p. 94)  C-ACROSS should 
  194.   help programmers without access to a lint program check declarations
  195.   for consistency:  C-ACROSS produces fully analytical descriptions of 
  196.   both simple and complex variable declarations, listing them in table
  197.   form for ease of comparison.  (See V.1.e. for further information.)
  198.  
  199.     2.b. To facilitate function checking, C-ACROSS will produce a listing of
  200.   prototypes constructed from the actual function declarations themselves
  201.   which can then be used as a universal header file to check function calls
  202.   against the actual declaration statements.  This is good protection
  203.   against certain illegal pointer errors that are otherwise difficult
  204.   to locate.
  205.  
  206.     2.c. C-ACROSS shows at a glance which functions call every
  207.   user-defined function and marks as UNUSED any unused functions.
  208.   It was for this particular listing that C-ACROSS was initially
  209.   undertaken:  to make it simple to determine whether a function
  210.   was being used and where it was being used.
  211.  
  212.     2.d.  See section II for a fuller account of the kinds of lists
  213.   C-ACROSS makes; and for further information on the use of the
  214.   C-ACROSS listings, see section V.
  215.  
  216.   3. The report produced by C-ACROSS can run into a considerable number of
  217.   pages:  it takes something like 40 pages to report on C-ACROSS itself,
  218.   if its switches are set to analyze all include files ( i.e. both C header
  219.   files and user created .h files).  It greatest usefulness, therefore, is
  220.   in some form of word-processing environment which can be easily searched.
  221.   It can very handily be used while programming, for instance with the
  222.   QuickC editor.
  223.  
  224.   The report file produced by C-ACROSS has the extension .rpt and the
  225.   filename of the first file processed, unless otherwise specified at
  226.   the prompt.
  227.  
  228.  
  229. II. TYPES OF LISTS PRODUCED
  230. (See "V. READING C-ACROSS REPORTS" for detailed examples.)
  231.  
  232. C-ACROSS makes the following lists under the headings in quotation
  233. marks:
  234.  
  235.   II.1.  "I. FUNCTION DECLARATIONS AND GLOBAL VARIABLES"
  236.   A listing of all functions and globals by module and by line number.
  237.   These function listings report the full function declarations.  The
  238.   globals are listed as declared both as to type and as to the relevant
  239.   storage class, i.e. extern or static.  Statics and externs are reported
  240.   in all instances, whether they are declared outside or inside a
  241.   function. C-ACROSS recognizes types which are declared both as typdefs and
  242.   as defines. In looking for typedefs and defines, it can access up to 8 
  243.   levels of nesting of include files (see III.3.b below), in addition to
  244.   reporting all user defined types which occur within the modules proper.
  245.   (This listing is really two lists:  the function declarations followed 
  246.   by the list of global variables.)
  247.  
  248. C-ACROSS (version 1.02):  README.CA                Page 6
  249.  
  250.    1.a.  When the /CDECLARE switch is set, the function declarations
  251.    are converted to prototypes by the addition of a semi-colon and a
  252.    file of all prototypes is created.  (See III.3.b.5)
  253.  
  254.  
  255.   II.2.  "II.  ALPHABETICAL INDEX OF FUNCTIONS & THEIR MODULES"
  256.   An alphabetical listing of functions showing the modules in
  257.   which they occur.
  258.  
  259.   II.3.  "III. FUNCTIONS (LISTED BY MODULE) AND CALLS"
  260.   A listing of functions by module, in the order in which they
  261.   appear, and the user-defined functions which they call. It
  262.   references each call and gives its line number.
  263.  
  264.   II.4.  "IV.  LIST OF FUNCTIONS AND CALLING FUNCTIONS"
  265.   An alphabetical listing of functions and the functions which
  266.   call them.  It lists each instance in which a caller calls.
  267.   Functions which show no callers are marked as UNUSED.
  268.  
  269.   II.5.  "V.   LISTINGS OF FUNCTION POINTERS"
  270.   There are two listings of function pointers.  The first parallels
  271.   the list described in II.4:  it lists the Global function pointers
  272.   and the functions from which they are called.  The second listing
  273.   lists all function pointers, global and local, in the order in
  274.   which they appear in the source files, as well as denoting which
  275.   functions they point to at the time of appearance and which functions
  276.   they are called from.  It also notes when function pointers are
  277.   assigned but not called.
  278.  
  279.  
  280.   II.6.  "VI.   GLOBAL VARIABLES LISTED ALPHABETICALLY"
  281.   An alphabetical listing of all globals, showing type, storage class
  282.   (extern or static) and module.  In the case of structures and
  283.   unions, structure and union identifiers are noted.  In the case
  284.   of defined types, only the defining identifiers are listed, not
  285.   their original types, i.e. an unsigned char type-defined as UCHAR
  286.   is listed as UCHAR. Moreover, types defined using #define are
  287.   categorized as typedef.  The following sample listing illustrates
  288.   both these points:
  289.  
  290.        <description of variable>                       <module >
  291.        typedef buffer[128]                              FUNC_CA
  292.            type:  UCHAR
  293.  
  294.   In the source code, UCHAR could be defined in either of the following
  295.   two ways.
  296.         typedef unsigned char UCHAR;
  297.         #define UCHAR unsigned char
  298.  
  299.  
  300.  
  301. III. INSTRUCTIONS
  302.  
  303.   III.1. DOS INCLUDE VARIABLE
  304.      1.a. If not already set, set DOS Environment INCLUDE variable to
  305.  
  306. C-ACROSS (version 1.02):  README.CA                Page 7
  307.  
  308.   the directory where Include files reside; or,
  309.     1.b. set command line INCLUDE switch to directory where Include
  310.   files reside (see Command line Switches in #3 below).
  311.  
  312.   III.2. PATH OF C FILES
  313.       2.a. The .C source files to be processed will be assumed to be in
  314.   the current directory unless a path is supplied with each file name.
  315.       2.a.  The .C extension is assumed.
  316.  
  317.   III.3. COMMAND LINE
  318.  
  319.     3.a. Syntax
  320.      Command Line Syntax:
  321.      CA [cfile_1 cfile_2 . . cfile_n] [@PROJECT_FILE]
  322.     [/[INC]LUDE=INCLUDE_DIRECTORY] [/[LEV]EL]=n] [/[NOI]NCLUDE]
  323.     [/[RED]IRECT] [/[CDE]CLARE] [/UHF] [/[IFD]EFOFF]
  324.  
  325.      Switch Syntax:
  326.      /SWITCH[=][VARIABLE]
  327.        Example:  /INCLUDE=c:\qc25\include
  328.      There must be no spaces between the front-slash [/] and the
  329.      name of the switch.  Spaces are acceptable on either side of the
  330.      equal sign.  Switches are recognized by the first three characters,
  331.      as shown in the angle brackets in 3b below, although the whole
  332.      word will be accepted.  Both upper and lower case or any mixture
  333.      thereof are acceptable as well.
  334.  
  335.     3.b. Switches
  336.  
  337.     3.b.1.   INCLUDE  </INC=c:\qc25\include>
  338.      1. C-ACROSS looks for C header files [filename.h] in the directory
  339.      specified in the DOS Environment space by the INCLUDE variable.
  340.      For Microsoft Quick C users this should already be set.  It can be
  341.      set from the command line using the DOS SET command:
  342.         SET INCLUDE=directoryname; directoryname. . .
  343.      It can also be set by using the C-ACROSS INCLUDE command line switch.
  344.      At the end of the C-ACROSS session, the DOS environment will
  345.      be reset to the INCLUDE variable which was in effect before
  346.      C_ACROSS started up.
  347.      2. The search for include files uses the Microsoft _searchenv()
  348.      function declared in stdlib.h:  the search begins in the current
  349.      directory and then proceeds to the paths path specified in the INCLUDE
  350.      environment variable.
  351.      3. It is possible to specify more than one directory when using
  352.      the </INC=> switch; however, there can be no spaces between the
  353.      named paths:
  354.         /INCLUDE=C:\QC25\INCLUDE;C:\QC25\MYFILES;D:\;D:\TEMP
  355.      Spaces are construed by the DOS command line parser as separations
  356.      between distinct arguments. Hence the inclusion of spaces will
  357.      corrupt the parsing of switches by C-ACROSS.
  358.  
  359.       3.b.2.   LEVEL  </LEV=n>
  360.        LEVEL sets an upper limit on the number of nestings of include files
  361.        which C-ACROSS will read.  The default value = 5; the maximum
  362.        value = 8;
  363.  
  364. C-ACROSS (version 1.02):  README.CA                Page 8
  365.  
  366.  
  367.       3.b 3.   NOINCLUDE </NOI>
  368.        If NOI is set, C-ACROSS will not read include files.
  369.        (See 3.b.12).
  370.  
  371.       3.b.4.   REDIRECT  </RED>
  372.        Redirects screen output to a file in the current directory named
  373.        SCRNOUT.RPT. Screen output reports on include files as they are
  374.        opened and closed (noting file handles in parentheses), lists
  375.        the defined types in each module, and reports on conditional
  376.        preprocessor defines.  See V.2 for further details.
  377.  
  378.       3.b.5.   CDECLARE </CDE>
  379.        Creates a function declaration file built from the actual
  380.        function declarations in each module. Placed at the head of
  381.        each source file in the program,  it makes a convenient header
  382.        file for checking prototypes and functions calls.  The default
  383.        extension for this file is .h$$, and the default filename is
  384.        the name of the first source file to be processed. For example,
  385.        if the first file in line to be processed is MENU.C, the
  386.        declarations file will be named MENU.H$$.  An alternate
  387.        filespec can be entered at the prompt.
  388.  
  389.       3.b.6.   UHF </UHF>
  390.        This switch stands for:  User Header Files Only.  Unless this
  391.        switch is used, C-ACROSS will analyze All header files, those of
  392.        the compiler as well as those created by the programmer, e.g.
  393.        the declarations file produced by CDECLARE.  When this switch
  394.        is used C-ACROSS will ignore all #include files which are placed
  395.        between angle brackets:   #include <stdio.h>.  It will process only
  396.        those include files which are enclosed in quotations marks:
  397.        #include "mydecl.h".  This means that if you are in the habit of
  398.        placing your own include files in the same directory as those of
  399.        the compiler and using angle brackets, you will have to change
  400.        angle brackets to quotation marks.  For general remarks on the
  401.        rules governing the search for include files, see III.3.b.1.
  402.        (See III.3.b.12).
  403.  
  404.       3.b.7.    IFDEFOFF </IFD>
  405.        This switch will turn off the processing of preprocessor
  406.        conditional compilation commands during the Second Pass,
  407.        when global variables are being analyzed.  This means that
  408.        you will get a reading of all globals referenced in both
  409.        header and source files, not just those which apply to the
  410.        currently defined environment for the program.  Thus, if you have
  411.        defined pointers to both large and small memory models, both
  412.        sets of pointers will be listed.  (See also IV.1.a.)
  413.  
  414.      3.b.8      NCX    </NCX>
  415.        NCX stands for:  No Complex Declarators.  This switch will turn
  416.        off the processing of complex declarations, both of variables and
  417.        of function prototypes.  Thus, setting /NCX will have the effect
  418.        of setting /NCP as well.  (See III.3.b.9. and  III.3.b.12.)
  419.  
  420.      3.b.9     FPS  </FPS=n>
  421.  
  422. C-ACROSS (version 1.02):  README.CA                Page 9
  423.  
  424.        FPS controls the size of the Function Pointer Stack, where
  425.        n=maximum number of function pointers which can be processed.
  426.        The default setting is 15.  If you are not using function
  427.        pointers set this value to 0 for conservation of ram.  Each
  428.        stack structure requires 66 bytes (small model).
  429.  
  430.      3.b.10.   SPLIT_REPORTFILE </SPL=n>
  431.        The main report file can be split into either two or three files,
  432.        depending on whether n=2 or n=3.  These files will have the default
  433.        extension of .RPT, but the last three letters of the report file
  434.        name will be changed to PT2 and PT3, as required.  A file whose
  435.        starting name is PROGRAM.RPT will have, when split, the name
  436.        PROGPT2.RPT for a second part, and PROGPT3.RPT for a third part.
  437.  
  438.      3.b.11.   VERBOSE </VER>
  439.      This will switch on the reporting in SCREENOUT.RPT of the
  440.      processing of Booleans used in preprocessor conditionals.
  441.  
  442.      3.b.12.   Comments on Use of Switches
  443.        Setting NOI, UHF, NCX, speeds up the program.  However,
  444.        if globals and/or the return types of functions use implementation
  445.        defined typedefs or #defines then using NOI or UHF will cause C-ACROSS
  446.        to lose necessary information.
  447.  
  448.   III.4.  Using a PROJECT-FILE
  449.        You may work from a project-file created with a standard ACII
  450.        text editor.  You can place the name and path of each .C file on
  451.        a separate line or you can list as many filespecs as you can
  452.        fit on a line with spaces between them; in the latter case if you
  453.        need more than one line, go on to the next line. The project-file
  454.        does not recognize command line switches; these must be placed
  455.        on the command line after the project-file name.  A project-file
  456.        name must be preceded by the @ character and there must be no space
  457.        between the filename and the @ character:  @makefile.ext.
  458.        Example 1:
  459.       file_1
  460.       file_2
  461.       c:\thatdir\file_3
  462.       .
  463.       .
  464.       .
  465.       file_n
  466.  
  467.        Example 2:
  468.       file_1   file_2  file_3   c:\dir2\file_4
  469.       file_5   . . .   c:\dir2\file_n
  470.  
  471.  
  472.   III.5. EXAMPLE COMMAND LINES
  473.  
  474.     CA file1 file2 c:\qc\file3 /NOI
  475.      This will treat two files in the current directory and one in c:\qc, and
  476.      it will ignore include files.
  477.  
  478.        CA @project_x  /INCLUDE=C:\QC25\INCLUDE
  479.  
  480. C-ACROSS (version 1.02):  README.CA                Page 10
  481.  
  482.      This will read the files listed in the project file named project_x and
  483.      will look for header files in c:\qc25\include.
  484.  
  485.  
  486.     If no files are listed either on the command line or in a stipulated
  487.     project file, the program will prompt the user for file name input.
  488.  
  489.  
  490.  
  491. IV.  CAVEATS AND RESTRICTIONS
  492.  
  493.  IV.1. PREPROCESSOR
  494.    C-ACROSS has a limited view of Preprocessor commands.
  495.  
  496.    IV.1.a.  Conditionals (#if. . .#ifdef..)
  497.        a.1.1. C-ACROSS accepts only definitions without assignment of
  498.      value, as in:
  499.              #define VARIABLE.
  500.      It also recognizes #undef.  If a value is defined, it will
  501.      be assigned a value of 1; if it is not defined or if it has been
  502.      #undef'd, it will be assigned a value of 0.  This is in keeping
  503.      with the Microsoft protocol in its .h files for simple inclusion
  504.      and exclusion of type and structure definitions, globals,
  505.      mutiply defined functions, etc.
  506.        a.1.2. C-ACROSS will process both #include and #define statements;
  507.      however, its processing of the #if, #ifdef group is subject to
  508.      restrictions.
  509.     a.1.2.a. It will read #if/#ifdef. . .#endif conditions only to
  510.      a maximum of three levels of nesting:
  511.  
  512.     #if defined (LEVEL_1)
  513.       #if defined (LEVEL_2)
  514.         #if defined (LEVEL_2)
  515.         #endif
  516.       #endif
  517.     #endif
  518.  
  519.     a.1.2.b. It will process only up to two conditions in any single
  520.      expression.
  521.     a.1.2.c. It will recognize binary conditionals using the new
  522.      "#if defined" and "#if !defined" commands; but in processing a
  523.      binary condition, it will recognize only the && and || operators.
  524.     a.1.2.d. Finally, C-ACROSS will not read nested sets of parentheses.
  525.  
  526.      EXAMPLES.
  527.      Accepts:     #if defined (ABC) && !defined (XYZ)
  528.               #if !defined (ABC) && !defined (XYZ)
  529.               #if defined (ABC) || defined (XYZ)
  530.               #ifndef ABC
  531.  
  532.      Rejects:     #if defined (ABC) || defined (XYZ) || defined (QRS)
  533.               #if (_MSC_VER >= 600)
  534.               #elif (defined(M_I86SM) || defined(M_I86MM))
  535.  
  536.     These last examples are from Microsoft's STDLIB.H.
  537.  
  538. C-ACROSS (version 1.02):  README.CA                Page 11
  539.  
  540.  
  541.   IV.1.b.  User defined types using #define.
  542.    C-ACROSS does not retain a fully "nested" memory of
  543.    preprocessor defines.  If a #define is defined in terms of a second
  544.    #define, C-ACROSS does not retain the memory of the first define
  545.    in its handling of the second.  For example:
  546.  
  547.     #define UCHAR unsigned char
  548.     #define UCHAR_PTR   UCHAR *
  549.     #define UCHAR_PTR_PTR  UCHAR_PTR *
  550.     UCHAR un_char;
  551.     UCHAR_PTR  un_charptr ;
  552.     UCHAR_PTR_PTR  un_charptr_ptr;
  553.  
  554.    This sequence yields the following analysis (see IV.1.c and II.6 for
  555.    use of 'typedef'):
  556.  
  557.      <description of variable>                       <module >
  558.       typedef un_char                                 FUNC_CA
  559.          [type:  UCHAR]
  560.       typedef un_charptr                              FUNC_CA
  561.          [type:  UCHAR_PTR]
  562.       typedef un_charptr_ptr                          FUNC_CA
  563.          [type:  UCHAR_PTR_PTR]
  564.  
  565.      In other words, C-ACROSS does not show the underlying lexical
  566.      structure of these statements, i.e. that un_charptr_ptr is:
  567.           unsigned char **un_charptr_ptr;
  568.      If the type UCHAR_PT_PTR were called XYZ, that is, had no symbolic
  569.      instancing of what this identifier means, we would have no
  570.      idea of the signified value behind the signifier XYZ.
  571.      C-ACROSS is content only to know that a particular identifier is
  572.      a 'type of' a preceding identifier which has itself been recognized
  573.      as a type specifier.  (For typedefs of function pointers see V.1.f).
  574.  
  575.     IV.1.c. Using #define as compared to typedef.
  576.      As the preceding example indicates C-ACROSS treats
  577.      all user defined types under the label of 'typedef', i.e.
  578.      whether they have been defined using #define or using typedef.
  579.      This did not seem to be a particular liability, since in practice
  580.      they are essentially two ways of doing the same thing. User
  581.      defined Modifiers are given modifier treatment as opposed to
  582.      type treatment. (See II.6. for further explanation and examples.)
  583.  
  584.  IV.2.  FORMATTING
  585.    There are a number of formatting limitations, none of which should
  586.    cause any special trouble.
  587.  
  588.      2.a.  C-ACROSS assumes 80 column page width.  Lines of more than
  589.      80 characters used in function declarations may cause errors in
  590.      pagination of the C-ACROSS .rpt file and will mar the appearance
  591.      of the page layout.
  592.  
  593.      2.b.  C-ACROSS does not recognize the back slash character as a
  594.      line continuator.
  595.  
  596. C-ACROSS (version 1.02):  README.CA                Page 12
  597.  
  598.  
  599.      2.c.  In the declaration of variables, it will not recognize type
  600.      specifiers which do not appear on the same line as at least one
  601.      variable.  This will be understood:
  602.  
  603.             int variable1,
  604.             variable2,
  605.             variable3;
  606.      This will not:
  607.             int
  608.             variable1,
  609.             variable2,
  610.             variable3;
  611.  
  612.      Nor will this:
  613.            extern
  614.            int i;
  615.  
  616.      In the latter case i will simply be recorded as int, not as
  617.      extern int.  A case such as this latter may very well appear in
  618.      a preprocessor #if, #else situation.  For instance:
  619.  
  620.            #if defined (EXTERNAL)
  621.            extern
  622.            #endif
  623.            int i;
  624.  
  625.      2.d. In declaring variables extern, one should specify the type
  626.      which is extern: C-ACROSS assumes that unspecified externs are
  627.      of type int.
  628.  
  629.  IV.3. REPORT FILE PATHS
  630.    3.a. C-ACROSS prompts for entry of filenames for its two main reporting
  631.    modes (CDECLARE and the standard C-ACROSS report).  If enter is pressed 
  632.    without entry of a new filespec, the report will be written to the path
  633.    of the filename displayed in brackets at the end of the prompt:
  634.  
  635.        Report File [D:\TEMP\FG$CA.rpt]: _
  636.  
  637.    If a new filename is entered, the path will be that of the new file;
  638.    if no path is specified, the path will be the current directory.
  639.  
  640.    3.b.  The SCRNOUT.RPT (resulting from /REDIRECT) is always written to
  641.    the current directory.
  642.  
  643.  IV.4.  COMMENTS
  644.    Ostensibly Microsoft QuickC does not accept nested comments.
  645.    However, it does accept nesting without an error message in
  646.    certain cases of extended comments. In addition, it does not
  647.    require a closed comment indicator [*/] in certain blocks of extended
  648.    comment, when a line within the block begins with an open comment
  649.    sign [/*]. Because C-ACROSS will give unreliable, even severely
  650.    truncated results in such cases, it provides an error message when
  651.    it comes across a possible commenting problem:  this will be printed
  652.    either to the screen or to the SCRNOUT.RPT.
  653.  
  654. C-ACROSS (version 1.02):  README.CA                Page 13
  655.  
  656.  
  657. IV.5. FUNCTION DEFINITIONS:  MULTIPLE LINES
  658.   5.a.  C-ACROSS recognizes a function definition in part by the open
  659.   parenthesis.  In the present implementation it looks for that
  660.   open parenthesis on the first line of a multiple line definition.  It
  661.   will therefore recognize this:
  662.  
  663.      struct globals_list *fill_globals_struct (char *token,
  664.       struct func *funcptr, int mods[_MAX_MODS], int __type,
  665.       int line_num, char storage, FILE * rptfp)
  666.  
  667.    but not this:
  668.  
  669.      struct globals_list *fill_globals_struct
  670.       (char *token, struct func *funcptr, int mods[_MAX_MODS],
  671.       int __type, int line_num, char storage, FILE * rptfp)
  672.  
  673.   5.b.  There is a limitation on the size of a function definition in
  674.   terms of how much of it can be displayed in section I of the
  675.   report.  The length of the definition does not affect the ability
  676.   of C-ACROSS to recognize and use the function name. The following
  677.   define is used:
  678.        #define BIGBUFSIZE  350 + 261.
  679.   The program will accept the first 349 bytes plus up to 261 bytes
  680.   of a final part line, to a maximum of 611 - 1 bytes.  Any bytes
  681.   exceeding these limits will be truncated.
  682.  
  683.  
  684. V.  READING C-ACROSS REPORTS
  685.  
  686.  V.1. Reading the Main Report File.
  687.  
  688.    V.1.a.  Functions and Globals by Module.
  689.    Following is the listing created from C-ACROSS source file TDEF_CA.C:
  690.  
  691.         TDEF_CA.C
  692.         int get_typedef(char *test)
  693.         int tdeftest(char *test)
  694.         int check_types(char *token_ptr, int *typenum)
  695.         int intypeslist(char *token)
  696.         int get_defines(char *test)
  697.         int insert_type(char *token)
  698.  
  699.         <Include File: stdio.h>
  700.          < 103: [extern] [FILE] _iob[]
  701.              < near  cdecl >
  702.         <Include File: ca.h>
  703.          <  59: [char] __type_def[__TYPEDEFS][__TYPEDEFSIZE]
  704.          <  60: [int] __typedef_count
  705.          <  61: [int] __typenum
  706.             41: [static] [int] tdef_open
  707.  
  708.    First the source file name is stated.  Below the source file is
  709.    a list of function declarations found in the file: these are the
  710.    actual function declarations drawn from the source file.
  711.  
  712. C-ACROSS (version 1.02):  README.CA                Page 14
  713.  
  714.    Then follows the global variables found in the file.  This listing shows
  715.    that globals were found in two include files, the compiler's STDIO.H and
  716.    the user's CA.H.  The names of the include files are placed in
  717.    angle brackets and an open angle bracket ["<"] is placed at
  718.    the beginning of each line cited from include files.  This practice
  719.    helps to distinguish citations from include files from those of
  720.    the source file proper.  The line numbers refer to the files
  721.    cited.  Here a global stored as an extern is found on line 103
  722.    of stdio.h.  Three other globals are found in ca.h on lines 59-61.
  723.    A final global int named tdef_open, stored as static, is found on
  724.    line 41 of the source file proper.
  725.  
  726.    V.1.b. Alphabetical listing of functions and their modules.
  727.    This listing is self-explanatory.  Following are a few lines
  728.    from C-ACROSS.RPT:
  729.  
  730.  _modifier. . . . . . . . . . FUNC_CA    argv_cat. . . . . . . . . . .INTF_CA
  731.  binary_search. . . . . . . . .XRF_CA    check_for_sign. . . . . . . .GLOB_CA
  732.  check_pointers. . . . . . . .UTLG_CA    check_types. . . . . . . . . TDEF_CA
  733.  
  734.    V.1.c. A listing of functions by module, in the order in which they
  735.    appear, and the user-defined functions which they call.
  736.  
  737.        162: get_modifiers             (UTLG_CA)
  738.             180: check_pointers
  739.             182: isolate_token
  740.             185: check_types
  741.             193: push_usertype
  742.             202: _modifier
  743.  
  744.        225: push_usertype             (UTLG_CA)
  745.  
  746.        265: pop_usertype              (UTLG_CA)
  747.  
  748.        295: is_else_if                (UTLG_CA)
  749.             314: test_token
  750.             320: def_value
  751.  
  752.    Again, this listing is self-explanatory.  Each function is recorded
  753.    as it appears in the source file, its line number is stated, and then
  754.    each function which it calls is listed by line number.  This listing
  755.    shows two functions which make no calls, push_usertype() at line 225
  756.    and pop_user_type() at 265.
  757.  
  758.    V.1.d. Alphabetical listing of functions and the functions which
  759.    call them.  It lists each instance in which a caller calls.
  760.  
  761.     data_type_
  762.           data_type_
  763.           data_type_
  764.           data_type_
  765.           main_loop
  766.           record_variables
  767.           vol_const
  768.           get_defines
  769.  
  770. C-ACROSS (version 1.02):  README.CA                Page 15
  771.  
  772.  
  773.     date_time
  774.           make_rptfile
  775.          .
  776.          .
  777.          .
  778.     unused_function
  779.           UNUSED FUNCTION
  780.  
  781.    This example shows three functions, one of them the hypothetical
  782.    unused_function(), which is marked as UNUSED.  The first function
  783.    reveals itself as a recursive function which calls itself three
  784.    times; this recursivity would also show up in the listings described
  785.    above in 1.c., which would also provide line numbers:
  786.  
  787.         63: data_type_                (FUNC_CA)
  788.             102: is_include
  789.             164: data_type_
  790.             209: data_type_
  791.             214: data_type_
  792.  
  793.    V.1.e. Alphabetical listing of globals, showing type, storage class
  794.    and module.
  795.    It is this listing which will prove most useful in helping with
  796.    the kinds of problems touched on in I.2.a.
  797.  
  798.       <storage>   <type>   <variable>                             <module>
  799.                <modifiers /structs /typedefs>
  800.  
  801.           typedef *start_ifdef_stack                      IFDEF_CA
  802.              [type:  IF_DEF_STACK]
  803.               .
  804.               .
  805.     extern    int     timezone                                 UTIL_CA
  806.           < near  cdecl >
  807.  
  808.           char    token[81]                                PARSE_CA
  809.     static    struct  *top                                     GLOB_CA
  810.               [struct:  globals_list]
  811.     static    struct  *top                                     FUNC_CA
  812.               [struct:  func]
  813.     static    struct  *top                                     FUNC_CA
  814.               [struct:  func]
  815.               .
  816.               .
  817.               .
  818.     extern    char    *TYPES[]                                 UTLG_CA
  819.     extern    char    *TYPES[]                                 GLOB_CA
  820.     extern    char    *TYPES[]                                 PARSE_CA
  821.           char    *TYPES[]                                 FUNC_CA
  822.     extern    char    tzname[2]                                UTIL_CA
  823.               < * near  cdecl >
  824.  
  825.           int     user_hfile_only                          INTF_CA
  826.     extern    int     user_hfile_only                          GLOB_CA
  827.  
  828. C-ACROSS (version 1.02):  README.CA                Page 16
  829.  
  830.  
  831.  
  832.      1.e.1. As this listing shows, for ease of reading the alphabeticization
  833.    occurs in blocks, as here, where t's and u's are separated by a space.
  834.  
  835.      1.e.2.  First Line of the C-ACROSS variable description.
  836.    The first line states the storage class, the type, the variable
  837.    name and, if it is an array, its dimensions.  These details are
  838.    followed by the module in which the variable appears. The simplest case
  839.    in the above listing is "token" which has the same form as it would
  840.    have in a declaration:  it is an 81 byte character array, and it is named
  841.    only once in the program in the file PARSE_CA.  Similarly,
  842.    "user_hfile_only" is equally simple, except that it is named in two
  843.    files, in one of which it is named as an extern.
  844.  
  845.      1.e.3. Second Line of variable description.
  846.        1.e.3.a. If the variable is a structure, union,  or typedef the name
  847.    of the type, union, or structure is given on the second line in square
  848.    brackets. Thus "top" is used in a number of places as a pointer to a
  849.    structure. In the first case, it is a pointer to a structure defined by
  850.    "globals_list."  In the second instance, however, there may be a
  851.    potential conflict, since it is used twice in the same module to
  852.    point to structures of the same type; but on checking the file, it
  853.    is seen that the second instance occurs within a function and has
  854.    local scope, while the first has file scope.  What this example
  855.    emphasizes is a fact pointed out above (II.1):  C-ACROSS lists
  856.    all instances of static variables, whether they have local or
  857.    global scope.  (For more on the listing of types see IV.1.c and II.6)
  858.        1.e.3.b. Also on the second line, but in angle brackets, are listed
  859.    all of the modifiers and qualifiers which define the variable. In
  860.    addition, any pointer designators which do not appear immediately to
  861.    the right of the variable are also placed on this line.  Modifiers,
  862.    qualifiers, and pointer designators are listed in the order in which
  863.    they appear in the declaration.
  864.  
  865.      1.e.4.  Normally the extern and static storage class modifiers
  866.    are the first names in the declaration.  C-ACROSS assumes that this
  867.    will be the case; if it is not, the storage class will appear on the
  868.    second line of the description together with other modifiers and
  869.    qualifiers.  Thus, the declaration:
  870.  
  871.          int extern _near ExternSecond;
  872.  
  873.     yields the following C-ACROSS description:
  874.  
  875.        int     ExternSecond                             TEST
  876.            < extern  near >
  877.  
  878.     This is situation is illustrated 1.e.6. below as well in the case of
  879.     the variable "*hardware_location_0".
  880.  
  881.       1.e.5. As Harbison and Steele point out, "It is a well-known deficiency
  882.     in C that defining and referencing occurrences of external variable
  883.     declarations are difficult to distinguish." (p. 92)  In the case
  884.     of "*TYPES[]", which is an array of character pointers that is
  885.  
  886. C-ACROSS (version 1.02):  README.CA                Page 17
  887.  
  888.     used in four modules, the usefulness of C-ACROSS in distinguishing
  889.     between defining and referencing externals is apparent.  It is clear
  890.     that *TYPES[] is defined in PARSE_CA and referenced through the use
  891.     of the "extern" modifier in the three other modules.
  892.     1.e.5.a. In Microsoft Quick C, variables with file scope, i.e.
  893.     declared outside of functions, are all treated as extern whether or not
  894.     they are given the "extern" modifier.  This could lead to a conflict if
  895.     the same global name is used unwittingly in two modules for different
  896.     purposes. C-ACROSS makes any such conflicts immediately apparent by
  897.     showing where the "extern" modifier has been applied.  The following
  898.     listing, for instance, could indicate a conflict, since in neither
  899.     file does "extern" modify "user_hfile_only":
  900.           int     user_hfile_only                          INTF_CA
  901.           int     user_hfile_only                          GLOB_CA
  902.  
  903.  
  904.      1.e.6. Reading variables with modifiers and qualifiers.
  905.     The following style of listing comes from section I of a report file
  906.     ("FUNCTION DECLARATIONS AND GLOBAL VARIABLES"):
  907.  
  908.        7: [int] near_far
  909.            < near  * far >
  910.        9: [int] test
  911.            < far >
  912.        101: [int] const_pointer_to_int
  913.          < * const >
  914.        102: [int] *pointer_to_constant
  915.          < const  near >
  916.        103: [static] [int] *static_pointer_to_const
  917.          < const >
  918.        104: [int] *hardware_location_0
  919.          < volatile  static  far >
  920.  
  921.     These variables were declared in the source file as follows:
  922.  
  923.     int _near * _far near_far;
  924.     int far test;
  925.     int * const const_pointer_to_int;
  926.     const int _near * pointer_to_constant;
  927.     static const int *static_pointer_to_const;
  928.     volatile int static _far *hardware_location_0;
  929.  
  930.       1.e.6.a  Unlike "extern" and "static", which must take their normal
  931.     positions in a declaration, if they are to appear in their normal place
  932.       in the C-ACROSS descriptor,  the qualifiers "const" and "volatile"
  933.       may appear at any legal point in the declaration and will always be
  934.       placed among the modifiers.  Often, the "const" or "volatile"
  935.       qualifier may take the first position in a declaration; when this occurs,
  936.       as noted in 1.e.4., the storage class will be entered on the second
  937.       line of the C-ACROSS descriptor.  Various cases are illustrated by
  938.       the examples in example lines 102-104.
  939.      1.e.6.b. Some of the ways in which a C-ACROSS description may be
  940.       of some value in sorting out the meaning a declaration are illustrated
  941.       in these example lines.
  942.         1. A modifier is understood to modify the item to its right.
  943.  
  944. C-ACROSS (version 1.02):  README.CA                Page 18
  945.  
  946.        (Microsoft QuickC Compiler: Language Reference, 4.33)  Generally,
  947.        they can be placed in any order which makes legal sense and in many
  948.        cases the order does not matter, as is the case with the variable
  949.        described at line 104. In the simplest cases, as in line 9, the
  950.        modifiers in the angle brackets represent modifiers which
  951.        appear to the right of the variable and modify it.
  952.        2.  Line 7, however, offers a more complex situation. In the
  953.        declaration of variables, the pointer designator ("*") normally
  954.        applies to the item immediately to its right.  For example,
  955.        *hardware_location_0 is understood to be a pointer, pointing to an
  956.        int.  In line 7, the pointer symbol applies to the modifier
  957.        "far", i.e. "near_far" is a far pointer to a near object,
  958.        an integer.  The pointer symbol associates right and has precedence
  959.        over the preceding modifier "near"; otherwise we'd have a near
  960.        pointer to a far object which, of course, cannot exist.
  961.       The schematic representation of the C-ACROSS descriptor should
  962.        help in the recognition of these facts by isolating the modifiers:
  963.        one can see at a glance that "near_far" is a far pointer,  given
  964.        that the pointer symbol attaches itself to the name to its
  965.        right: * far.
  966.      3. An analogous kind of reading applies to declarations
  967.        of const and volatile variables.  (The examples are adapted from
  968.        Harbison and Steele's discussion of qualifiers.)  Again, the second
  969.        line of "const_pointer_to_int" shows us at a glance that we have here a
  970.        constant pointer: < * const >.   On the other hand,
  971.        "*pointer_to_constant" is a near pointer to a constant object.
  972.        Unless the pointer symbol is applied directly to the qualifier,
  973.        in which case we would get "<* const >", the qualifier must
  974.        qualify the object pointed to.
  975.  
  976.        1.e.7. The following listing illustrates the handling of types defined
  977.      by two type specifiers, as in "unsigned long":
  978.  
  979.        <storage>   <type>   <variable>                             <module>
  980.  
  981.           [l]double  LONGdouble                               TEST
  982.  
  983.              signed  SIGNEDbyitself                           TEST
  984.              char    simple                                   TEST
  985.           [s]int     signedint                                TEST
  986.  
  987.           [u]char    unsignedCHAR                             TEST
  988.           [u]long    UNSIGNED_long                            TEST
  989.  
  990.      The first character of the modifying type specifier is placed in square
  991.      brackets before the main specifier.   If "signed" or "unsigned" is
  992.      used by itself it is represented as in SIGNEDbyitself.
  993.  
  994.        1.e.8.  Complex Declarations.
  995.      No attempt is made to break down complex declarations into descriptor
  996.      form, beyond the first line, where it is shown what storage class and
  997.      type are indicated in the variable declaration.  Moreover, if a pointer
  998.      designator appears to the right of the variable, it is removed.  Then,
  999.      the entire declaration is reprinted on the second line.  When modifiers
  1000.      or qualifiers appear to the left of the first set of parentheses,
  1001.  
  1002. C-ACROSS (version 1.02):  README.CA                Page 19
  1003.  
  1004.      they are placed on the second line and the rest of the declaration then
  1005.      appears on the third line.  Some examples follow:
  1006.  
  1007.      extern    char    charVAR                                  TEST
  1008.                *(*(*charVAR)()) [10]
  1009.  
  1010.            char    getint                                   TEST
  1011.                < far >
  1012.                * (far *getint)(int far *)
  1013.  
  1014.            int     intVAR                                   TEST
  1015.                < const >
  1016.                (*intVAR)[5]
  1017.  
  1018.        e.8.1    Using the principles laid down in section  V.1.e.6,
  1019.      "intVAR" is clearly a pointer to a constant object or objects:
  1020.      in fact, a pointer to an array of five constant ints.
  1021.        e.8.2   "getint" is a far pointer to a function which returns
  1022.      a pointer; the far modifier in brackets on the second line tells
  1023.      us that the returned pointer is far and the type specifier tells us
  1024.      that it is a far pointer to a char.
  1025.        e.8.3  The first example is a pointer to a function which returns a
  1026.      pointer to an array of 10 elements; each array element is a pointer
  1027.      to a char.  This example and "getint" are found in "Microsoft
  1028.      C Language Reference" (pp. 56, 61).
  1029.  
  1030.      V.1.f  The Listing and Treatment of Function Pointers.
  1031.        1.f.1. The following are some examples of declarations of
  1032.        function pointers:
  1033.  
  1034.        double ( *(*vdptr)  (double (*) [3]) )[3];
  1035.        char *(*np)(char *);
  1036.        char  *( (*fp) )  (char *) = routine;
  1037.        typedef void sig_handler(int sig);
  1038.        sig_handler *(*SHANDLER) (int sig, sig_handler *func) = signal;
  1039.  
  1040.      In listing "I. FUNCTION DECLARATIONS AND GLOBAL VARIABLES" (see above:
  1041.      V.1.a) these declarations will be treated as follows:
  1042.  
  1043.     6: [double] vdptr
  1044.        <Fn Ptr> ( *(*vdptr)  (double (*) [3]) )[3]
  1045.     9: [char] np
  1046.        <Fn Ptr> *(*np)(char *)
  1047.        16: [char] fp
  1048.        <Fn Ptr> *( (*fp) )  (char *) = routine
  1049.        25: [typedef] SHANDLER
  1050.        type: sig_handler
  1051.        <Fn Ptr> *(*SHANDLER) (int sig, sig_handler *func) = signal
  1052.  
  1053.     Notice that C-ACROSS recognizes the complex typedef of sig_handler.
  1054.     In the global listings, we would have the following:
  1055.  
  1056.  
  1057. extern    char    np                                       TEST2FP
  1058.           <Fn Ptr>
  1059.  
  1060. C-ACROSS (version 1.02):  README.CA                Page 20
  1061.  
  1062.           *(*np)(char *)
  1063.       char    np                                       TEST1FP
  1064.           <Fn Ptr>
  1065.           *(*np)(char *)
  1066.  
  1067.       typedef SHANDLER                                 TEST1FP
  1068.          [type:  sig_handler]
  1069.           <Fn Ptr>
  1070.           *(*SHANDLER) (int sig, sig_handler *func) = signal
  1071.  
  1072.       double  vdptr                                    TEST1FP
  1073.           <Fn Ptr>
  1074.           ( *(*vdptr)  (double (*) [3]) )[3]
  1075.  
  1076.      1.f.2.  C-ACROSS also producess two additional listings for
  1077.     the pointers to functions.
  1078.       f.2.a. The first of these conforms to the listing of functions
  1079.     and calling functions (see II.4. and V.1.d.). It lists all GLOBAL
  1080.     pointers and the functions from which they are called, noting where
  1081.     necessary when the pointer is not used.
  1082.  
  1083.     V.   FUNCTION POINTERS AND CALLING FUNCTIONS
  1084.  
  1085.  
  1086.     <Global Pointers>
  1087.            <Functions Called From>
  1088.         . . . .
  1089.  
  1090.  
  1091.     SHANDLER                          [TEST1FP]
  1092.           UNUSED PTR TO FUNCTION
  1093.  
  1094.  
  1095.     fp                                [TEST1FP]
  1096.           main                                (TEST1FP)
  1097.  
  1098.     np                                [TEST1FP]
  1099.           vardub                              (TEST1FP)
  1100.           routine2                            (TEST2FP)
  1101.  
  1102.     testGetinT                        [TEST1FP]
  1103.           UNUSED PTR TO FUNCTION
  1104.  
  1105.     vdptr                             [TEST1FP]
  1106.           main                                (TEST1FP)
  1107.  
  1108.       f.2.b. The second listing lists ALL function pointers, both
  1109.       GLOBAL and LOCAL, in the order in which they appear.  This
  1110.       allows for an overview of the changing values of Global pointers
  1111.       to functions.
  1112.  
  1113.     Pointer Name             Function Pointed To        [Calling Function]
  1114.  
  1115.     fp                        routine                    [NOT CALLED]
  1116.     SHANDLER                  signal                     [NOT CALLED]
  1117.  
  1118. C-ACROSS (version 1.02):  README.CA                Page 21
  1119.  
  1120.     test2ptr                  routine                    [NOT CALLED]
  1121.     testfuncT                 FUNCT                      [main]
  1122.     vdptr                     vardub                     [main]
  1123.     np                        routine                    [main]
  1124.     fp2                       to_newfn                   [routine]
  1125.     fp2                       routine                    [vardub]
  1126.     fp2                       routine2                   [to_newfn]
  1127.     fp2                       routine                    [vardub]
  1128.  
  1129.  
  1130.  
  1131.  V.2.  The SCRNOUT Report.
  1132.     For instructions on how to create the SCRNOUT.RPT see III.3.b.4;
  1133.     See also IV.3.b.  This report is created by redirecting screen
  1134.     output to the file SCRNOUT.RPT.  The screen output was originally
  1135.     intended as information while debugging C-ACROSS;  the author
  1136.     thought that some or all of this information might be of use
  1137.     to the user of C-ACROSS.  It now includes error messages as well.
  1138.  
  1139.        1.  SCRNOUT.RPT first lists all the include files which are opened
  1140.     and closed during processing:
  1141.  
  1142.        Opened Include File: stdlib.h (9)
  1143.        Closing Include: stdlib.h (9). Returning to Module: FUNC_CA (8)
  1144.        Opened Include File: stdio.h (9)
  1145.        Closing Include: stdio.h (9). Returning to Module: FUNC_CA (8)
  1146.  
  1147.     The numbers in parentheses are the file handles.
  1148.  
  1149.        2.  It then lists the User defined types found in the module
  1150.     being processed.
  1151.  
  1152.        3. During the second pass, when globals are being processed, it
  1153.     reports on whether or not #defines are found, if verbose switch
  1154.     is set.
  1155.  
  1156.  
  1157. VI.    ERRORS
  1158.        Any errors will be reported in the SCRNOUT.RPT.  Most errors
  1159.        cause termination of the program, insofar as they will most
  1160.        likely be caused by missing information needed for further
  1161.        processing.
  1162.  
  1163.  
  1164. VII.  FILES INCLUDED ON C-ACROSS DISKS
  1165.  
  1166.      <File>                         <Purpose/contents>
  1167.  
  1168. 1.  FUNC_CA             ... Parses function definitions; First Pass
  1169. 2.  GLOB_CA             ... Parses and prints globals: Second Pass
  1170. 3.  IFDEF_CA            ... Handles preprocessor defines
  1171. 4.  INTF_CA             ... User interface module:  contains main()
  1172. 5.  LINKL_CA            ... Creates linked lists of functions and
  1173.               globals and prints lists of functions
  1174.               derived from linked lists
  1175.  
  1176. C-ACROSS (version 1.02):  README.CA                Page 22
  1177.  
  1178. 6.  PARSE_CA            ... Third Pass function parser: tokenizes file
  1179. 7.  TDEF_CA             ... User type functions
  1180. 8.  TYPES_CA            ... Main functions used for parsing types,
  1181.                 modifiers, and qualifiers
  1182. 9.  UTIL_CA             ... Utility functions for FUNC_CA and file
  1183.                 handling
  1184. 10.  UTLG_CA            ... Utility functions used in parsing globals
  1185. 11.  XRF_CA             ... Main loop for Third Pass (xrf), in which
  1186.                  cross references of functions are established
  1187.                  to create calls from and calls to lists
  1188. 12. EXIT_CA             ... Exit on error routines
  1189. 13. README.CA           ... Instructions
  1190. 14. CDECL_CA.H          ... Declarations of all functions:  created
  1191.                 using /CDECLARE switch
  1192. 15. CA.H                ... Structure and variable declarations, defines
  1193. 16. KEYWORDS.H          ... More declarations and defines relating to
  1194.                 key words, modifiers, type specifiers
  1195. 17. CA.PRJ              ... The project file for creating a report
  1196.                 file for C-ACROSS
  1197. 18. CA.RPT              ... A full report file on C-ACROSS, including
  1198.                 Microsoft and user header file results
  1199. 19. CA.MAK              ... Microsoft make file for C-ACROSS
  1200.                 C-ACROSS needs stack of 3000 bytes
  1201.                 or greater.
  1202. 20. SCREENOUT.RPT       ... See V.1. above: second report file.
  1203. 21. CA.EXE              ... The C-ACROSS program file.
  1204.  
  1205. VIII.  COPYRIGHT
  1206.       C-ACROSS is copyright (C) by MYRON TURNER, who retains the
  1207.       rights to this (version 1.02) and all subsequent versions.
  1208.  
  1209.   The following permissions are granted:
  1210.  
  1211.   1. Permission is granted to The C Users' Group to distribute
  1212.   C-ACROSS, without royalty or other compensation, and to charge
  1213.   their normal distribution fee for such distribution.
  1214.  
  1215.   2. The C Users' Group may distribute C-ACROSS for non-commercial
  1216.   personal use.
  1217.  
  1218.   3. The phrase "non-commercial" in 2 above excludes use in the
  1219.   development of software for sale as well as redistribution in
  1220.   whole or part for purposes of sale.
  1221.  
  1222.   4.  For commercial use of C-ACROSS (version 1.02) written permission
  1223.   is required from the author of C-ACROSS or his representative(s).
  1224.   A fee will not be required for the commercial use of C-ACROSS
  1225.   (version 1.02); however, the letter of permision will set out the
  1226.   terms which will govern its commerical use.
  1227.  
  1228.  
  1229.  
  1230. C-ACROSS (version 1.02):  README.CA                Page 23
  1231.  
  1232.   5.  Permission is granted to the non-commercial, personal user to
  1233.   make changes in C-ACROSS but not to distribute it with those changes
  1234.   without consulting the author or his representative(s).
  1235.  
  1236.   6.  Points 5 and 6 above are aimed at helping the author to keep
  1237.   track of C-ACROSS so that he may incorporate any changes and fixes
  1238.   into future versions of the program.  He would be grateful for any
  1239.   comments concerning the use and usefulness of C-ACROSS, as well
  1240.   as fixes.  Please write to the address given at the head of this file.
  1241.   It would be helpful to receive copies of the C source files which
  1242.   result in any bugs.
  1243.  
  1244.