Media Depot 5

home *** CD-ROM | disk | FTP | other *** search

/ Media Depot 5 / mediadepotvolume51993.iso / FILES / 13 / CSCOP122.ZIP / CSCOPE.DOC < prev next >

Wrap

Text File | 1996-05-01 | 42.4 KB | 1,559 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 e-mail: jrsys@io.org World Wid Web: http://www.io.org/~jrsys 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 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) 1991-96 JAYAR Systems All Rights Reserved CONTENTS 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 1 2 What c-scope does . . . . . . . . . . . . . . . . . . . . . . . 2 3 Using c-scope . . . . . . . . . . . . . . . . . . . . . . . . . 9 1 Installing c-scope . . . . . . . . . . . . . . . . . . . . . 9 2 Running c-scope . . . . . . . . . . . . . . . . . . . . . . 9 1 Circular Function References . . . . . . . . . . . . . 10 3 Ignoring functions . . . . . . . . . . . . . . . . . . . . . 10 4 Function declarations . . . . . . . . . . . . . . . . . . . 11 4 Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 1 Non-standard function types . . . . . . . . . . . . . . . . 12 2 Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . 12 3 Function pointers . . . . . . . . . . . . . . . . . . . . . 12 A Error messages . . . . . . . . . . . . . . . . . . . . . . . . 14 B License . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 C Trial Use License: . . . . . . . . . . . . . . . . . . . . . . 17 D Limited Distribution License: . . . . . . . . . . . . . . . . . 18 E Definition of Shareware . . . . . . . . . . . . . . . . . . . . 20 F How to Register . . . . . . . . . . . . . . . . . . . . . . . . 21 iii 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 and provides an inverse function reference ("called by") report. 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. 1 What c-scope does 2 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: o 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 pop STACK.C 22 push STACK.C 10 o 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 What c-scope does 3 clear o A Function Calls 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 CALLS Function Calls function -------------------- -------------- getop getc ungetc main atof clear getop pop printf push push clear printf pop clear printf clear void o 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 What c-scope does 4 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: SOFTWARE COMPLEXITY METRICS Function Lines Stmts whl for swc if -------------------- ------ ------ ---- ---- ---- ----- clear 4 1 0 0 0 0 getop 35 16 2 2 0 6 main 35 21 1 0 1 1 pop 10 4 0 0 0 1 push 10 4 0 0 0 1 In addition, the registered version of c-scope generates a Functions Called report. Every function that is called by one of the functions defined in your program (i.e., whose source code is available), is listed, along with all the defined functions that call it. This is convenient for locating where a given function is referenced. This report also includes names of functions that are unreferenced--that is, those that are not called by any other function. FUNCTIONS CALLED Function Called by function -------------------- ------------------ atof [E] main What c-scope does 5 clear main push pop getc [E] getop getop main pop main printf [E] main push pop push main ungetc [E] getop See Appendix C for information on registering your version of c-scope. What c-scope does 6 #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(). What c-scope does 7 #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(). What c-scope does 8 #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(). Using c-scope 9 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 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 Using c-scope 10 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 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.2.1 Circular Function References If your program is constructed in such a way that function calls form a circuit, e.g., function a calls function b, which calls function c, which calls function a again, then expanding all function references with the -e option could potentially cause an infinite expansion. c-scope will detect such circuits and print [C] beside the function name in the static calling tree where it was detected. If the -e option was specified, c-scope will stop expansion at that point. 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. Using c-scope 11 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 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. Notes 12 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. 4.3 Function pointers c-scope does not deal properly with pointers to functions; for example, in the following: main() { Notes 13 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. Error messages 14 A Error messages This section describes the error messages that c-scope may produce and offers suggestions on how to remedy the problems they indicate. ____ Invalid option -opt A program option was specified that is not one of -e or -c. ________ Unable to open filename A source file was specified on the command line or in the file SOURCE.DAT that cannot be opened--check for spelling mistakes, etc. Error--no main function There is no main function in any of the source files; a static calling tree will not be produced. Error - insufficient memory to proceed c-scope was unable to allocate any more memory for its internal tables. The more files, functions and function references your source files contain, the more memory will be required. It is unlikely this error will ever occur, but if it does, try to free up some memory in your system and try again. ___ _ _____ Error--token too long (limit = nnn) line n: token A token was found in the source file that exceeds the internal limit. Most likely due to a too-long literal character string--may result from an unmatched ". ___ Error - too many function references (limit = nnn) The source files in SOURCE.DAT collectively call too many functions. Contact JAYAR Systems. ___ Error - too many source functions (limit = nnn) The source files in SOURCE.DAT collectively contain too many functions. Contact JAYAR Systems. Unable to open source.dat and no arguments given You need to supply the name of a source file on the command line or have a file called SOURCE.DAT containing source file names in the current working directory. ___ Too many source files (limit = nnn) Too many source files were specified in SOURCE.DAT. Contact JAYAR Systems. ___ Too many types (limit = nnn) You have specified too many user types in TYPES.DAT. Contact JAYAR Systems. Error messages 15 ___ Too many functions in ignore list (limit = nnn) You have specified too many function names to ignore in IGNORE.DAT. Contact JAYAR Systems. License 16 B License This appendix contains important license information regarding the use of c-scope, Version 1.22. 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! Trial Use License: 17 C Trial Use License: c-scope is NOT a public domain program. It is Copyright (C) 1991-96 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, 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 F, "How to Register." Limited Distribution License: 18 D 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. 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 Limited Distribution License: 19 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. Definition of Shareware 20 E 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. How to Register 21 F 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 two additional reports--a set of software complexity metrics and an inverse function reference or "called by" report. In the first the number of lines, statements, whiles, fors, switches and ifs are reported for each function. In the second, the functions that call each function in your program are listed; functions that are not called by any other function are also listed. 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 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 How to Register 22 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. Note that c-scope is available for UNIX as well as for the DOS operating system. If you are ordering the DOS version, you may order a single-user UNIX version at the same time for only half price. If you want to order the UNIX version alone, or if it will be used in a multiuser or networked environment you must use the site license application form for ordering (see file SITELICE.DOC). The UNIX version is shipped as obfuscated C source code and will compile on most systems. Give us a call if you have any questions about this option. Send in the following form to register your copy of c-scope: 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 | | +--------+------------------------+------------+------------+ | |single user UNIX version|1/2 of above| | +--------+------------------------+------------+------------+ | Canadian residents add 7% GST | | +----------------------------------------------+------------+ | Ontario residents add 8% PST | | +----------------------------------------------+------------+ | Outside Canada/U.S.A., add shpg/hndlg | $5.00 | +----------------------------------------------+------------+ | TOTAL | | +----------------------------------------------+------------+ DISK FORMAT (check one): 5-1/4"DD [ ] 5-1/4"HD [ ] 3-1/2"HD [ ] 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-5678 for credit | | card registrations. | | | | Master Card [ ] Visa [ ] Card Number ______ ______ _____ ______ | | | | Name on the Card (print) _______________________________________ | | | | Expires ____/____ | | Signature ___________________________________ | | | +------------------------------------------------------------------+