DP Tool Club 18

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

/ DP Tool Club 18 / CD_ASCQ_18_111294_W.iso / dos / prg / c / xref32 / xref32.txt < prev

Wrap

Text File | 1994-09-01 | 41KB | 1,164 lines

Xref The C language cross reference utility. (c) 1991-1994 by David Archibald. Users Manual Version 3.2 _______ ____|__ | (R) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER Xref - C language cross-reference utility. v3.2 Table of Contents Introduction: What Xref does.......................101 Registration benefits................102 Registration and licensing information............... 103 System requirements................. 104 Installing Xref..................... 105 Program output: Global variables and constants...... 201 Summary list of functions........... 202 Verbose list of functions........... 203 Function tree....................... 204 Running Xref: Command line syntax................. 301 Module names........................ 302 x command. Suppress function tree... 303 t command. Suppress all but function tree..................... 304 s command. Suppress all but function summary.................. 305 w command. Output line length....... 306 l command. Add identifiers.......... 307 i command. Xref <...> include files. 308 n command. Do not xref "..." include files..................... 309 f command. Format verbose output.... 310 p command. Source and header search paths.......................311 o command. Functions without line-of-origins................... 312 m command. Xrefing Windows programs. 313 c command. Command file............. 314 d and e commands. Section delimit characters.........................315 Command line examples.................... 316 The reserved word files: RES_WORD.TXT and WIN_RES.TXT.............................. 401 What Xref ignores........................ 501 Technical support........................ 601 Page 1 of 18 Xref - C language cross-reference utility. v3.2 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 18 Xref - C language cross-reference utility. v3.2 102 Registration benefits. Registered users will receive: o The latest version of Xref (with the registration reminders removed). o The DOS memory extender version of Xref that can access up to 4 gigabytes of memory. o The printed manual. o A free Source file listing program. This Xref compatible program lists your files with line numbers, etc. o Free telephone support for three months. o Future updates, as they become available. 103 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 $34.95 (see the REGISTER.TXT 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.TXT file). 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 18 Xref - C language cross-reference utility. v3.2 Invoice/Registration Form For Xref Individual Registration fee $ 34.95 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. Credit card orders only: You can order with MC, Visa, Amex, or Discover from Public (software) Library by calling 800-2424-PsL or 713-524-6394 or by FAX to 713-524-6398 or by CIS Email to 71355,470. Please refer to product number: 11372. You can also mail credit card orders to PsL at P.O.Box 35705, Houston, TX 77235-5705. THE ABOVE NUMBERS ARE FOR ORDERS ONLY. Any questions about the status of the shipment of the order, refunds, registration options, product details, technical support, volume discounts, dealer pricing, site licenses, etc, must be directed to DA Software 3717 Aldon Lane Flint, MI 48506. To insure that you get the latest version, PsL will notify us the day of your order and we will ship the product directly to you. Page 4 of 18 Xref - C language cross-reference utility. v3.2 104 System requirements. Config.sys file: Xref can use up to 60 file handles. The recommended minimum number of handles is 20. You can change the number of available handles by modifying the "files" statement in your config.sys file yourself, or allow the Xref's install program do it for you. To make the change yourself, use EDIT, or another ASCII text editor, and change the "files" statement to read "files=xx" ("xx" being the number of file handles). 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. (The registered version of Xref uses a DOS memory extender that can access up to four gigibytes of memory [a 80386 or higher is required]. The unregistered version does not include the DOS memory extender and can only use up to 640k of memory.) The majority of 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. (The registered version of Xref was tested by cross-referencing over 425 modules, which totaled 3.5 megabytes of C code, on a computer system with 8 megabytes of memory. No out-of-memory error was encountered.) 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, and remain in memory. 105 Installing Xref. To install Xref, follow these steps: 1.At the DOS prompt, change to the drive on which you have the Xref package. 2.Type install and press ENTER. 3.Follow the online instructions to complete the installation. For a description of the installed files, see PACKING.LST. Page 5 of 18 Xref - C language cross-reference utility. v3.2 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 section 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 An "*" appearing before a line number indicates that the variable is to the left of an assignment operator (i.e. "=" or "\=", etc.) on that line. --------------------------------------------------------------- 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 section 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 in 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 18 Xref - C language cross-reference utility. v3.2 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's length exceeds 20 characters. When this occurs, the truncated name will be followed by an ellipsis of three periods. [i.e. {filename.c }Very_very_long_na...()] --------------------------------------------------------------- LOCAL VARIABLES are any variable or constant that falls between a function's name and it's closing brace. Page 7 of 18 Xref - C language cross-reference utility. v3.2 --------------------------------------------------------------- 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 the local variable 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 18 Xref - C language cross-reference utility. v3.2 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 column [int] *13 19 file_name [char] 12 *17 file_pnt [FILE] *14 18 21 ----------------------------------------------------------------- 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 --------------------------------------------------------------- Note: As with the global variables, an "*" appearing before a line number indicates that the variable is to the left of an assignment operator (i.e. "=" or "\=", etc.) on that line. --------------------------------------------------------------- Page 9 of 18 Xref - C language cross-reference utility. v3.2 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 18 Xref - C language cross-reference utility. v3.2 301 The command line syntax. xref [-c filename -d -e -f \... -i -l -m -n -o -p path;path... -s -t -w -x] 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 "*"). The file names must be the last entries on the command line. --------------------------------------------------------------- Note: Also, your text modules must be free of syntax errors, otherwise the resulting output can be unpredictable. --------------------------------------------------------------- 303 x command. Suppress function tree. The "x" command suppresses output of the function tree. 304 t command. Suppress all but function tree. The "t" command suppresses output of everything except the function tree. 305 s command. Suppress all but function summary. The "s" command suppresses all output except the function summary. 306 w command. Output line length. 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 18 Xref - C language cross-reference utility. v3.2 307 l command. Add identifiers. 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 i command. Xref <...> include files. By default, Xref does not cross-reference the include files enclosed by "<>"s (i.e. #include <stdio.h>). The "i" command lets you include these files in the cross-reference. 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 n command. Do not xref "..." include files. By default, Xref cross-references the include files enclosed in double quotes (i.e. #include "mydef.h"). You can prevent these files being read and cross-referenced with the "n" command. Like the "i" command, Xref keeps track of the include file names so that they are cross-referenced only once. --------------------------------------------------------------- Note: Xref can not cross-reference include files when identifiers are used in place of filenames (it does not preprocess define statements). For example: #define F_NAME "mydef.h" #include F_NAME /* won't cross-reference! */ --------------------------------------------------------------- Page 12 of 18 Xref - C language cross-reference utility. v3.2 310 f command. Format verbose output. This command allows you to format the output of the verbose function section with linefeeds and formfeeds. The format line uses C's standard newline and formfeed commands. For example: -f \n\n\n and -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 p command. Source and header search paths. 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. 312 o command. Functions without line-of-origins. By default, Xref does not produce a listing in the verbose function 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 18 Xref - C language cross-reference utility. v3.2 313 m command. Xrefing Windows programs. This command is useful when you are cross-referencing Windows programs. The "m" command causes, Xref to load 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). 314 c command. Command file. Because of DOS's command line length limit, you may have a hard time fitting all of the commands, paths, and filenames on the command line. It can also be time consuming (not to mention annoying) typing the same command line again and again. To get around these limitations, Xref will read a text file and process the commands found there as if they were typed on the command line. The command file has a limit of 200 items, and each item has a maximum length of 80 characters (Each entry separated by a space is an item. For example: "-f \f" are two items). You can pack a line by having more than one command on a line, for example: -f \f\f -x -m... or put each command on a separate line to make it more readable: -f \f\f -x -m... Xref will output an error message if a command file cannot be opened, or it exceeds 200 items. One of the advantages of putting commands in a text file, is that it allows you to have multiple command files. Multiple Page 14 of 18 Xref - C language cross-reference utility. v3.2 command files gives you the ability to have a variety of different and easy to run cross-reference configurations. For example, you could have a number of command files with different paths following the "p" command (if your include files are in one path, then use that command file. If they are in another path, then use that command file...). Or you might have another command file that outputs only the verbose listing with a formfeed after each function's listing. You can build a basic set of command files into a more complex file by chaining them together. Say you have three command files: paths1.txt, paths2.txt and ver_only.txt. You can use each of these command files by themselves, or you can combine them on the command line. For example: -c paths1.txt -c paths2.txt -c ver_only.txt You can also combine commands and command files on the command line. For example: xref -f \f -c paths1.txt -i *.c --------------------------------------------------------------- Note: Whether you are using command files or command line input, no commands may follow the module name(s). --------------------------------------------------------------- Command files can also evoke other command files. This feature lets you chain multiple command files, and get around a file's 200 item limit. Need more than 200 items? Put the commands in two files, and as the last command in the first file, have it evoke the second. For example: . . . -c paths2.txt (this is the last command in the first file, and it will evoke the second.) (When chaining files, I suggest that you always make this the last command in the file, since it is possible to exceed the 200 item limit otherwise.) Page 15 of 18 Xref - C language cross-reference utility. v3.2 315 e and d commands. Section delimit characters. By default, Xref uses a string of "=" and "-" characters to divide the cross-reference listing's different sections from one another. If, on the other hand, you would like to use different characters than these, you can change them with the "d" and "e" commands. For example: -d + will replace the "-"s in the cross-reference listing with "+"s and: -e # will replace the "="s with "#"s where ever "="s would normally appear. 316 Command line examples. xref -i -p c:\dos\;c:\prg\text\ -w mod??.c This command line will: o Outputs a complete cross-reference listing. o -i: Cross-reference all include files. o -p: Also look for the C modules and include files in the "c:\dos\" and "c:\prg\text\" directories. o -w: Output in 132 column width. o Cross-reference any file that matches the file name pattern "mod??.c". xref -t -e * -f \f c:\prg\*.c a:\text\bigprg?.* This command line will: o -t: Only output a function tree. o -e *: Replaces all "="s with "*"s. o -f: 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 <ENTER>) you will get a short description of the command switches. --------------------------------------------------------------- Page 16 of 18 Xref - C language cross-reference utility. v3.2 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_" are ignored. 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 18 Xref - C language cross-reference utility. v3.2 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). 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, 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 18 of 18