C/C++ Interactive Guide

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

/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource1 / xref / xref31.doc < prev next >

Wrap

Text File | 1993-12-27 | 32.8 KB | 1,231 lines

Xref The C language cross reference utility. (c) 1991-1994 by David Archibald. _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER Xref - C language cross-reference utility. v3.1 Table of Contents Introduction: What 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 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 -p command.....................311 * The -o command.................... 312 * The -m command.................... 313 Command line examples.................... 314 *The reserved word files: RES_WORD.TXT and WIN_RES.TXT.............................. 401 What Xref ignores........................ 501 Technical support........................ 601 (Entries that begin with an "*" have changed since the last version.) Page 1 of 19 Xref - C language cross-reference utility. v3.1 101 What it does. 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 in which it originates. - Line of origin. - 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. xref 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. Xref is not C++ compatible at this time, but it will ignore C++ keywords and comments (i.e. "//"). Page 2 of 19 Xref - C language cross-reference utility. v3.1 102 Registration and licensing information. Xref is a Shareware program, and copies of this program and it's documentation may be freely distributed. Xref and this document are copyrighted and may not be modified in any manner. You are licensed to use Xref for a thirty (30) day evaluation period. Unregistered use of 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 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 ref, 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 19 Xref - C language cross-reference utility. v3.1 Invoice/Registration Form For Xref Individual Registration fee $ 24.95 (Prices guaranteed through December 1994) Name:________________________________________________ Company:________________________________________________ Address:________________________________________________ City:________________________________________________ State, Zip:________________________________________________ E-mail address:___________________________________________ Telephone number:___________________________________________ 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. 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 19 Xref - C language cross-reference utility. v3.1 103 System requirements. Config.sys file: 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 Xref, but some data remains in memory (mostly global variables and function names). If 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), try running Xref without this command. 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 19 Xref - C language cross-reference utility. v3.1 201 Global variables and constants. 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 19 Xref - C language cross-reference utility. v3.1 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 19 Xref - C language cross-reference utility. v3.1 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 an 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 19 Xref - C language cross-reference utility. v3.1 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 19 Xref - C language cross-reference utility. v3.1 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 19 Xref - C language cross-reference utility. v3.1 301 The command line syntax. xref [-x -t -i -p path;path... -n -s -w -l -o -m -f \...] sourcefilespec1 [sourcefilespec2...] --------------------------------------------------------------- Note: A space must separate each command and source file name. Also, Xref is not case sensitive, so commands can be entered as upper or lower case letters. --------------------------------------------------------------- 302 Module names. 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 19 Xref - C language cross-reference utility. v3.1 307 The -l command. The 'l' command gives you an easy way to add identifiers from your cross-referenced modules to the RES_WORD.TXT file (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--function names, global variables, and defines--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 "<>" (i.e. #include <stdio.h>). 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. 309 The -n command. By default, Xref cross-references include files enclosed in double quotes (i.e. #include "mydef.h"), but you can disable this with the '-n' command. Like the "-i" command, Xref keeps track of the file names so that they are cross-referenced only once. --------------------------------------------------------------- Note: If you use identifiers in place of file names in your include statements, then Xref can not cross-reference them. For example: #define F_NAME "mydef.h" #include F_NAME /* won't cross-reference! */ --------------------------------------------------------------- Page 12 of 19 Xref - C language cross-reference utility. v3.1 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 -p command. Xref searches the file paths for source and header files in the following order: o The path entered with the file names or included with the header files (i.e. "c:\text\myprog.c" or "#include <c:\headers\myheader.h>"). o The default directory of the default drive. o The root directory of the default drive. o The paths entered with the '-p' command. The '-p' command has the following syntax: -p c:\dos\;c:\prg\text\ Each path name must be separate by a ";" (no spaces). You can specify up to 20 alternate path names. Page 13 of 19 Xref - C language cross-reference utility. v3.1 312 The -o command. By default, 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. 313 The -m command. This command is useful when you are cross-referencing Windows programs. When the `-m' command is used, Xref loads the reserved word file WIN_RES.TXT in addition to RES_WORD.TXT. Like RES_WORD.TXT, this file contains reserved and special words, but these are distinct to Windows programs. Xref will ignore these words. The `-m' command also changes the output in the function tree section. Instead of starting the tree output with "main," it will begin with "WinMain" (there being no "main" in Windows' programs). Xref also keeps track of all WNDCLASS assignments to xxx.lpfnWndProc's, and treats the procedures that follow as if they were also "main"s. For example: wnd.lpfnWndProc = WinProc; "WinProc" would begin a function tree heading the same as if it were "main." Xref will do this--treat each as a "main," and begin a new tree heading--for all lpfnWndProc assignments that appear in the module(s). Page 14 of 19 Xref - C language cross-reference utility. v3.1 314 Command line examples. xref -i -p 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. o Also look for the C modules and include files in 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". xref -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: running Xref with an empty command line (i.e. xref <CR>) you will get a short description of the command switches. --------------------------------------------------------------- Page 15 of 19 Xref - C language cross-reference utility. v3.1 401 The reserved word files: RES_WORD.TXT and WIN_RES.TXT If Xref included references to C's function calls (printf, etc.) and reserved words, the output would soon become pretty long and messy. To prevent this, Xref reads two files (RES_WORD.TXT and WIN_RES.TXT), that contain a list of words it will ignore when cross-referencing the C modules. RES_WORD.TXT and WIN_RES.TXT are ASCII files 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). Xref also accepts the asterisk as a wildcard character in the entries. The asterisk is used the same way with the entries, as it is used with DOS file names. Using the asterisk in this manner, you can specify entire groups of words to ignored. For example with the entries: foo* global_* any word that begins with "foo" or "global_" is ignored. Page 16 of 19 Xref - C language cross-reference utility. v3.1 The RES_WORD.TXT file included with 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++. WIN_RES.TXT contains the reserved words from WINDOWS.H and WINDOWSX.H. RES_WORD.TXT is always loaded, but the loading of WIN_RES.TXT is optional (see section 313).(The Windows' entries use about 30K of program memory, so to save memory when not cross-referencing Windows programs they were split in to their own separate file. Another added benefit is that execution time is improved by reducing the number of reserved words through which Xref has to search.) The RES_WORD.TXT and WIN_RES.TXT files must be in the same directory as Xref. --------------------------------------------------------------- Note: with the unregistered version of Xref, the RES_WORD.TXT file must be on a non-write protected disk. Xref modifies this file and it will not run if the file is write protected. --------------------------------------------------------------- Page 17 of 19 Xref - C language cross-reference utility. v3.1 501 What Xref ignores. 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 and WIN_RES.TXT files (when loaded). Page 18 of 19 Xref - C language cross-reference utility. v3.1 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 3717 Aldon Lane Flint, MI 48506 U.S.A. By telephone: 810-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 questions please do not hesitate to contact me. The quickest response will be had in the following order: Telephone, e-mail (I check for mail at least once a week, often daily), 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 19 of 19