HOW TO USE THIS FILE: This file has a table of contents and an index that refer to "pages" in this file. If your editor has a search facility, you can use it to search for the page numbers listed in either the table of contents or in the index. The phrase "Page n" (where n represents the actual page number) appears at the bottom left of the "page" it refers to. Thus, at the bottom of page 1, you'll find "Page 1" as the last item on that "page." UTILITIES TABLE OF CONTENTS ___________________________________________________________________ Overview 1 The OBJXREF command-line BGIOBJ: Conversion utility for options . . . . . . . . . 22 graphics drivers and fonts . . 1 Control options . . . . 23 Adding the new .OBJ files to Report options . . . . 24 GRAPHICS.LIB . . . . . . . . 2 Response files . . . . . . 26 Registering the drivers and Free-form response fonts . . . . . . . . . . . 2 files . . . . . . . . . . 26 An example . . . . . . . . 3 Project files . . . . . . 26 The /F option . . . . . . . 4 Linker response files . . 27 Advanced features . . . . . 5 Sample OBJXREF reports . . 28 Report by public names (/ RP) . . . . . . . . . . . 29 CPP: The preprocessor Report by module (/RM) . 29 utility . . . . . . . . . . . 9 Report by reference (/ CPP as a macro RR) . . . . . . . . . . . 30 preprocessor . . . . . . . . 9 Report by external An example . . . . . . . . 10 references (/RX) . . . . 30 GREP: A text-search utility . 10 Report of module sizes (/ Command-line syntax . . . 11 RS) . . . . . . . . . . . 31 GREP options . . . . . . . 11 Report by class type (/ Order of precedence . . 13 RC) . . . . . . . . . . . 31 The search string . . . . 14 Report of unreferenced Operators in regular symbol names (/RU) . . . 32 expressions . . . . . . 14 Verbose reporting (/RV) . 33 File specifications . . . 16 Examples of how to use Some GREP examples . . . . 16 OBJXREF . . . . . . . . . . 33 Example 1 . . . . . . . 16 Example 1 . . . . . . . . 33 Example 2 . . . . . . . 17 Example 2 . . . . . . . . 33 Example 3 . . . . . . . 17 Example 3 . . . . . . . . 34 Example 4 . . . . . . . 18 Example 4 . . . . . . . . 34 Example 5 . . . . . . . 18 OBJXREF error messages and Example 6 . . . . . . . 19 warnings . . . . . . . . . 34 Example 7 . . . . . . . 19 Error messages . . . . . 35 Example 8 . . . . . . . 20 Warnings . . . . . . . . 35 OBJXREF: The object module THELP . . . . . . . . . . . 36 cross-reference utility . . 21 TRIGRAPH . . . . . . . . . . 37 The OBJXREF command line . 21 Index 41 Appendix: Project conversion utilities . . . . . . . . . . . . . A ____________________________________________________________________ OVERVIEW Your Turbo C++ package supplies much more than just two versions of the fastest C compiler available. It also provides twelve powerful standalone utility programs that you can use with your Turbo C++ files or your other modules. Of these, MAKE, TLIB, TLINK, and TOUCH are documented in the User's Guide. The rest of them, listed below, are documented in this file. BGIOBJ converts graphics drivers and fonts CPP is the Turbo C++ preprocessor GREP searches files for text strings OBJXREF is an object module cross-referencer PRJCNVT converts Turbo C 2.0 project files to Turbo C++ format PRJ2MAK converts Turbo C++ project files to MAKE files THELP is the Turbo Help utility TRIGRAPH supports character conversion ================================================================== BGIOBJ: Conversion utility for graphics drivers and fonts You can use BGIOBJ to convert graphics driver files and character sets (stroked font files) to object (.OBJ) files. Once they're con- verted, you can link them into your program, making them part of the executable file. This is in addition to the graphics package's dynamic loading scheme, in which your program loads graphics drivers and character sets (stroked fonts) from disk at run time. Linking drivers and fonts directly into your program is advanta- geous because the executable file contains all (or most) of the Page 1 BGIOBJ drivers and/or fonts it might need, and doesn't need to access the driver and font files on disk when running. However, linking the drivers and fonts into your executable file increases its size. To convert a driver or font file to a linkable object file, use the BGIOBJ.EXE utility. This is the simplified syntax: BGIOBJ source_file where source_file is the driver or font file to be converted to an object file. The object file created has the same file name as the source file, with the extension .OBJ; for example, EGAVGA.BGI yields EGAVGA.OBJ, SANS.CHR gives SANS.OBJ, and so on. Adding the new .OBJ files to GRAPHICS.LIB You should add the driver and font object modules to GRAPHICS.LIB, so the linker can locate them when it links in the graphics routines. If you don't add these new object modules to GRAPHICS.LIB, you'll have to add them to the list of files in the TC project (.PRJ) file, on the TCC command line, or on the TLINK command line. To add these object modules to GRAPHICS.LIB, invoke TLIB with the following command line: tlib graphics + object_file_name [+ object_file_name ...] where object_file_name is the name of the object file created by BGIOBJ.EXE (such as CGA, EGAVGA, GOTH, and so forth). The .OBJ extension is implied, so you don't need to include it. You can add several files with one command line to save time; see the example in the following section. Registering the drivers and fonts After adding driver and font object modules to GRAPHICS.LIB, you have to register all the drivers and fonts that you want linked in; you do this by calling registerbgidriver and registerbgifont in your program (before calling initgraph). This informs the graphics system of the presence of those files, and ensures that they will be linked in when the executable file is created by the linker. The registering routines each take one parameter; a symbolic name defined in graphics.h. Each registering routine returns a nonnegative value if the driver or font is successfully registered. Page 2 BGIOBJ The following table shows the names to be used with registerbgidriver and registerbgifont. It is a complete list of drivers and fonts included with Turbo C++. ___________________________________________________________________ Driver file registerbgidriver Font file registerbgifont (*.BGI) symbolic name (*.CHR) symbolic name ___________________________________________________________________ CGA CGA_driver TRIP triplex_font EGAVGA EGAVGA_driver LITT small_font HERC Herc_driver SANS sansserif_font ATT ATT_driver GOTH gothic_font PC3270 PC3270_driver IBM8514 IBM8514_driver ___________________________________________________________________ An example Suppose you want to convert the files for the CGA graphics driver, the gothic font, and the triplex font to object modules, then link them into your program. Here's what you do: 1. Convert the binary files to object files using BGIOBJ.EXE, as shown in the following separate command lines: bgiobj cga bgiobj trip bgiobj goth This creates three files: CGA.OBJ, TRIP.OBJ, and GOTH.OBJ. 2. You can add these object files to GRAPHICS.LIB with this TLIB command line: tlib graphics +cga +trip +goth 3. If you don't add the object files to GRAPHICS.LIB, you must add the object file names CGA.OBJ, TRIP.OBJ, and GOTH.OBJ to your project list (if you are using Turbo C++'s integrated environment), or to the TCC command line. For example, the TCC command line would look like this: tcc niftgraf graphics.lib cga.obj trip.obj goth.obj 4. You register these files in your graphics program like this: Page 3 BGIOBJ If you ever get a linker error "Segment exceeds 64K" after linking in some drivers and/or fonts, refer to the following section. /* Header file declares CGA_driver, triplex_font & gothic_font */ #include /* Register and check for errors (one never knows...) */ if (registerbgidriver(CGA_driver) < 0) exit(1); if (registerbgifont(triplex_font) < 0) exit(1); if (registerbgifont(gothic_font) < 0) exit(1); /* ... */ initgraph(....); /* initgraph should be called after registering */ /* ... */ The /F option This section explains what steps to take if you get the linker error "Segment exceeds 64K" (or a similar error) after linking in several driver and/or font files (especially with small- and compact-model programs). By default, the files created by BGIOBJ.EXE all use the same segment (called _TEXT). This can cause problems if your program links in many drivers and/or fonts, or when you're using the small or compact memory model. To solve this problem, you can convert one or more of the drivers or fonts with the BGIOBJ /F option. This option directs BGIOBJ to use a segment name of the form filename_TEXT, so that the default segment is not overburdened by all the linked-in drivers and fonts (and, in small and compact model programs, all the program code). For example, the following two BGIOBJ command lines direct BGIOBJ to use segment names of the form EGAVGA_TEXT and SANS_TEXT. bgiobj /F egavga bgiobj /F sans When you select /F, BGIOBJ also appends F to the target object file name (EGAVGAF.OBJ, SANSF.OBJ, and so forth), and appends _far to the name that will be used with registerfarbgidriver and registerfarbgifont. (For example, EGAVGA_driver becomes EGAVGA_driver_far.) For files created with /F, you must use these far registering routines instead of the regular registerbgidriver and registerbgifont. For example, Page 4 BGIOBJ if (registerfarbgidriver(EGAVGA_driver_far) < 0) exit(1); if (registerfarbgifont(sansserif_font_far) < 0) exit(1); Advanced features This section explains some of BGIOBJ's advanced features, and the routines registerfarbgidriver and registerfarbgifont. Only experienced users should use these features. This is the full syntax of the BGIOBJ.EXE command line: BGIOBJ [/F] source destination public-name seg-name seg-class This table describes each component of the BGIOBJ command line. ___________________________________________________________________ Component Description ___________________________________________________________________ /F or -F This option instructs BGIOBJ.EXE to use a segment name other than _TEXT (the default), and to change the public name and destination file name. (See page 4 for a detailed discussion of /F.) source This is the driver or font file to be converted. If the file is not one of the driver/font files shipped with Turbo C++, you should specify a full file name (including extension). destination This is the name of the object file to be produced. The default destination file name is source.OBJ, or sourceF.OBJ if you use the /F option. public-name This is the name that will be used in the program in a call to registerbgidriver or registerbgifont (or their respective far versions) to link in the object module. The public name is the external name used by the linker, so it should be the name used in the program, prefixed with an underscore. If your program uses Pascal calling conventions, use only uppercase letters, and do not add an underscore. Page 5 BGIOBJ seg-name This is an optional segment name; the default is _TEXT (or filename_TEXT if /F is specified) seg-class This is an optional segment class; the default is CODE. ___________________________________________________________________ All parameters except source are optional. However, if you need to specify an optional parameter, all the parameters preceding it must also be specified. If you choose to use your own public name(s), you have to add declaration(s) to your program, using one of the following forms: void public_name(void); /* if /F not used, */ /* default segment name used */ extern int far public_name[]; /* if /F used, or */ /* segment name not _TEXT */ In these declarations, public_name matches the public-name you used when converting with BGIOBJ. The graphics.h header file contains declarations of the default driver and font public names; if you use those default public names you don't have to declare them as just described. After these declarations, you have to register all the drivers and fonts in your program. If you don't use the /F option and don't change the default segment name, you should register drivers and fonts through registerbgidriver and registerbgifont; otherwise, use registerfarbgidriver and registerfarbgifont. Here is an example of a program that loads a font file into memory: /* Example of loading a font file into memory */ #include #include #include #include #include #include #include #include main() { void *gothic_fontp; /* points to font buffer in memory */ int handle; /* file handle used for I/O */ unsigned fsize; /* size of file (and buffer) */ Page 6 BGIOBJ int errorcode; int graphdriver; int graphmode; /* open font file */ handle = open("GOTH.CHR", O_RDONLY|O_BINARY); if (handle == -1) { printf("unable to open font file 'GOTH.CHR'\n"); exit(1); } /* find out size of the file */ fsize = filelength(handle); /* allocate buffer */ gothic_fontp = malloc(fsize); if (gothic_fontp == NULL) { printf("unable to allocate memory for font file 'GOTH.CHR'\n"); exit(1); } /* read font into memory */ if (read(handle, gothic_fontp, fsize) != fsize) { printf("unable to read font file 'GOTH.CHR'\n"); exit(1); } /* close font file */ close(handle); /* register font */ if (registerfarbgifont(gothic_fontp) != GOTHIC_FONT) { printf("unable to register font file 'GOTH.CHR'\n"); exit(1); } /* detect and initialize graphix */ graphdriver = DETECT; initgraph(&graphdriver, &graphmode, ".."); errorcode = graphresult(); if (errorcode != grOk) { printf("graphics error: %s\n",grapherrormsg(errorcode)); exit(1); } settextjustify(CENTER_TEXT, CENTER_TEXT); settextstyle(GOTHIC_FONT, HORIZ_DIR, 4); outtextxy(getmaxx()/2,getmaxy()/2, "Borland Graphics Interface (BGI)"); /* press a key to terminate */ getch(); /* shut down graphics system */ closegraph(); Page 7 BGIOBJ return(0); } Page 8 CPP CPP: The preprocessor utility CPP produces a list (in a file) of a C source program in which include files and #define macros have been expanded. It is not needed for normal compilations of C programs. Often, when the compiler reports an error inside a macro or an include file, you can get more information about what the error is if you can see the include files or the results of the macro expansions. In many multi-pass compilers, a separate pass performs this work, and the results of the pass can be examined. Since Turbo C++ uses an integrated single-pass compiler, we provided CPP to supply the first-pass functionality found in other compilers. You use CPP just as you would use TCC, the standalone compiler. CPP reads the same TURBOC.CFG file for default options, and accepts the same command-line options as TCC. The TCC options that don't pertain to CPP are simply ignored by CPP. To see the list of arguments handled by CPP, type cpp at the DOS prompt. With one exception, the file names listed on the CPP command line are treated like they are in TCC, with wildcards allowed. The exception to this is that all files are treated as C source files. There is no special treatment for .OBJ, .LIB, or .ASM files. For each file processed by CPP, the output is written to a file in the current directory (or the output directory named by the -n option) with the same name as the source name but with an extension of .I. This output file is a text file containing each line of the source file and any include files. Any preprocessing directive lines have been removed, along with any conditional text lines excluded from the compile. Unless you use a command-line option to specify other- wise, text lines are prefixed with the file name and line number of the source or include file the line came from. Within a text line, any macros are replaced with their expansion text. Important! The resulting output of CPP cannot be compiled because of the file name and line number prefix attached to each source line. CPP as a macro preprocessor The -P option to CPP tells it to prefix each line with the source file name and line number. If you give it -P* (turning this option off), CPP omits this line number information. With this option Page 9 CPP turned off, CPP can be used as a macro preprocessor; the resulting .I file can then be compiled with TC or TCC. An example The following simple program illustrates how CPP preprocesses a file, first with -P selected, then with -P*. Source file: HELLOJOE.C #define NAME "Joe Smith" #define BEGIN { #define END } main() BEGIN printf("%s\n", NAME); END Command line used to invoke CPP as a preprocessor: cpp hellojoe.c Output: hellojoe.c 1: hellojoe.c 2: hellojoe.c 3: hellojoe.c 4: hellojoe.c 5: main() hellojoe.c 6: { hellojoe.c 7: printf("%s\n","Joe Smith"); hellojoe.c 8: } Command line used to invoke CPP as a macro preprocessor: cpp -P* hellojoe.c Output: main() { printf("%s\n","Joe Smith"); } GREP: A text-search utility GREP (Global Regular Expression Print) is a powerful text-search program derived from the UNIX utility of the same name. GREP searches for a text pattern in one or more files or in its standard input stream. Page 10 GREP Here's a quick example of a situation where you might want to use GREP. Suppose you wanted to find out which text files in your current directory contained the string "Elisabeth." You would issue the command grep Elisabeth *.txt and GREP would respond with a list of the lines in each file (if any) that contained the string "Elisabeth." The strings "elisabeth" and "ELISABETH" would not be considered matches. GREP can do a lot more than match a single, fixed string. In the section that follows, you'll see how to make GREP search for any string that matches a particular pattern. Command-line syntax The general command-line syntax for GREP is grep [options] searchstring [filespec ... ] options consist of one or more letters, preceded by a hyphen (*), that let you change various aspects of GREP's behavior. searchstring gives the pattern to search for. filespec (a list of file specifications) tells GREP which files to search. (If no file is specified, GREP searches its standard input; this lets you use GREP with pipes and redirection.) In addition, the command GREP ? prints a brief help screen showing GREP's command-line options, special characters, and defaults. (See the description of the -u command-line option for information on how to change GREP's defaults.) GREP options In the command line, options are one or more single characters preceded by a hyphen (*). Each individual character is a switch that you can turn on or off: A plus symbol (+) after a character turns the option on; a hyphen (*) after the character turns the option off. The default is on; for example, -r means the same thing as -r+. You can list multiple options individually (like this: -i -d -l), or Page 11 GREP you can combine them (like this: -ild or -il, -d, and so on); it's all the same to GREP. Here are the GREP option characters and their meanings: __________________________________________________________ Option Meaning __________________________________________________________ -c Count only: Prints only a count of matching lines. For each file that contains at least one matching line, GREP prints the file name and a count of the number of matching lines. Matching lines are not printed. -d Directories: For each filespec specified on the command line, GREP searches for all files that match the file specification, both in the directory specified and in all subdirectories below the specified directory. If you give a filespec without a path, GREP assumes the files are in the current directory. -i Ignore case: GREP ignores upper/lowercase differences (case folding). GREP treats all letters a to z as identical to the corresponding letters A to Z in all situations. -l List match files: Prints only the name of each file containing a match. After GREP finds a match, it prints the file name and processing immediately moves on to the next file. -n Numbers: Each matching line that GREP prints is preceded by its line number. -o UNIX output format: Changes the output format of matching lines to support more easily the UNIX style of command-line piping. All lines of output are preceded by the name of the file that contained the matching line. -r Regular expression search: The text defined by searchstring is treated as a regular expression instead of as a literal string. This option is on by default. -u Update options: GREP will combine the options given on the command line with its default options and write these to the GREP.COM file as the new defaults. (In other words, GREP is self- configuring.) This option allows you to tailor the Page 12 GREP default option settings to your own taste. If you want to see what the defaults are in a particular copy of GREP.COM, type GREP ? at the DOS prompt. Each option on the help screen will be followed by a + or a - depending on its default setting. -v Nonmatch: Prints only nonmatching lines. Only lines that do not contain the search string are considered to be nonmatching lines. -w Word search: Text found that matches the regular expression is considered a match only if the character immediately preceding and following cannot be part of a word. The default word character set includes A to Z, 0 to 9, and the underscore ( _ ). An alternate form of this option lets you specify the set of legal word characters. Its form is - w[set], where set is any valid regular expression set definition. If you define the set with alphabetic characters, it is automatically defined to contain both the uppercase and lowercase values for each letter in the set (regardless of how it is typed), even if the search is case-sensitive. If you use the -w option in combination with the -u option, the new set of legal characters is saved as the default set. -z Verbose: GREP prints the file name of every file searched. Each matching line is preceded by its line number. A count of matching lines in each file is given, even if the count is zero._______________ Order of precedence Remember that each of GREP's options is a switch: Its state reflects the way you last set it. At any given time, each option can only be on or off. Each occurrence of a given option on the command line overrides its previous definition. Given this command line, grep -r -i* -d -i -r* main( my*.c Page 13 GREP GREP runs with the -d option on, the -i option on, and the -r option off. You can install your preferred default setting for each option in GREP.COM with the -u option. For example, if you want GREP to always do a verbose search (-z on), you can install it with the following command: grep -u -z The search string To use GREP well, you'll need to become proficient at writing search strings. The value of searchstring defines the pattern GREP searches for. A search string can be either a regular expression or a literal string. In a regular expression, certain characters have special meanings: They are operators that govern the search. In a literal string, there are no operators: Each character is treated literally. You can enclose the search string in quotation marks to prevent spaces and tabs from being treated as delimiters. The text matched by the search string cannot cross line boundaries; that is, all the text necessary to match the pattern must be on a single line. A regular expression is either a single character or a set of characters enclosed in brackets. A concatenation of regular expressions is a regular expression. Operators in regular expressions When you use the -r option (on by default), the search string is treated as a regular expression (not a literal expression). The following characters take on special meanings: Page 14 GREP __________________________________________________________ Option Meaning __________________________________________________________ ^ A circumflex at the start of the expression matches the start of a line. $ A dollar sign at the end of the expression matches the end of a line. . A period matches any character. * An expression followed by an asterisk wildcard matches zero or more occurrences of that expression. For example, in to*, the * operates on the expression o; it matches t, to, too, etc. (t followed by zero or more os), but doesn't match ta. + An expression followed by a plus sign matches one or more occurrences of that expression: to+ matches to, too, etc., but not t. [ ] A string enclosed in brackets matches any character in that string, but no others. If the first character in the string is a circumflex (^), the expression matches any character except the characters in the string. For example, [xyz] matches x, y, or z, while [^xyz] matches a and b, but not x, y, or z. You can specify a range of characters with two characters separated by a hyphen (*). These can be combined to form expressions (like [a*bd*z?], which matches the ? character and any lowercase letter except c). \ The backslash escape character tells GREP to search for the literal character that follows it. For example, \. matches a period instead of "any character." The backslash can be used to quote itself; that is, you can use \\ to indicate a literal backslash character in a GREP expression. __________________________________________________________ Note Four of the "special" characters ($, ., *, and +) don't have any special meaning when used within a bracketed set. In addition, the character ^ is only treated specially if it immediately follows the beginning of the set definition (immediately after the [ delimiter). Any ordinary character not mentioned in the preceding list matches that character (> matches >, # matches #, and so on). Page 15 GREP File specifications filespec tells GREP which files (or groups of files) to search. filespec can be an explicit file name, or a "generic" file name incorporating the DOS ? and * wildcards. In addition, you can enter a path (drive and directory information) as part of filespec. If you give filespec without a path, GREP searches the current directory. If you don't specify any file specifications, input to GREP must come from redirection (<) or a vertical bar (|). Some GREP examples The following examples show how to combine GREP's features to do different kinds of searches. They assume GREP's default settings are unchanged. Example 1 The search string here tells GREP to search for the word main with no preceding lowercase letters ([^a*z]), followed by zero or more occurrences of blank spaces (\ *), then a left parenthesis. Since spaces and tabs are normally considered to be command-line delimiters, you must quote them if you want to include them as part of a regular expression. In this case, the space after main is quoted with the backslash escape character. You could also accomplish this by placing the space in double quotes. Command line: grep -r [^a*z]main\ *( *.c Matches: main(i:integer) main(i,j:integer) if (main ()) halt; Does not match: mymain() MAIN(i:integer); Files searched: *.C in current directory. Page 16 GREP Example 2 Because the backslash (\) and period (.) characters usually have special meaning in path and file names, you must place the backslash escape character immediately in front of them if you want to search for them. The -i option is used here, so the search is not case sensitive. Command line: grep -ri [a*c]:\\data\.fil *.c *.inc Matches: A:\data.fil c:\Data.Fil B:\DATA.FIL Does not match: d:\data.fil a:data.fil Files searched: *.C and *.INC in current directory. Example 3 This format basically defines how to search for a given word. Command line: grep -ri [^a*z]word[^a*z] *.doc Matches: every new word must be on a new line. MY WORD! word--smallest unit of speech. In the beginning there was the WORD, and the WORD Does not match: Each file has at least 2000 words. He misspells toward as toword. Page 17 GREP Files searched: *.DOC in the current directory. Example 4 This format defines a basic "word" search. Command line: grep -iw word *.doc Matches: every new word must be on a new line. However, MY WORD! word: smallest unit of speech which conveys In the beginning there was the WORD, and Does not match: each document contains at least 2000 words! He seems to continually misspell "toward" as "toword." Files searched: *.DOC in the current directory. Example 5 This is an example of how to search for a string with embedded spaces. Command line: grep "search string with spaces" *.doc *.c a:\work\myfile.* Matches: This is a search string with spaces in it. Does not match: THIS IS A SEARCH STRING WITH SPACES IN IT. This search string has spaces in it, too. Page 18 GREP Files searched: *.DOC and *.C in the current directory, and MYFILE.* in a directory called \WORK on drive A. Example 6 This example searches for any one of the characters " . : ? ' and , at the end of a line. The double quote within the range is preceded by an escape character, so it is treated as a normal character instead of as the ending quote for the string. Also, the $ character appears outside of the quoted string. This demonstrates how regular expressions can be concatenated to form a longer expression. Command line: grep -rd "[ ,.:?'\"]"$ \*.doc Matches: He said hi to me. Where are you going? In anticipation of a unique situation, Examples include the following: "Many men smoke, but fu man chu." Does not match: He said "Hi" to me Where are you going? I'm headed to the Files searched: *.DOC in the root directory and all its subdirectories on the current drive. Example 7 This example ignores case and just prints the names of any files that contain at least one match. The three command-line examples show different ways of specifying multiple options. Page 19 GREP Command line: grep -ild " the " \*.doc or grep -i -l -d " the " \*.doc or grep -il -d " the " \*.doc Matches: Anyway, this is the time we have do you think? The main reason we are Does not match: He said "Hi" to me just when I Where are you going? I'll bet you're headed Files searched: *.DOC in the root directory and all its subdirectories on the current drive. Example 8 This example redefines the current set of legal characters for a word as the assignment operator (=) only, then does a word search. It matches C assignment statements, which use a single equal sign (=), but not equality tests, which use a double equal sign (==). Command line: grep -w[=] = *.c Matches: i = 5; j=5; i += j; Does not match: if (i == t) j++; /* ======================= */ Files searched: *.C in the current directory. Page 20 OBJXREF OBJXREF: The object module cross-reference utility OBJXREF examines a list of object files and library files and produces reports on their contents. One type of report lists definitions of public names and references to them. The other type lists the segment sizes defined by object modules. There are two categories of public names: global variables and function names. The TEST1.C and TEST2.C files in the section "Sample OBJXREF reports" (page 28) illustrate definitions of public names and external references to them. Object modules are object (.OBJ) files produced by TC, TCC or TASM. A library (.LIB) file contains multiple object modules. An object module generated by TC is given the same name as the .C source file it was compiled from. This is also true for TCC, unless a different output file name is specifically indicated with the -o TCC command-line option. The OBJXREF command line The OBJXREF command line consists of the word OBJXREF followed by a series of command-line options and a list of object and library file names, separated by a space or tab character. The syntax is as follows: OBJXREF options filename filename ... The command-line options determine the kind of reports that OBJXREF will generate and the amount of detail that OBJXREF will provide. They are discussed in more detail in the next section. Each option begins with a forward slash (/) followed by a one- or two-character option name. Page 21 OBJXREF Object files and library files may be specified either on the command line or in a response file. On the command line, file names are separated by a space or a tab. All object modules specified as .OBJ files are included in reports. Like TLINK, however, OBJXREF includes only those modules from .LIB files which contain a public name referenced by an .OBJ file or by a previously included module from a .LIB file. As a general rule, you should list all the .OBJ and .LIB files that are needed if the program is to link correctly, including the startup .OBJ file and one or more C libraries. File names may include a drive and directory path. The DOS ? and * wildcard characters may be used to identify more than one file. File names may refer to .OBJ object files or to .LIB library files. (If you don't give a file extension, the .OBJ extension is assumed.) Options and file names may occur in any order in the command line. OBJXREF reports are written to the DOS standard output. The default is the screen. The reports can be sent to a printer (as with >LPT1:) or to a file (as with >lstfile) with the DOS redirection character (>). Entering OBJXREF with no file names or options produces a summary of available options. The OBJXREF command-line options OBJXREF command-line options fall into two categories: control options and report options. Page 22 OBJXREF Control options Control options modify the default behavior of OBJXREF (the default is that none of these options are enabled). _________________________________________ Option Meaning _________________________________________ /I Ignore case differences in public names. Use this option if you use TLINK without the /C option (which makes case differences significant). /D Look for .OBJ files in another directory. If you want OBJXREF to look for .OBJ files in a directory other than the current one, include the directory name on the command line, prefixed with /D: OBJXREF /Ddir1 [; dir2 [; dir3]] or OBJXREF /Ddir1 [/Ddir2] [/Ddir3] OBJXREF will search each of the directories in the specified order for all object and library files. Important! If you don't use a /D option, OBJXREF will search only the current directory. If you do use a /D option, however, the current directory will not be searched unless it is included in the directory list. For example, if you wanted OBJXREF to search first the BORLAND directory and then the current directory for files, you would enter OBJXREF /Dborland;. Page 23 OBJXREF The period denotes the current directory. /F Include full library. All object modules in specified .LIB files are included even if they do not contain public names that are referenced by an object module being processed by OBJXREF. This provides information on the entire contents of a library file. (See example 4 in the section "OBJXREF examples.") /O Allows you to specify an output file where OBJXREF will send any reports generated. Its syntax is as follows: OBJXREF filename.obj /report option /Ooutputfilename.ext By default all output is sent to the screen. /V Verbose output. Lists names of files read and displays totals of public names, modules, segments, and classes. /Z Include zero-length segment definitions. Object modules may define a segment without allocating any space in it. Listing these zero length segment definitions normally makes the module size reports harder to use but it can be valuable if you are trying to remove all definitions of a segment. _________________________________________ Report options Report options govern what sort of report is generated, and the amount of detail that OBJXREF provides. Page 24 OBJXREF _______________________________________________________________ Option Report generated _______________________________________________________________ /RC Report by class type: Module sizes ordered by class type of segment. /RM Report by module: Public names ordered by defining module. /RP Report by public names: Public names in order with defining module name. This is the default. /RR Report by reference: Public name definitions and references ordered by name. /RS Report of module sizes: Module sizes ordered by segment name. /RU Report of unreferenced symbol names: Unreferenced public names ordered by defining module. /RV Verbose reporting: OBJXREF produces a report of every type. /RX Report by external reference: External references ordered by referencing module name. ________________________________________________________________ Public names defined in .C files appear in reports with a leading underscore in the reports unless the -U* option was specified when the file was compiled (main appears as _main). You can limit the modules, segments, classes, or public names that OBJXREF reports on by entering the appropriate name on the command line prefixed with the /N option. For example, OBJXREF filelist /RM /NC0 tells OBJXREF to generate a report listing information only for the module named C0. Page 25 OBJXREF Response files The command line is limited by DOS to a maximum of 128 characters. If your list of options and file names will exceed this limit, you must place your file names in a response file. A response file is a text file that you make with a text editor. Since you may already have prepared a list of the files that make up your program for other Turbo C++ programs, OBJXREF recognizes several response file types. Response files are called from the command line using one of the following options. The response file name must follow the option without an intervening space (so, for example, you would type /Lresp, not /L resp). You can specify more than one response file on the command line; additional .OBJ and .LIB file names can precede or follow them. Free-form response files You can create a free-form response file with a text editor. Just list the names of all .OBJ and .LIB files needed to make your .EXE file. Any file name listed in the response file without an extension is assumed to be an .OBJ file. To use free-form files with OBJXREF, type in each response file name on the command line, preceded by an @, and separate it from other command-line entries with a space or tab: @filename @filename ... Project files Page 26 OBJXREF You can also use project files of the type generated by Turbo C++'s integrated environment as response files. In the command line, precede the project file name with /P, like this: /Pfilename If the file name does not include an explicit extension, a .PRJ extension is assumed. File names in the project file with a .C extension or no extension are interpreted as specifying the corresponding .OBJ file. You need not remove file dependencies specified inside parentheses; they are ignored by OBJXREF. Note By itself, the list of files in a .PRJ file does not specify a complete program--you must also specify a startup file (C0x.OBJ) and one or more Turbo C++ library files (MATHX.LIB, EMU.LIB, and CX.LIB, for example). In addition, you may need to use the /D option to specify the directory where OBJXREF should look for your .OBJ files. Linker response files Files in TLINK response-file format can also be used by OBJXREF. A linker response file called from the command line is preceded by /L, like so: /Lfilename To see how to use one of these files, refer to Example 2 in the section "Examples of how to use OBJXREF." Page 27 OBJXREF Sample OBJXREF reports Suppose you have two source files in your Turbo C++ directory, and want to generate OBJXREF reports on the object files compiled from them. The source files are called TEST1.C and TEST2.C, and they look like this: /* test1.c */ int i1; /* defines i1 */ extern int i2; /* refers to i2 */ static int i3; /* not a public name */ extern void look(void); /* refers to look */ void main(void) /* defines main */ { int i4; /* not a public name */ look(); /* refers to look */ } /* test2.c */ #include extern int i1; /* refers to i1 */ int i2; /* defines i2 */ void look(void) /* defines look */ { exit(i1); /* refers to exit... */ } /* and to i1 */ The object modules compiled from these source files are TEST1.OBJ and TEST2.OBJ. You can tell OBJXREF what kind of report to generate about these .OBJ files by entering the file names on the command line, followed by a /R and a second letter denoting report type. Page 28 OBJXREF Note: The following examples show only useful parts of the output. Report by public names (/RP) A report by public names lists each of the public names defined in the object modules being reported on, followed by the name of the module in which it is defined. If you enter this on the command line: OBJXREF /RP test1 test2 OBJXREF generates a report that looks like this: SYMBOL DEFINED IN _i1 TEST1 _i2 TEST2 _look TEST2 _main TEST1 Report by module (/RM) A report by module lists each object module being reported on, followed by a list of the public names defined in it. If you enter this on the command line: OBJXREF /RM test1 test2 OBJXREF generates a report that looks like this: MODULE: TEST1 defines the following symbols: public: _i1 public: _main MODULE: TEST2 defines the following symbols: public: _i2 public: _look Page 29 OBJXREF Report by reference (/RR) A report by reference lists each public name with the defining module in parentheses on the same line. Modules that refer to this public name are listed on following lines indented from the left margin. This is the default if no report option is specified. If you enter this on the command line: OBJXREF /RR C0 test1 test2 CS.LIB OBJXREF generates a report that looks like this: _exit (EXIT) C0 TEST2 _i1 (TEST1) TEST2 _i2 (TEST2) _look (TEST2) TEST1 _main (TEST1) C0 Report by external references (/RX) A report by external references lists each module followed by a list of external references it contains. If you enter this on the command line: OBJXREF /RX C0 test1 test2 CS.LIB OBJXREF generates a report that looks like this: MODULE: C0 references the following symbols: _main MODULE: TEST1 references the following symbols: _i2 _look Page 30 OBJXREF MODULE: TEST2 references the following symbols: _exit _i1 Report of module sizes (/RS) A report by sizes lists segment names followed by a list of modules that define the segment. Sizes in bytes are given in decimal and hexadecimal notation. The word uninitialized appears where no initial values are assigned to any of the symbols defined in the segment. Segments defined at absolute addresses in a .ASM file are flagged Abs to the left of the segment size. If you enter this on the command line: OBJXREF /RS test1 test2 OBJXREF generates a report that looks like this: These files were compiled using the large memory model. TEST1_TEXT 6 (00006h) TEST1 6 (00006h) total TEST2_TEXT 10 (0000Ah) TEST2 10 (0000Ah) total _BSS 4 (00004h) TEST1, uninitialized 2 (00002h) TEST2, uninitialized 6 (00006h) total Report by class type (/RC) A report by class type lists segment size definitions by segment class. The CODE class contains instructions, DATA class contains initialized data and BSS class contains uninitialized data. Segments Page 31 OBJXREF which do not have a class type will be listed under the notation No class type. If you enter this on the command line: OBJXREF /RC C0 test1 test2 CS.LIB OBJXREF generates a report that looks like this: BSS 4 (00004h) TEST1 2 (00002h) TEST2 ... 132 (00084h) total CODE 6 (00006h) TEST1 10 (0000Ah) TEST2 16 (00010h) total DATA 143 (0008Fh) C0 143 (0008Fh) total Report of unreferenced symbol names (/ RU) A report of unreferenced symbol names lists modules that define public names not referenced in other modules. Such a symbol is either: 1. referenced only from within the defining module and does not need to be defined as a public symbol (in that case, if the module is in C, the keyword static should be added to the definition; if the module is in TASM, just remove the public definition). 2. never used (therefore, it can be deleted to save code or data space). If you enter this on the command line: OBJXREF /RU test1 test2 OBJXREF generates a report that looks like this: Page 32 OBJXREF MODULE: TEST2 defines the unreferenced symbol _i2. Verbose reporting (/RV) If you enter /RV on the command line, OBJXREF generates one report of each type. Examples of how to use OBJXREF These examples assume that the application files are in the current directory of the default drive and that the Turbo C++ startup files (C0x.OBJ) and the library files are in the \TURBOC\LIB directory. Example 1 C>OBJXREF \turboc\lib\c0l test1 test2 \turboc\lib\cl.lib In this example, the TEST1.OBJ and TEST2.OBJ files and the Turbo C++ startup file \TURBOC\LIB\C0L.OBJ and the library file \TURBOC\LIB\CL.LIB are specified. Since no report type is specified, the resulting report is the default report by reference, listing public names and the modules that reference them. Example 2 C>OBJXREF /RV /Ltest1.arf The TLINK response file TEST1.ARF contains the same list of files as the command line in Example 1. The /RV option is specified, so a report of every type will be generated. TEST1.ARF contains \turboc\lib\c0l test1 test2 test1.exe test1.map \turboc\lib\cl Page 33 OBJXREF Example 3 C>OBJXREF /RC B:c0s /Ptest1 @libs The TC project file TEST1.PRJ specifies TEST1.OBJ and TEST2.OBJ. The response file @libs specifies libraries on a disk in the B drive. TEST1.PRJ contains test1 test2.c The file LIBS contains b:maths.lib b:emu.lib b:cs.lib The startup and library files specified depend on the memory model and floating point options used in compilation. The /RC causes a report of class type to be output. Example 4 C>OBJXREF /F /RV \turboc\lib\cs.lib This example reports on all the modules in the Turbo C++ library file CS.LIB; OBJXREF can produce useful reports even when the files specified do not make a complete program. The /F causes all modules in CS.LIB file to be included in the report. OBJXREF error messages and warnings OBJXREF generates two sorts of diagnostic messages: error messages and warnings. Page 34 OBJXREF Error messages Out of memory OBJXREF performs its cross referencing in RAM memory and may run out of memory even if TLINK is able to link the same list of files successfully. When this happens, OBJXREF aborts. Remove memory resident programs to get more space, or add more RAM. Warnings WARNING: Unable to open input file The input file filename could not be located or opened. OBJXREF proceeds to the next file. WARNING: Unknown option -