home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
DP Tool Club 8
/
CDASC08.ISO
/
VRAC
/
CSCOP110.ZIP
/
CSCOPE.DOC
< prev
next >
Wrap
Text File
|
1993-04-15
|
35KB
|
989 lines
c-scope
C program
analysis tool
User's Manual
JAYAR Systems
253 College Street
Suite 263
Toronto, Ontario
Canada M5T 1R5
(416) 751-5678
LICENSE
The license for the Shareware evaluation (trial use) version of
c-scope is contained in the file LICENSE.DOC. This file has been
included for your convenience as an appendix to this manual.
WARRANTY
The Shareware evaluation (trial use) version of c-scope is provided AS
IS. JAYAR Systems MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR
IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF
MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
SUPPORT POLICY
JAYAR Systems provides free support for this product. We will answer
questions and fix serious bugs. If you have any questions about or
problems with using this product, give us a call at the number on the
inside front cover of this manual. Or, if you are not in a rush, send
us a letter.
We would also appreciate hearing from you if you have any comments or
suggestions for improvements.
_______
____|__ | (R)
--| | |-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
-----| | |---------------------
|___|___| MEMBER
c-scope Copyright (C) 1992-93 JAYAR Systems
All Rights Reserved
CONTENTS
1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . 2
2 WHAT C-SCOPE DOES . . . . . . . . . . . . . . . . . 2
3 USING C-SCOPE . . . . . . . . . . . . . . . . . . . 7
3.1 Installing C-scope . . . . . . . . . . . . . . . . 8
3.2 Running C-scope . . . . . . . . . . . . . . . . . 8
3.3 Ignoring Functions . . . . . . . . . . . . . . . . 9
3.4 Function Declarations . . . . . . . . . . . . . . 9
4 NOTES . . . . . . . . . . . . . . . . . . . . . . 10
4.1 Non-standard Function Types . . . . . . . . . . 10
4.2 Preprocessor . . . . . . . . . . . . . . . . . . 10
4.3 Function Pointers . . . . . . . . . . . . . . . 10
APPENDIX A LICENSE
A.1 TRIAL USE LICENSE: . . . . . . . . . . . . . . . . A-1
A.2 LIMITED DISTRIBUTION LICENSE: . . . . . . . . . . A-2
APPENDIX B DEFINITION OF SHAREWARE
APPENDIX C HOW TO REGISTER
c-scope User's Manual (JAYAR Systems) Page 2
INTRODUCTION
1 INTRODUCTION
c-scope is an analysis tool for C programs. It shows you what
functions are contained in a program and which functions they
reference. This information is provided in several easy-to-use
formats. In addition, the registered version of c-scope computes and
reports a number of software complexity metrics for each function.
The program to be analyzed may be contained in one file, or spread
across many files, as is typical with C programs.
It is possible with c-scope to get detailed information on all of the
inter-function references, or just on those that you are interested
in.
The analysis provided by c-scope is ideal for understanding or
documenting the structure and operation of a large C program, whether
it is a program you wrote or one that you inherited.
Using c-scope is simple and is described in the following sections of
the manual. Section 2 describes c-scope's capabilities by working
through a short example. Section 3 shows you how to use c-scope. And
Section 4 provides a few notes on using c-scope.
2 WHAT C-SCOPE DOES
The easiest way to explain what c-scope does is to work through an
example. For illustration purposes we will use the following simple
example program (the RPN desk calculator program, borrowed from K & R)
and analyze it with c-scope. The program consists of five functions,
in three files.
File DCALC.C in Figure 1 contains the main program, main(), file
STACK.C in Figure 2 contains the functions push(), pop() and clear()
and file GETOP.C in Figure 3 contains function getop().
When c-scope analyzes a program it produces four reports which are
printed on stdout:
1. A Function Location report. For each function defined in your
program (i.e., has source code), c-scope lists the function
(functions are listed alphabetically), the name of the file the
function is contained in, and the line number in the file where
the function is defined; for our example program:
FUNCTION LOCATION
Function File Line No.
-------------------- -------------------- --------
clear STACK.C 34
getop GETOP.C 6
main DCALC.C 7
c-scope User's Manual (JAYAR Systems) Page 3
WHAT C-SCOPE DOES
pop STACK.C 22
push STACK.C 10
2. A File Contents report. This is similar to the Function Location
report, but for each file the functions defined in it are listed.
File names are printed in the order determined by the contents of
the file SOURCE.DAT (discussed later in Section 3.2):
FILE CONTENTS
File Function
-------------------- --------------------
GETOP.C getop
DCALC.C main
STACK.C push
pop
clear
3. A Function References report. For each function defined in the
program (i.e., whose source code is available), an alphabetical
list of the functions called by that function are listed. c-scope
recognizes a function call if it occurs in the body of the
function or in an initialization statement. Functions which do
not reference any other functions are listed as referencing
function void (e.g., function clear() in our example):
FUNCTION REFERENCES
Function References function
-------------------- --------------------
getop getc
ungetc
main atof
clear
getop
pop
printf
push
push clear
printf
pop clear
printf
clear void
c-scope User's Manual (JAYAR Systems) Page 4
WHAT C-SCOPE DOES
4. A Static Calling Tree. Starting with the main() function, all the
functions it calls, and all the functions called by those
functions, etc. are listed in a tree format:
STATIC CALLING TREE
0. main
1. atof[E]
1. clear
1. getop
2. getc[E]
2. ungetc[E]
1. pop
2. clear
2. printf[E]
1. printf[E]
1. push
2. clear
2. printf[E]
A level number is printed beside each function name to aid
interpretation. main() is at level 0, all the functions called by
main() are at level 1, and so on. The functions referenced by a
higher level function are listed alphabetically.
Multiple references to a function are ignored--main() in our
example calls push() and pop() several times, but they only appear
in the tree once. If a function appears more than once in the
tree, because it is called by more than one function, the function
is only expanded the first time, to reduce the amount of output.
Including the -E option will force c-scope to expand all
references though.
The letter [E] following a function name means the function is
defined externally--its source code was not available. The letter
[R] is also printed for functions that are called recursively.
If a main() function is not defined, a static calling tree is not
produced.
The registered version of c-scope also produces a Function Complexity
report. For each function in your program c-scope lists the function
name, the number of source lines in it, the number of statements in it
and the number of while, for, switch and if statements. See Appendix
C for information on registering your version of c-scope.
c-scope User's Manual (JAYAR Systems) Page 5
WHAT C-SCOPE DOES
#include <stdio.h>
#define MAXOP 20
#define NUMBER '0'
#define TOOBIG '9'
main()
{
int type;
char s[MAXOP];
double op2, atof(char *), pop(void), push(double);
void clear(void);
int getop(char *s, int lim);
while ((type = getop(s, MAXOP)) != EOF)
switch (type)
{ case NUMBER: push(atof(s));
break;
case '+': push(pop() + pop());
break;
case '*': push(pop() * pop());
break;
case '-': op2 = pop();
push(pop() - op2);
break;
case '/': op2 = pop();
if (op2 != 0.0)
push(pop() / op2);
else
printf("zero divisor popped\n");
break;
case '=': printf("\t%f\n",push(pop()));
break;
case 'c': clear();
break;
case TOOBIG: printf("%.20s ... is too long\n",s);
break;
default: printf("unknown command %c\n", type);
break;
}
}
Figure 1: File DCALC.C which contains function main().
c-scope User's Manual (JAYAR Systems) Page 6
WHAT C-SCOPE DOES
#include <stdio.h>
#define MAXVAL 100
int sp = 0;
double val[MAXVAL], push(double f), pop(void);
void clear(void);
double push(double f)
{
if (sp < MAXVAL)
return(val[sp++] = f);
else
{ printf("error: stack full\n");
clear();
return(0);
}
}
double pop(void)
{
if (sp > 0)
return(val[--sp]);
else
{ printf("error: stack empty\n");
clear();
return(0);
}
}
void clear(void)
{
sp = 0;
}
Figure 2: File STACK.C which contains the functions push(), pop() and
clear().
c-scope User's Manual (JAYAR Systems) Page 7
WHAT C-SCOPE DOES
#include <stdio.h>
#define NUMBER '0'
#define TOOBIG '9'
int getop(char *s, int lim)
{
int i,c;
while ((c = getc(stdin)) == ' ' || c == '\t' ||
c == '\n')
;
if (c != '.' && (c < '0' || c > '9'))
return(c);
s[0] = c;
for (i=1; (c = getc(stdin)) >= '0' && c <= '9'; i++)
if (i < lim)
s[i] = c;
if (c == '.')
{ if (i < lim)
s[i] = c;
for (i++; (c = getc(stdin)) >= '0' && c <= '9'; i++)
if (i < lim)
s[i] = c;
}
if (i < lim)
{ ungetc(c,stdin);
s[i] = '\0';
return(NUMBER);
}
else
{ while (c != '\n' && c != EOF)
c = getc(stdin);
s[lim-1] = '\0';
return(TOOBIG);
}
}
Figure 3: File GETOP.C which contains function getop().
c-scope User's Manual (JAYAR Systems) Page 8
USING C-SCOPE
3 USING C-SCOPE
3.1 Installing C-scope
Installation of c-scope couldn't be easier. The distribution diskette
contains the program CS.EXE and a file called READ.ME that you should
check for any last minute updates that did not make this manual.
The distribution diskette is not copy protected so you can copy the
program to your hard disk--a good location would be the directory
where you keep your utilities. It should be a directory that is
pointed to by your PATH environment variable so that c-scope will be
easy to use.
It is also possible to use c-scope from a floppy diskette too. It is
quite small and doesn't require a lot of memory or disk space so it is
convenient to use even from a diskette.
In any event, don't execute the program from the distribution
diskette. Copy it to another disk and put the distribution diskette
away in a safe place.
3.2 Running C-scope
c-scope may be used to analyze a single source file by typing
CS program.c
where program.c is the name of the source file. More typically it
will be used to analyze a program spread across numerous files. In
this case you just type
CS
c-scope looks in the current directory for a file called SOURCE.DAT.
In this file it expects to find the names of the files comprising the
program--one per line. Full filenames are required, and paths may be
included for source files not in the current directory. For instance,
in the example program in Section 2, SOURCE.DAT contained the
following three lines:
GETOP.C
DCALC.C
STACK.C
As the source files are processed, c-scope writes their names to
stderr, and the analysis is written to stdout which usually appears on
your screen. If you would rather have the reports in a file, use I/O
redirection:
CS > PROGRAM.RPT
c-scope User's Manual (JAYAR Systems) Page 9
USING C-SCOPE
This puts the output in a file called PROGRAM.RPT which can be printed
or edited.
As mentioned above, the -E option will force c-scope to expand all
references to a function, e.g.,
CS -E
3.3 Ignoring Functions
Usually you will find with c-scope that many of the functions
referenced in a program belong to the C library. You may not be
interested in these functions, and may feel their inclusion clutters
the output needlessly. If so you may create a file called IGNORE.DAT,
which c-scope will read if it is present in the current directory.
c-scope expects to find the names of functions, one per line, in
IGNORE.DAT. c-scope will ignore these functions when it generates its
output reports.
For example, if you didn't want the references to the functions
printf, fprintf, strcpy and strcmp to appear in the reports,
IGNORE.DAT would contain
printf
fprintf
strcpy
strcmp
You may also include names of functions which are defined in your
source--not just C library function names.
3.4 Function Declarations
When c-scope encounters a function name internal to another function
it determines if the reference is a declaration or a call by checking
for one of C's reserved storage class or type identifiers. However,
if you have declared a function that returns a DEFINEd or typedef'd
result, c-scope will not recognize it as a declaration and will treat
it as a call. A common example is:
FILE *myopen();
To avoid this problem, you can make sure all internal function
declarations have the extern class, i.e.,
extern FILE *myopen();
or, you can create a file called TYPES.DAT. This file will be read by
c-scope User's Manual (JAYAR Systems) Page 10
USING C-SCOPE
c-scope if present, and will be assumed to consist of type identifiers
that c-scope will add to its list of C keywords. In the above
illustration, TYPES.DAT would contain the line:
FILE
This problem does not occur for function declarations external to a
function.
4 NOTES
c-scope examines each source file in SOURCE.DAT looking for function
names. When it encounters one, it determines if the function name
represents a definition, a call, or an external or internal
declaration.
c-scope uses a knowledge of C program syntax to identify functions and
their context. It is not a compiler though, and some situations may
cause problems. These are discussed in this section.
4.1 Non-standard Function Types
This was discussed in Section 3.4. c-scope doesn't recognize an
internal function declaration as such if it returns a type which is
not one of C's predefined types (int, float, double, char, etc. or
pointers to these) and an implicitly defined storage class. ___
You can remedy this by declaring the function to be of the extern
storage class (which is proper form but often left assumed for
functions), or by including the new type in TYPES.DAT.
Note that all external function declarations are recognized as such,
regardless of the type.
4.2 Preprocessor
The current version of c-scope ignores preprocessor lines. This means
it does not process include files (however, good style dictates that
such files should not contain executable code anyway).
Macros are not expanded, so that functions which are referenced by
macros are not noticed by c-scope. Also, macros which take arguments
are not recognized as such, but are interpreted as external functions.
Conditional compilation directives are ignored.
c-scope User's Manual (JAYAR Systems) Page 11
NOTES
4.3 Function Pointers
c-scope does not deal properly with pointers to functions; for
example, in the following:
main()
{
char *(*fncn)();
char *a(void);
fncn = a;
printf ("this is %s\n",(*fncn)());
}
char name[10];
char *a(void)
{
strcpy(name,"function A");
return(name);
}
c-scope does not recognize (*fncn)() as a function call. Such calls
should be rewritten as fncn() which is permissible under the ANSI
standard, where the syntax for calls to functions and to functions
specified by pointers is allowed to be the same.
Even with this change though, c-scope will only recognize that fncn()
has been called, and not that a() was indirectly called.
APPENDIX A
LICENSE
This appendix contains important license information regarding the use of
c-scope, Version 1.10. This information applies to individual users who
wish to pass copies out to friends and associates.
User Groups, Computer Clubs, Disk Vendors and Distributors, Subscription
Services, Disk-of-the-Month Clubs, etc., should refer to the VENDOR.DOC
file for complete information relating to them.
BBS SYSOPs should refer to the SYSOP.DOC file for complete information
relating to them.
PLEASE! Show your support for Shareware by registering the programs you
actually use. JAYAR Systems depends upon and needs your support. Thank
you!
A.1 TRIAL USE LICENSE:
c-scope is NOT a public domain program. It is Copyright (C) 1992-93 by
JAYAR Systems. All rights reserved.
This software and accompanying documentation are protected by Canadian
Copyright law and also by International Treaty provisions. Any use of this
software in violation of Copyright law or the terms of this limited license
will be prosecuted to the best of our ability. The conditions under which
you may copy this software and documentation are clearly outlined below
under "Distribution Restrictions".
JAYAR Systems hereby grants you a limited license to use this software for
evaluation purposes for a period not to exceed sixty (60) days. If you
intend to continue using this software (and/or it's documentation) after
the sixty (60) day evaluation period, you MUST make a registration payment
to JAYAR Systems.
Using this software after the sixty (60) day evaluation period, without
registering the software is a violation of the terms of this limited
license.
Licensee shall not use, copy, rent, lease, sell, modify, decompile,
LICENSE Page A-2
TRIAL USE LICENSE:
disassemble, otherwise reverse engineer, or transfer the licensed program
except as provided in this agreement. Any such unauthorized use shall
result in immediate and automatic termination of this license.
All rights not expressly granted here are reserved to JAYAR Systems.
For information on registering your copy of c-scope see Appendix C, "How to
Register."
A.2 LIMITED DISTRIBUTION LICENSE:
As the copyright holder for c-scope, JAYAR Systems authorizes distribution
by individuals only in accordance with the following restrictions.
(User Groups, Computer Clubs, Disk Vendors and Distributors, Subscription
Services, Disk-of-the-Month Clubs, etc., should refer to the VENDOR.DOC
file for complete information relating to them.)
(BBS SYSOPs should refer to the SYSOP.DOC file for complete information
relating to them.)
Individuals are hereby granted permission by JAYAR Systems to copy the
c-scope diskette for their own use (for evaluation purposes) or for other
individuals to evaluate, ONLY when the following conditions are met.
The c-scope package is defined as containing all the material listed in the
PACKING.LST text file. If any files listed in the PACKING.LST text file,
or the PACKING.LST file itself, are missing, then the package is not
complete and distribution is forbidden. Please contact us to obtain a
complete package suitable for distribution.
o The c-scope package--including all related program files and
documentation files - CANNOT be modified in any way and must be
distributed as a complete package, without exception. The
PACKING.LST text file contains a list of all files that are part
of the c-scope package.
o No price or other compensation may be charged for the c-scope
package. A distribution cost may be charged for the cost of the
diskette, shipping and handling, as long as the total (per disk)
does not exceed $10.00.
o The c-scope package CANNOT be sold as part of some other inclusive
package. Nor can it be included in any commercial software
packaging offer, without a written agreement from JAYAR Systems.
o The PRINTED User's Guide may not be reproduced in whole or in
part, using any means, without the written permission of JAYAR
Systems. In other words, the disk-based documentation may not be
distributed in PRINTED (hardcopy) form.
LICENSE Page A-3
LIMITED DISTRIBUTION LICENSE:
o The c-scope package cannot be "rented" or "leased" to others.
o Licensee shall not use, copy, rent, lease, sell, modify,
decompile, disassemble, otherwise reverse engineer, or transfer
the licensed program except as provided in this agreement. Any
such unauthorized use shall result in immediate and automatic
termination of this license.
o U.S. Government Information: Use, duplication, or disclosure by
the U.S. Government of the computer software and documentation in
this package shall be subject to the restricted rights applicable
to commercial computer software as set forth in subdivision
(b)(3)(ii) of the Rights in Technical Data and Computer Software
clause at 252.227-7013 (DFARS 52.227-7013). The
Contractor/manufacturer is JAYAR Systems, 253 College Street,
Suite 263, Toronto, Ontario, CANADA M5T 1R5.
All rights not expressly granted here are reserved to JAYAR Systems.
APPENDIX B
DEFINITION OF SHAREWARE
Shareware distribution gives users a chance to try software before buying
it. If you try a Shareware program and continue using it, you are expected
to register. Individual programs differ on details--some request
registration while others require it, some specify a maximum trial period.
With registration, you get anything from the simple right to continue using
the software to an updated program with printed manual.
Copyright laws apply to both Shareware and commercial software, and the
copyright holder retains all rights, with a few specific exceptions as
stated below. Shareware authors are accomplished programmers, just like
commercial authors, and the programs are of comparable quality. (In both
cases, there are good programs and bad ones!) The main difference is in the
method of distribution. The author specifically grants the right to copy
and distribute the software, either to all and sundry or to a specific
group. For example, some authors require written permission before a
commercial disk vendor may copy their Shareware.
Shareware is a distribution method, not a type of software. You should
find software that suits your needs and pocketbook, whether it's commercial
or Shareware. The Shareware system makes fitting your needs easier,
because you can try before you buy. And because the overhead is low,
prices are low also. Shareware has the ultimate money-back guarantee--if
you don't use the product, you don't pay for it.
ASP OMBUDSMAN POLICY
This program is produced by a member of the Association of Shareware
Professionals (ASP). ASP wants to make sure that the shareware principle
works for you. If you are unable to resolve a shareware-related problem
with an ASP member by contacting the member directly, ASP may be able to
help. The ASP Ombudsman can help you resolve a dispute or problem with an
ASP member, but does not provide technical support for members' products.
Please write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI 49442 or
send a CompuServe message via CompuServe Mail to ASP Ombudsman 70007,3536.
APPENDIX C
HOW TO REGISTER
c-scope is a "shareware program" and is provided at no charge to the user
for evaluation. Feel free to share it with your friends, but please do not
give it away altered or as part of another system. The essence of
"user-supported" software is to provide personal computer users with
quality software without high prices, and yet to provide incentive for
programmers to continue to develop new products. If you find this program
useful and find that you are using c-scope and continue to use c-scope
after a reasonable trial period, you must make a registration payment of
US$24.00 (Cdn$28.00) to JAYAR Systems. The registration fee will license
one copy for use on any one computer at any one time.
When you register you receive the following:
o You will get the latest version of c-scope,
o The registered version of c-scope does not display a banner
(registration reminder notice) when it runs,
o You will get a typeset manual,
o The registered version of c-scope generates an additional
report--a set of software complexity metrics. For each function
you see the number of lines, statements, whiles, fors, switches
and ifs. This tells you which functions in the program are the
most complex.
o You will be informed of updates and given a reduced upgrade cost.
You must treat this software just like a book. An example is that this
software may be used by any number of people and may be freely moved from
one computer location to another, so long as there is no possibility of it
being used at one location while it's being used at another. Just as a
book cannot be read by two different persons at the same time.
Commercial users of c-scope must register and pay for their copies of
c-scope within 30 days of first use or their license is withdrawn. Your
registration fee purchases a single user license. If you need to use
multiple copies, significant savings can be had by purchasing a site
license rather than registering multiple individual copies. Even a
HOW TO REGISTER Page C-2
two-user site license saves you money. See the file SITELICE.DOC for
details.
Anyone distributing c-scope for any kind of remuneration must first contact
JAYAR Systems at the address given in DESCRIBE.DOC for authorization. This
authorization is automatically granted to distributors and vendors who are
members of the Association of Shareware Professionals (ASP). See files
VENDOR.DOC and SYSOP.DOC for details.
You are encouraged to pass a copy of c-scope along to your friends for
evaluation. Please encourage them to register their copy if they find that
they can use it. All registered users will receive a copy of the latest
version of the c-scope system.
Send in the following form to register your copy of c-scope:
HOW TO REGISTER Page C-3
REGISTRATION FORM
Send to: JAYAR Systems GST Registration Number:
253 College Street R124607193
Suite 263
Toronto, Ontario
Canada M5T 1R5
Name ___________________________________________
Address ___________________________________________
___________________________________________
___________________________________________
___________________________________________
Telephone __________________________
+--------+------------------------+------------+------------+
|Quantity| Product | Each | Total |
+--------+------------------------+------------+------------+
| | | US$24.00 | |
| | c-scope | or | |
| | | Cdn$28.00 | |
+--------+------------------------+------------+------------+
| Canadian residents add 7% GST | |
+----------------------------------------------+------------+
| Ontario residents add 8% PST | |
+----------------------------------------------+------------+
| Outside Canada/U.S.A., add shpg/hndlg | $5.00 |
+----------------------------------------------+------------+
| TOTAL | |
+----------------------------------------------+------------+
Please remit by cheque (we will accept cheques in your local currency at
the appropriate rate of exchange) or by money order. We will accept your
company's purchase order. We also accept payment by Visa or Mastercard.
P.O. Number ______________________________________ (P.O. to follow)
+------------------------------------------------------------------+
| Note - Fill out the following ONLY if you are making payment by |
| credit card. You may also call (416) 751-3284 for credit |
| card registrations. |
| |
| Master Card [ ] Visa [ ] Card Number ______ ______ _____ ______ |
| |
| Name on the Card (print) _______________________________________ |
| |
| Expires ____/____ |
| Signature ___________________________________ |
| |
+------------------------------------------------------------------+
