Contents of the TPINFO.DOC file

TPINFO is a utility for extracting information from the TPU, TPL, and TPMfiles created by Turbo Pascal version 4.0. It can display four kinds ofinformation gathered from these files:

1. General information: The amount of code and data (both initialized and uninitialized) in a unit; the size of the symbol table, relocation table (used by the linker), and line number table (used by TPMAP); the state of the $N compiler directive ($N+/$N-); the names of all units USEd by the unit; and the names of all source and object (.OBJ) files that the unit depends on. This information is always displayed. Example:

The size of the line number table will be 0 if the $D+ compiler directive was not in effect when the unit was compiled. Note that all values displayed by TPINFO are in decimal format (not hex) and refer to bytes (not paragraphs).

2. The names of all interfaced symbols: types, constants, variables (includes typed constants), procedures, and functions. Symbol names are sorted alphabetically and grouped according to class. This information is displayed only if the '/S' command line option is specified. Example:

The Constants category includes symbols found in enumerated type declarations, such as 'Beatles = (John, Paul, George, Ringo)'. The Variables category includes typed constants and absolute variables (more on these below).

3. The sizes of all interfaced procedures and functions: This information, displayed only if the '/P' command line option is specified, sometimes involves guesswork. In a TPU file, all routines (procedures and functions) are associated with a particular "code block". If the routine is written in Pascal, the size of the code block is the size of the routine, and the "entry point" displayed by TPINFO will indicate where the code for the routine actually starts, relative to the beginning of the block; everything prior to the entry point is presumably constant data (probably strings). If the routine is an external assembly language routine linked from an OBJ file, however, the size of the code block is the size of the OBJ file, and the entry point is the offset into the OBJ file for the routine. Example:

(The large entry point values are good indications that 'assigncrt' and 'changeattribute' are both assembly language routines located in OBJ files, whereas 'blockcursor', which has an entry point of 0, is probably written in Pascal.)

The size of the code block and the entry point will always be correct. The "approximate size" of the routine, however, is guaranteed to be correct only for routines written in Pascal--neither the compiler nor TPINFO has any way of knowing where an assembly language routine ends. So what TPINFO does is to estimate the size of the routine by searching for a second routine in the same code block, one with a higher entry point. If no such routine is found, the size shown is simply the size of the code block minus the entry point. If one is found, however, the size shown represents the difference between the two entry points. This estimated size will frequently be accurate if nothing intervenes between the two routines, but even so there's no guarantee that the bulk of the work done by the routine isn't performed by low-level routines hidden in the OBJ file. In short, TPINFO's "approximate size" figures should be taken with a grain of salt where assembly language routines are concerned.

Special case: Inline macros such as

procedure InterruptsOff; inline($FA); {-Turn interrupts off}

do appear in the symbol table as procedures and functions, but they do not belong to a particular code block, and their sizes are not readily available (though they can be calculated). For now TPINFO simply ignores them.

4. Information about global variables and typed constants: their type (integer, byte, etc.), class (global variable, typed constant, absolute variable), and size. This information is displayed only if the '/V' command line option is selected. Example:

There are a couple of noteworthy limitations here. First, TPINFO does not bother to track down the precise name of the variable type (e.g., if the type is 'CharSet = set of Char', TPINFO will report 'set' rather than 'charset'). Due to the way that the symbol table is arranged, finding the precise name for the type would be very difficult. Second, TPINFO will report the type and size only if the type is declared either in the current unit or in SYSTEM (where simple types such as byte and integer are declared). It does not search other units in TPL or TPM files to try to locate this information, even though it is sometimes available, because doing so would add a considerable amount of overhead for minimal gain. If the type information is not found, the type will be 'unknown', and the size will be 0. (The class--var, const, or abs--is always known.)

Notes about absolute variables: TPINFO displays the addresses of absolute variables immediately following the name of the variable. Example:

2. If the '/P' option is specified, TPINFO can tell you what routines were stripped by the linker. These routines are flagged by a series of asterisks where you would normally expect to see values. Example:

Note that the linker cannot strip unused code located in OBJ files. If a single routine in the OBJ file (considered a single code block) is used, the entire OBJ file will be linked in. This explains why routines that are never actually used will sometimes appear in the list without asterisks beside them.

Note that a program is treated just like a unit by the compiler, except thatit cannot be pre-compiled, and that the first "unit" in a TPM file is alwaysthe program itself.

Special note about the SYSTEM unit----------------------------------

The compiler does not treat built-in procedures and functions (MemAvail, New,BlockRead, etc.) like ordinary routines. If you do a hex dump of SYSTEM.TPU,you'll see their names, but I have been unable to find a reliable way todetermine what code block they're in, their sizes, etc., so for now TPINFOjust ignores them.

Running TPINFO--------------

TPINFO is command-line driven and expects a command line of the followingform:

TPINFO tpufile[.TPU] [Options] [>Output]

"tpufile" is the name of the TPU, TPL, or TPM file to be analyzed, and anextension of "TPU" is assumed. If the file is not in the current directory,TPINFO will search DOS's PATH in an attempt to find it. If no "tpufile" isspecified, an error message will be displayed.

The following options, discussed above, are currently available:

/S Generate a list of symbol names. /P Generate a list of procedures/functions and their sizes. /V Generate a list of variables and their types and sizes.

TPINFO will accept either '/' or '-' as an option delimiter, and the case ofthe option character ('S', 's', etc.) is not important.

TPINFO writes to the DOS standard output device, so its output may beredirected to a file or piped to a filter program such as MORE. Redirectingoutput is especially advisable if you are specifying the '/P' option, since itcan produce several screens full of information in the blink of an eye, or ifyou are examining a TPL or TPM file. (Error and status messages are alwayswritten to the screen.)

If you enter "TPINFO" without any parameters or "TPINFO ?", a brief helpscreen will be displayed.

Limitations-----------Like TPMAP and the compiler itself, TPINFO loads the entire TPU/TPL/TPM fileinto memory at once, so memory consumption can be high if the file is large,although 128K of available memory should usually be more than adequate. TPINFOis further limited to 2500 symbols in any one unit, a limitation that you arenot likely to encounter.

TPINFO is also version-dependent: it's not likely to work with TPU/TPL/TPMfiles produced by future (post-4.0) versions of the compiler. I will try toupdate it to keep up with any changes, though.

File Formats------------

Borland has not yet made the format of TPU/TPL/TPM files public. TPINFO wasmade possible largely by spending countless hours staring at hex dumps, aswell as a fair amount of time tracing through the compiler with Periscope. Ihave not seen any internal documents from Borland, nor has anyone at Borlandtold me anything about the file formats (except that they're secret).

Many thanks are due, however, to Jim Kyle, a pioneer in the field ofTPU-snooping, who got me started; to Dave Baldwin, who pointed out severalthings about TPM files that I didn't know; and to Kim Kokkonen, who, besideshelping me figure out a few stumpers, kindly allowed me to work on TPINFO oncompany time (well, maybe he had a motive...).

Anyway, please don't ask to see the source code for TPINFO. If Borland evermakes the file formats public, the source code for TPINFO will be made publictoo. Until then I feel obliged not to reveal any of their secrets for them.

Distribution of TPINFO----------------------

TPINFO is hereby placed in the public domain for private, non-commercial use.It may be distributed freely by means of public bulletin boards and otherdistribution channels for public domain software, so long as no fee is chargedfor it.