home *** CD-ROM | disk | FTP | other *** search
/ Collection of Education / collectionofeducationcarat1997.iso / COMPUSCI / CSCOP.ZIP / CSCOPE.DOC < prev    next >
Text File  |  1993-10-31  |  39KB  |  1,495 lines
  1.  
  2.  
  3.                                                                             
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                                     c-scope
  16.  
  17.  
  18.                                    C program
  19.  
  20.                                  analysis tool
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.                                  User's Manual
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.                                  JAYAR Systems
  52.                               253 College Street
  53.                                    Suite 263
  54.                                Toronto, Ontario
  55.                                Canada   M5T 1R5
  56.                                 (416) 751-5678
  57.  
  58.  
  59.                                        
  60.  
  61.  
  62.  
  63.                                                                             
  64.  
  65.  
  66.                                     LICENSE
  67.  
  68.         The license for the Shareware evaluation (trial use) version of
  69.   c-scope is contained in the file LICENSE.DOC. This file has been included
  70.   for your convenience as an appendix to this manual.
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.                                    WARRANTY
  79.  
  80.         The Shareware evaluation (trial use) version of c-scope is provided
  81.   AS IS. JAYAR Systems MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED,
  82.   INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY AND/OR
  83.   FITNESS FOR A PARTICULAR PURPOSE.
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.                                 SUPPORT POLICY
  92.  
  93.         JAYAR Systems provides free support for this product. We will answer
  94.   questions and fix serious bugs. If you have any questions about or problems
  95.   with using this product, give us a call at the number on the front cover of
  96.   this manual. Or, if you are not in a rush, send us a letter.
  97.  
  98.         We would also appreciate hearing from you if you have any comments or
  99.   suggestions for improvements.
  100.  
  101.  
  102.  
  103.  
  104.  
  105.                      _______                    
  106.                 ____|__     |               (R) 
  107.              --|       |    |-------------------
  108.                |   ____|__  |  Association of   
  109.                |  |       |_|  Shareware        
  110.                |__|   o   |    Professionals    
  111.              -----|   |   |---------------------
  112.                   |___|___|    MEMBER           
  113.  
  114.  
  115.                   c-scope Copyright (C) 1991-93 JAYAR Systems
  116.                               All Rights Reserved
  117.  
  118.  
  119.                                        
  120.  
  121.  
  122.  
  123.                                                                             
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.                                    CONTENTS
  132.  
  133.  
  134.  
  135.   1      Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .    1
  136.   2      What c-scope does . . . . . . . . . . . . . . . . . . . . . . .    2
  137.   3      Using c-scope . . . . . . . . . . . . . . . . . . . . . . . . .    8
  138.           1 Installing c-scope . . . . . . . . . . . . . . . . . . . . .    8
  139.           2 Running c-scope  . . . . . . . . . . . . . . . . . . . . . .    8
  140.           3 Ignoring functions . . . . . . . . . . . . . . . . . . . . .    9
  141.           4 Function declarations  . . . . . . . . . . . . . . . . . . .    9
  142.   4      Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   11
  143.           1 Non-standard function types  . . . . . . . . . . . . . . . .   11
  144.           2 Preprocessor . . . . . . . . . . . . . . . . . . . . . . . .   11
  145.           3 Function pointers  . . . . . . . . . . . . . . . . . . . . .   11
  146.   A      Error messages  . . . . . . . . . . . . . . . . . . . . . . . .   13
  147.   B      License . . . . . . . . . . . . . . . . . . . . . . . . . . . .   15
  148.   C      Trial Use License:  . . . . . . . . . . . . . . . . . . . . . .   16
  149.   D      Limited Distribution License: . . . . . . . . . . . . . . . . .   17
  150.   E      Definition of Shareware . . . . . . . . . . . . . . . . . . . .   19
  151.   F      How to Register . . . . . . . . . . . . . . . . . . . . . . . .   20
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.                                      iii
  179.  
  180.  
  181.  
  182.  
  183.                                                                             
  184.  
  185.  
  186.  
  187.  
  188.  
  189.                                 1 Introduction 
  190.  
  191.  
  192.   c-scope is an analysis tool for C programs. It shows you what functions are
  193.   contained in a program and which functions they reference. This information
  194.   is provided in several easy-to-use formats. In addition, the registered
  195.   version of c-scope computes and reports a number of software complexity
  196.   metrics for each function.
  197.  
  198.         The program to be analyzed may be contained in one file, or spread
  199.   across many files, as is typical with C programs.
  200.  
  201.         It is possible with c-scope to get detailed information on all of the
  202.   inter-function references, or just on those that you are interested in.
  203.  
  204.         The analysis provided by c-scope is ideal for understanding or
  205.   documenting the structure and operation of a large C program, whether it is
  206.   a program you wrote or one that you inherited.
  207.  
  208.         Using c-scope is simple and is described in the following sections of
  209.   the manual. Section 2 describes c-scope's capabilities by working through a
  210.   short example. Section 8 shows you how to use c-scope. And Section 3.4
  211.   provides a few notes on using c-scope.
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.                                       1
  239.  
  240.  
  241.  
  242.  
  243.                                                        What c-scope does   2
  244.  
  245.  
  246.  
  247.  
  248.  
  249.                              2 What c-scope does 
  250.  
  251.  
  252.   The easiest way to explain what c-scope does is to work through an example.
  253.   For illustration purposes we will use the following simple example program
  254.   (the RPN desk calculator program, borrowed from K & R) and analyze it with
  255.   c-scope. The program consists of five functions, in three files.
  256.  
  257.         File DCALC.C in Figure 1 contains the main program, main(), file
  258.   STACK.C in Figure 2 contains the functions push(), pop() and clear() and
  259.   file GETOP.C in Figure 3 contains function getop().
  260.  
  261.         When c-scope analyzes a program it produces four reports which are
  262.   printed on stdout:
  263.  
  264.     o A Function Location report. For each function defined in your program
  265.       (i.e., has source code), c-scope lists the function (functions are
  266.       listed alphabetically), the name of the file the function is contained
  267.       in, and the line number in the file where the function is defined; for
  268.       our example program:
  269.  
  270.               FUNCTION LOCATION
  271.  
  272.               Function              File                  Line No.
  273.               --------------------  --------------------  --------
  274.               clear                 STACK.C                     34
  275.               getop                 GETOP.C                      6
  276.               main                  DCALC.C                      7
  277.               pop                   STACK.C                     22
  278.               push                  STACK.C                     10
  279.  
  280.     o A File Contents report. This is similar to the Function Location
  281.       report, but for each file the functions defined in it are listed. File
  282.       names are printed in the order determined by the contents of the file
  283.       SOURCE.DAT (discussed later in Section 8):
  284.  
  285.               FILE CONTENTS
  286.  
  287.               File                  Function
  288.               --------------------  --------------------
  289.  
  290.               GETOP.C               getop               
  291.  
  292.               DCALC.C               main                
  293.  
  294.               STACK.C               push                
  295.                                     pop                 
  296.                                     clear               
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.                                                        What c-scope does   3
  304.  
  305.  
  306.     o A Function References report. For each function defined in the program
  307.       (i.e., whose source code is available), an alphabetical list of the
  308.       functions called by that function are listed. c-scope recognizes a
  309.       function call if it occurs in the body of the function or in an
  310.       initialization statement. Functions which do not reference any other
  311.       functions are listed as referencing function void (