tdump.txt

tasm source document descript

/*********************************************************************/
                        TDUMP.EXE Utility Program

This file contains information on:

1.  TDUMP: The file inspecting utility
2.  Understanding "Undefined Symbol" Error Messages
3.  Resolving Undefined Symbol linker messages
4.  Borland Open Architecture: Name Mangling


===================================================================
1.  TDUMP: The file inspecting utility
===================================================================
TDUMP.EXE is a utility that you use to examine the structure and
contents of files.

TDUMP organizes the output display according to the extension of the
file you're dumping. If the file extension is recognizable, TDUMP
displays the file's components according to the file type. TDUMP
recognizes many file extensions, including .EXE, .OBJ, and .LIB files.
If TDUMP doesn't recognize an extension, it produces a hexadecimal dump
of the file. You can control the output format by using command-line
options when you start the TDUMP (these command-line options are
described later).


TDUMP syntax
------------
The syntax for TDUMP is:

  TDUMP [<options>] <Inputfile> [<Listfile>] [<options>]

  o  <options> stands for any of the TDUMP options discussed in the
     next section. For a list of the available command-line options,
     type TDUMP, then press <Enter> at the DOS prompt.

  o  <Inputfile> is the file whose structure you want to display (or
     "dump").

  o  <Listfile> is an optional output file name. Note that you can
     also use the standard DOS redirection command ">" to create an
     output file.


TDUMP command-line options
--------------------------
You can use several option switches at a time with TDUMP. Because you can start
each option with either a hyphen or a forward slash, the following two commands
are equivalent:

  TDUMP -el -v demo.exe

  TDUMP /el /v demo.exe


The -a and -a7 options
- - - - - - - - - - - -
TDUMP automatically adjusts its output display according to the file extension
type. However, you can force an ASCII file display using either the -a or -a7
options:

  o  -a  produces an ASCII file display that shows the offset and the
     contents using the displayable ASCII characters. TDUMP displays
     non-displayable characters (like control characters) as a period.

  o  -a7 converts high-ASCII characters to their low-ASCII
     equivalents. This is useful if the file you are dumping sets
     high-ASCII characters as flags (WordStar files do this).


The -b# option
- - - - - - - -
The -b# option allows you to display information beginning at a specified offset.
For example, if you wanted a dump of MYFILE starting from offset 100, you would
use the following command:

  TDUMP -b100 MYFILE


The -d option
 - - - - - - -
The -d option causes TDUMP to dump any Borland 32-bit debug information found in
the .OBJ file. If you do not specify this option, TDUMP displays raw data only.


The -e, -el, -er and -ex options
- - - - - - - - - - - - - - - - -
All four options force TDUMP to display the file as an executable (.EXE) file.

An .EXE file display consists of information contained within a file that is used
by the operating system when loading a file. If symbolic debugging information is
present (Turbo Debugger or MicrosoftCodeView), TDUMP displays it.

TDUMP displays information for DOS executable files, NEW style executable files
(Microsoft Windows and OS/2 .EXEs and DLLs), and Linear Executable files.

  o  -el suppresses line numbers in the display.

  o  -er suppresses the display of the relocation table.

  o  -ex prevents the display of New style executable information.
     This means TDUMP will only display information for the DOS
     "stub" program.


The -h option
- - - - - - - -
The -h option displays the dump file in hexadecimal (hex) format. Hex format
consists of a column of offset numbers, 16 columns of hex numbers, and their ASCII
equivalents (a period appears where no displayable ASCII character occurs).

If TDUMP doesn't recognize the input file's extension, it displays the file in hex
format (unless an option is used to indicate another format).


The -l and -li options
- - - - - - - - - - - -
The -l option displays the output file in library (.LIB) file format. A library
file is a collection of object files (see the -o option for more on object files).
The library file dump displays library-specific information, object files, and
records in the object file.

The -li option tells TDUMP to display a short form of "impdef" records when
dumping import libraries. You can also specify a search string using the following
syntax:
	-li=<string>

For example, the command
	TDUMP -li=codeptr import.lib
results in the following output:
	Impdef:(ord) KERNAL.0336=ISBADCODEPTR
This output shows that the function is exported by ordinal, whose ordinal value is
336 (decimal). In addition, the output displays the module and function name.

If you give the command
	TDUMP -li=walk import32.lib
TDUMP displays:
	Impdef:(name) KERNEL32.????=HEAPWALK
This shows the output of a function exported by name.


The -m option
- - - - - - -
The -m option leaves C++ names occurring in object files, executable files, and
Turbo Debugger symbolic information files in "mangled" format. This option is
helpful in determining how the C++ compiler "mangles" a given function name and
its arguments.


The -o, -oc, -oi, and -ox options
---------------------------------
The -o option displays the file as an object (.OBJ) file. An object file display
contains descriptions of the command records that pass commands and data to the
linker, telling it how to create an .EXE file.

The display format shows each record and its associated data on a record-by-record
basis.

  o  -oc causes TDUMP to perform a cyclic redundancy test (CRC) on
     each record encountered. The display differs from the -o display
     only if an erroneous CRC check is encountered (the TDUMP CRC
     value differs from the record's CRC byte).

  o  -oi<id> includes only specified record types in the object module
     dump. Replace <id> with the name of the record to be displayed.
     For instance,

        TDUMP -oiPUBDEF MYMODULE.OBJ

     produces an object module display for MYMODULE.OBJ that displays
     only the PUBDEF records.

  o  -ox<id> excludes designated record types from the object module
     dump. Replace <id> with the record name not to be displayed. For
     instance,

        TDUMP -oxPUBDEF MYMODULE.OBJ

     produces an object module display for MYMODULE.OBJ that excludes
     the PUBDEF records.

  o  The -ox and -oi options are helpful in finding errors that occur
     during linking. By examining the spelling and case of EXTDEF and
     PUBDEF symbols, you can resolve many linking problems. For
     instance, if you receive an "unresolved external" message from
     the linker, use "TDUMP -oiEXTDEF" to display the external
     definitions occurring in the module causing the error. Then, use
     "TDUMP -oiPUBDEF" on the module containing the public symbol
     which the linker could not match.

Another use for the -oi switch is to check the names and sizes of the segments
generated in a particular module. For instance,

  TDUMP -oiSEGDEF MYMODULE.OBJ

displays the names, attributes, and sizes of all of the segments in MYMODULE.

Note: To get a list of record types for -0i and -ox, use the command-line
      options -oi? and -ox?.


The -R option
- - - - - - -
The -R option causes TDUMP to dump relocation tables from 32-bit PE (Win32) format
images. The default is to suppress these dumps.


The -v option
- - - - - - -
The -v option is used to create a verbose display. If you use -v with an .OBJ or
.LIB file, TDUMP produces a hexadecimal dump of the record's contents without any
comments about the records.

If you use TDUMP on a Turbo Debugger symbol table, it displays the information
tables in the order in which it encounters them. TDUMP doesn't combine information
from several tables to give a more meaningful display on a per-module basis.


===================================================================
2.  Understanding "Undefined Symbol" Error Messages
===================================================================
One of the most common error messages seen by developers using a C or
C++ compiler is "undefined symbol." This document provides a general
description of what causes undefined symbol error messages, as well as
instructions on solving specific undefined symbol errors.

The following error message are treated in order:
  UNDEFINED SYMBOL AT COMPILE TIME
  UNDEFINED SYMBOL AT LINK TIME
  OTHER UNDEFINED SYMBOL ERRORS
  o  UNDEFINED SYMBOL WHEN LINKING A BORLAND EXAMPLE
  o  UNDEFINED SYMBOL WHEN TLINKING FROM DOS COMMAND LINE
  o  UNDEFINED SYMBOL LINKING C/C++ AND ASSEMBLY MODULES
  o  UNDEFINED SYMBOL LINKING C++ WITH C OR ASSEMBLY MODULES
  o  UNDEFINED SYMBOL: '_main' IN MODULE C0.ASM
  o  UNDEFINED SYMBOL LINKING A DLL
  o  UNDEFINED SYMBOL: A PSEUDO REGISTER (ie. _AX)
  o  UNDEFINED SYMBOL: 'FIWRQQ'
  o  UNDEFINED SYMBOL: AN IOSTREAM CLASS MEMBER
  o  UNDEFINED SYMBOL: 'abort()'
  o  UNDEFINED SYMBOL: '_exitclean()'
  o  UNDEFINED SYMBOL: LLSH or SCOPY or FMUL or FDIV
  o  UNDEFINED SYMBOL: STATIC POINTER TO A CLASS MEMBER FUNCTION
  o  UNDEFINED SYMBOL: '_WSPRINTF'
  o  UNDEFINED SYMBOL: 'fidrqq'
  o  UNDEFINED SYMBOL IN WINDOWS.H
  o  UNDEFINED SYMBOL USING TCLASDLL.LIB
  o  UNDEFINED SYMBOL USING SELECTORS PROVIDED BY WINDOWS
  o  UNDEFINED SYMBOL: 'ChangeSelector'
  o  UNDEFINED SYMBOLS USING THE OBJECTWINDOWS LIBRARY (OWL)
  o  UNDEFINED SYMBOL: 'Object::new(unsigned int)'
  GETTING A CLOSER LOOK
  o  USING TDUMP TO RESOLVE UNDEFINED SYMBOLS
  o  USING IMPDEF TO RESOLVE UNDEFINED SYMBOLS IN A DLL


UNDEFINED SYMBOL AT COMPILE TIME
--------------------------------
An undefined symbol at compile time indicates that the named
identifier was used in the named source file, but had no definition in
the source file. This is usually caused by a misspelled identifier
name, or missing declaration of the identifier used.

EXAMPLE 1:
    int main(void)
    {
        test = 1;
        return 0;
    }

The code shown in Example 1 generates an undefined symbol error if the
variable "test" was not declared in either an included header file or
in the actual source file itself.

EXAMPLE 2:
    int main(void)
    {
        int test;
        Test = 1;
        return 0;
    }

The code shown in Example 2 causes an undefined symbol error message
to be displayed because the variable "Test" was not spelled as it was
declared. Remember that C and C++ are case-sensitive languages.


UNDEFINED SYMBOL AT LINK TIME
-----------------------------
When linking multi-file projects, the linker must resolve all
references to functions and global variables shared between modules.
When these references cannot be resolved, the linker generates
an "undefined symbol" error message. This means that after searching
all of the object files and libraries which are included in the link,
the linker was unable to find a declaration for an identifier you
used. This can be caused by:

  o  Forgetting to include a needed object module or library in
     your link (project file, response file, or command line).

  o  Misspelling the name of the undefined symbol either where it
     was used or where it was declared.

  o  Accidentally declaring a global variable as "extern."

  o  Forgetting to use extern "C" to disable name mangling when you're
     mixing C++ with C or Assembly modules. See the specific entry on
     this subject elsewhere in this document or consult the
     HELPME!.DOC file included with the product.

  o  Turning OFF Generate Underbars in one of the modules you're
     linking.

If all else fails, use TDUMP to dump both object modules and note any
difference between the symbols used. This will usually give enough
insight to resolve the problem. For more information on using TDUMP to
resolve undefined symbol errors, see the "Getting a Closer
Look "section in this document.


OTHER UNDEFINED SYMBOL ERRORS
------------------------------
The following list provides solutions to some of the more common
causes of undefined symbol errors:

  o  UNDEFINED SYMBOL WHEN LINKING A BORLAND EXAMPLE
     Almost all of Borland's examples come with project files. You
     must use the project file when building the example to ensure
     that all necessary modules are linked and all the necessary
     settings are defined.

  o  UNDEFINED SYMBOL WHEN TLINKING FROM DOS COMMAND LINE
     The TLINK command line must have the libraries in the following
     order ( GRAPHICS.LIB + <user libs> + EMU.LIB + MATH (S,T,C,M,L -
     for model) + C (S,T,C,M,L - for model)

  o  UNDEFINED SYMBOL LINKING C/C++ AND ASSEMBLY MODULES
     There are several sources of undefined symbol errors when trying
     to link assembly with C or C++ modules:

       o  Turbo Assembler generates all upper-case symbols unless you
          specify /ml or /mx on the assembly command line. Since C
          modules are, by default, case sensitive, failing to do this
          will result in undefined symbols for all symbols that are
          not completely upper case in the C module(s).

       o  The symbols in the assembly file being referenced from a C
          module must be declared using a PUBLIC directive. TLINK does
          not consider symbols which are not declared PUBLIC when it
          attempts to resolve an undefined symbol.

       o  All symbols in the assembly module that are referenced in
          the C module must be prototyped/declared as extern in the C
          module -- the compiler generates undefined symbol errors for
          all symbols not declared in this manner. In addition, all
          symbols in the assembly module that are referenced from a C
          module must have an underscore prefix. This naming
          convention must be used in the assembly module. You can
          either do this explicitly (_symbol) or you can use:

            .model <memory model used>, C

          to specify this implicitly for all symbols.

          IMPORTANT NOTE: If you put underscores in front of your
          assembly routines and also use the .model (memory model)
          C directive, the public symbol will be generated with two
          underscores; consequently an undefined symbol error is
          generated.

          If all else fails, TDUMP both object modules and note any
          difference between symbols. This will usually give enough
          insight to resolve the problem. For more information on
          using TDUMP to resolve undefined symbol errors see the
          "Getting a Closer Look" section in this document.

  o  UNDEFINED SYMBOL LINKING C++ WITH C OR ASSEMBLY MODULES
     C++ is a strongly typed language. In order to support type-safe
     linkage (as well as function overloading), Borland C++ must
     attach information to the symbols generated for function names
     and variables. When this is done, the symbol will no longer match
     the standard C style function name. In order to link correctly