The Programmer Disk

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

/ The Programmer Disk / The Programmer Disk (Microforum).iso / xpro / vc / pro14 / cxref3a.doc < prev next >

Wrap

Text File | 1993-10-16 | 31.2 KB | 1,190 lines

C xref The C language cross reference utility. (c) 1992-1993 by David Archibald. _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER C xref - C language cross-reference utility. v3.0a Table of Contents Introduction: What C xref does.....................101 Registration and licensing information............... 102 System requirements................. 103 Program output: Global variables and constants...... 201 Summary list of functions........... 202 Verbose list of functions........... 203 Function tree....................... 204 Running C xref: The command line syntax............. 301 The module names.................... 302 The -x command...................... 303 The -t command...................... 304 The -s command...................... 305 The -w command...................... 306 The -l command...................... 307 The -i command...................... 308 The -n command...................... 309 The -f command...................... 310 The -o command...................... 311 Command line examples.................... 312 The reserved word file: RES_WORD.TXT..... 401 What C xref ignores...................... 501 Technical support........................ 601 Page 1 of 17 C xref - C language cross-reference utility. v3.0a 101 What it does. C xref is a cross-reference utility program for the C programming language. It will read any number of your C text modules and send the following to standard output: o A list of the module's global variables and constants, along with the line numbers they appear on. o A summary listing of the module's functions. o A verbose list of all the module's functions that includes: - The name of the module it originates in. - Line of origin. - On what line numbers the function is referenced on, and by which modules. - What functions, and the modules they are in, it references. - What local and global variables appear in the function. o A tree that displays all of the functions calling hierarchy. --------------------------------------------------------------- Note: To send the output to your printer or to a file, use DOS redirection (i.e. cxref filename >LPT1, would send output to your printer). --------------------------------------------------------------- A cross-reference listing can be helpful for: o Debugging. For example, it can tell you: - Which functions reference another. - What global variables are used in a function. - What functions use a certain variable. o Documenting your programs. It gives you a complete listing of your variables and functions, and where they are used. o Program maintenance and modification. A cross- reference listing makes following a program's flow easier, and will show which parts of a program will be affected by, for example, changing a "define" statement. This means less time wasted deciphering a program, and fewer bugs. C xref is not C++ compatible at this time, but it will ignore C++ keywords and comments (i.e. "//"). Page 2 of 17 C xref - C language cross-reference utility. v3.0a 102 Registration and licensing information. C xref is a Shareware program, and copies of this program and it's documentation may be freely distributed. C xref and this document are copyrighted and may not be modified in any manner. You are licensed to use C xref for a thirty (30) day evaluation period. Unregistered use of C xref after this trial period is a violation of federal copyright laws. Individual copies may be licensed for $24.95 (see the REGISTER.DOC file). You may access C xref through a network, provided that site licenses have been obtained for all workstations that will be using the software (see the SITELICE.DOC file). After registering you will be sent the latest version of C xref, and, as they become available, future updates. 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. Page 3 of 17 C xref - C language cross-reference utility. v3.0a Invoice/Registration Form For C xref Individual Registration fee $ 24.95 (Prices guaranteed through December 1994) Name:________________________________________________ Company:________________________________________________ Address:________________________________________________ City:________________________________________________ State, Zip:________________________________________________ Email address:___________________________________________ Disk size: 5 1/4:_____ 3 1/2:_____ Either size:_____ Ordering by check: Send this form and a check to: DA Software 3717 Aldon Lane Flint, MI 48506 Ordering with CompuServe's Software Registration Service: Enter GO SWREG at the ! prompt and follow the menus. C xref's registration ID is 1394. Ordering by credit card: Call or send your Visa/MasterCard order to (Please refer to product number: V328): Software Excitement! 6475 Crater Lake Hwy. Central Point, OR 97502 (800) 444-5457 or (503)826-8082 CIS Email: 71203.1301 Card number:_______________________ Exp. date:_________ Signature:_________________________________ Page 4 of 17 C xref - C language cross-reference utility. v3.0a 103 System requirements. Config.sys file: C xref can use up to 60 file handles. When cross- referencing "include" files (see the "-i" command, section 308) the recommended minimum number of available handles is 20. You can change the number of available handles by modifying the "file" statement in your config.sys file. For example, to make 20 file handles available, use EDIT, or another ASCII text editor, and change the "file" statement to read "file=20". Memory limits: There is no minimum memory, but the number of modules you can cross-reference is dependent on the amount of memory you have. (Expanded and extended memory use are not supported at this time.) The majority of the program data is stored in a temporary file created by C xref, but some data remains in memory (mostly global variables and function names). If C xref runs out of memory it will output an error message to this effect, and terminate. If you do run out of memory, and you are using the "-i" command (which cross-references the standard header files along with your modules), then try it without this command. The standard header files have a large number of global defines and variables which are not stored in the temporary file, but remain in memory. Page 5 of 17 C xref - C language cross-reference utility. v3.0a 201 Global variables and constants. C xref assumes that anything declared outside a function's boundaries (from the function name to the function's closing brace) is a global variable or constant. The global variable and constant cross-reference has the following format: variable name [type] {module name} what line numbers the variable appears on in this the module. Sample output: char_pnt [char] {example.c } 1 {explfile.c } 10 11 16 28 35 42 cnt [int] {example.c } 4 11 32 {explfile.c } 8 14 --------------------------------------------------------------- Note: a variable, constant, or a function is tagged as [unknown] when it's data type is not known. --------------------------------------------------------------- 202 Summary list of functions. The summary list has the following format: {module name} : line-of-origin : function name() [type] --------------------------------------------------------------- Note: a line-of-origin of [NONE] indicates that the function was reference, but it did not appear any of the modules cross- referenced. --------------------------------------------------------------- Sample output: {example.c } : [NONE] : getch() [int] {explfile.c } : 32 : is_it_a_comma() [int] {example.c } : 7 : main() [void] {explfile.c } : 39 : not_comma() [char] {example.c } : 25 : open_file() [FILE] Page 6 of 17 C xref - C language cross-reference utility. v3.0a 203 Verbose list of functions. The verbose list of functions has the following format: --------------------------------------------------------------- Note: only those functions that have a line-of-origin are listed. --------------------------------------------------------------- ================================================================= function name [type] : {module name} : line-of-origin ================================================================= USERS: {module name} what line numbers in this module reference this function. ----------------------------------------------------------------- CALLS: {module name} function name() {module} function() ----------------------------------------------------------------- LOCAL VARIABLES: variable name [type] what line numbers in this function it appears on. ----------------------------------------------------------------- GLOBAL VARIABLES: variable name [type] what line numbers in this function it appears on. USERS are a list of the line numbers in a module that reference this function. CALLS are other functions that this function references. --------------------------------------------------------------- Note: A function name is truncated if it is over 20 characters long. When this occurs, the truncated name will be followed by an ellipsis of three periods. [i.e. {filename.c }Very_very_long_na...()] --------------------------------------------------------------- Page 7 of 17 C xref - C language cross-reference utility. v3.0a LOCAL VARIABLES are any variable or constant that falls between a function's name and it's closing brace. --------------------------------------------------------------- Note: As with your C compiler, when a local and global variable have the same name, the global variable is hidden, and all line numbers that it appears on are assigned to the local variable. Also, if it is declared with a unknown specifier type (for example, a typedef from a header file that was not cross- referenced) it will be processed as a global variable. --------------------------------------------------------------- GLOBAL VARIABLES are a list of any global variables or constants that appear in this function. (This section is suppressed when a function does not use any global variables.) Page 8 of 17 C xref - C language cross-reference utility. v3.0a Sample verbose output: ================================================================= main() [void] : {example.c} : 7 ================================================================= USERS: [NONE] ----------------------------------------------------------------- CALLS: {example.c } close_file() {explfile.c } not_comma() {example.c } get_input() {example.c } open_file() ----------------------------------------------------------------- LOCAL VARIABLES: argc [int] 7 10 argv [char] 7 9 column [int] 13 19 file_name [char] 12 17 file_pnt [FILE] 14 18 21 row [int] 13 19 ----------------------------------------------------------------- GLOBAL VARIABLES: cnt [int] 11 ================================================================= not_comma() [char] : {explfile.c} : 39 ================================================================= USERS: {explfile.c } 13 ----------------------------------------------------------------- CALLS: [NONE] ----------------------------------------------------------------- LOCAL VARIABLES: [NONE] ----------------------------------------------------------------- GLOBAL VARIABLES: char_pnt [char] 42 Page 9 of 17 C xref - C language cross-reference utility. v3.0a 204 Function tree. The function tree option generates a tree representation of all of the module's function calls (or more simply stated: who's calling who). The following is a sample tree for two modules: example.c :main example.c :|_close_file example.c :|_output_char example.c :|_get_input explfile.c :| |_not_comma explfile.c :| |_is_it_a_comma explfile.c :| |_is_it_a_comma* :| example.c :|_open_file --------------------------------------------------------------- Note: An '*' following a function name indicates that this is a recursive function call. --------------------------------------------------------------- Page 10 of 17 C xref - C language cross-reference utility. v3.0a 301 The command line syntax. cxref [-x -t -i[p path;path...] -n -s -w -l] sourcefilespec1 [sourcefilespec2...] --------------------------------------------------------------- Note: A space must separate each command and source file name. Also, C xref is not case sensitive, so commands can be entered as upper or lower case letters. --------------------------------------------------------------- 302 Module names. C xref will accept any legal DOS file name. Standard DOS pattern checking is supported ('?' and '*'). --------------------------------------------------------------- Note: Also, your text modules must be free of syntax errors, otherwise the resulting output can be unpredictable. --------------------------------------------------------------- 303 The -x command. The 'x' command suppresses output of the function tree. 304 The -t command. The 't' command suppresses output of everything except the function tree. 305 The -s command. The 's' command suppresses all output except the function summary. 306 The -w command. The default line width for output is 80 characters, but with the 'w' command you can set the line width to 132 characters (useful if you have a wide carriage printer). Page 11 of 17 C xref - C language cross-reference utility. v3.0a 307 The -l command. The 'l' command gives you an easy way to add identifiers (function names, and global variables and defines) from your cross-referenced modules to the RES_WORD.TXT file (C xref ignores anything in a module that appears in this file. See section 401). The cross-reference listing is suppressed when this command is entered. The identifiers are displayed one at a time, and you can choose one of three options: o Press 'a' to add the item to the RES_WORD.TXT file. o Press 'q' to quit and stop adding to the file. o Press any other key to skip the item. 308 The -i command. The 'i' command lets you cross-reference the "include" files in your modules. This command only cross-references include files enclosed in "<>". C xref keeps track of the include file names so that each file is cross-referenced only once. It will cross-reference nested include files up to 60 files deep, or to the limit of file handles in your config.sys file. C xref always looks in the current directory (i.e. the directory in which the current module is located) for include files, but you can enter alternate path names. For example: -ip c:\dos\;c:\prg\text\ Each path name must be separate by a ";" (no spaces) and the -i command must be followed by a "p" (if you are not entering an alternate path name, then do not include the "p"). Page 12 of 17 C xref - C language cross-reference utility. v3.0a 309 The -n command. By default, C xref cross-references include files enclosed in double quotes (i.e. #include "mydef.h"), but you can disable this with the '-n' command. C xref searches the current directory for the include file, but if it is not found, and the '-i' command was entered, it will search any alternate path names that follow it. --------------------------------------------------------------- Note: If you use identifiers in place of file names in your include statements, then C xref can not cross-reference them. For example: #define F_NAME "mydef.h" #include F_NAME /* won't cross-reference! */ --------------------------------------------------------------- 310 The -f command. This command allows you to format the verbose function output with linefeeds and formfeeds. The format line uses C's standard newline and formfeed commands. For example: -f \n\n\n or -f \f The first example would output three newlines between each function's cross-reference listing. The second example would output a formfeed after each function, placing each function's cross-reference listing on a separate page. The only formatting commands that are recognized are the newline and formfeed commands, and there must be a space between the '-f' command and the format string. No spaces may appear in the formatting string. 311 The -o command. By default, C xref does not output a listing in the verbose section for functions that do not have a line-of-origin. The '-o' command will cause all functions to be listed in the verbose section, whether they have a line-of-origin or not. Page 13 of 17 C xref - C language cross-reference utility. v3.0a 312 Command line examples. cxref -ip c:\dos\;c:\prg\text\ -w mod??.c This command line will: o Output a complete cross-reference listing. o Cross-reference all include files,and will look for them in the module's directory, and the "c:\dos\" and "c:\prg\text\" directories. o Output in 132 column width. o Cross-reference any file that matches the file name pattern "mod??.c". cxref -t -l -f \f c:\prg\*.c a:\text\bigprg?.* This command line will: o Only output a function tree. o Output the global and function identifiers and give you the opportunity to add them to the RES_WORD.TXT file. o Output a formfeed after each function in the verbose listing. o Cross-reference all files in the paths "c:\prg\*.c" and "a:\text\bigprg?.*" that match the name patterns "*.c" and "bigprg?.*". --------------------------------------------------------------- Note: if you run C xref with an empty command line (i.e. cxref <CR>) you will get a short description of the command switches. --------------------------------------------------------------- Page 14 of 17 C xref - C language cross-reference utility. v3.0a 401 The reserved word file: RES_WORD.TXT If C xref included references to C function calls (printf, etc.) or it's reserved words, the output would soon become pretty long and messy. To prevent this, C xref reads RES_WORD.TXT when executed, which contains a list of words it will ignore when cross- referencing the C modules. RES_WORD.TXT is an ASCII file that you can customize with the following limitations: o Each entry must be separated by a newline. o line length is limited to 80 characters. Comments can be added or an entry "rem"ed out by inserting an "*" in the first column (the '*' MUST be in the first column). Asterisks can also be used with the entries as a wildcard character in the same way they are used in DOS filenames. This lets you specify entire groups of words to be ignored. For example with the entries: foo* global_* any word that begins with "foo" or "global_" is ignored. The RES_WORD.TXT file included with C xref has all of C's and C++'s reserved words and function calls. It also includes the function calls and defines from Borland C++, and WINDOWS.H and WINDOWSX.H. (The Windows' entries use about 30K of program memory, so if you do not program in Windows, you may want to delete them and make that memory available for program execution.) The RES_WORD.TXT file must be in the same directory as C xref. --------------------------------------------------------------- Note: with the unregistered version of C xref, the RES_WORD.TXT file must be on a non-write protected disk. C xref modifies this file and it will not run if the file is write protected. --------------------------------------------------------------- Page 15 of 17 C xref - C language cross-reference utility. v3.0a 501 What C xref ignores. C xref ignores: o Anything enclosed by single or double quotes. o All comments (both "/*...*/" and "//"). o Anything that matches the contents of the RES_WORD.TXT file. Page 16 of 17 C xref - C language cross-reference utility. v3.0a 601 Technical support. Telephone support will be provided to registered users for three months following registration. Unlimited support is available by e-mail and US mail. Bugs will be fixed for free for one year following registration, if possible. If not, a full refund will be offered. A written description of the bug, and a copy of your program file are essential to enable me to duplicate the problem. Support will be provided to non-registered users and users beyond the free support period on a time and materials basis. Question, problems or bug reports may be addressed to: By US mail: David Archibald DA Software P.O. Box xxxx Flint, MI 48506 U.S.A. By telephone: 313-736-0239 Monday-Friday 5:00PM-9:00PM Saturday and Sunday 10:00AM-5:00PM. By e-mail: CompuServe: 71573,616 Internet: 71573.616@compuserve.com If you have any question please do not hesitate to ask them. The quickest response will be had in the following order: Telephone, e-mail (I check for mail at least once a week), and US mail. If you contact me by e-mail or US mail, please include a telephone number where you can be reached in case I need further information. Page 17 of 17