Technical Information Database

TI867C.txt   Resolving Undefined Symbol linker messages.       
Category   :General
Platform    :All
Product    :Borland C++  3.x    

Description:
  The purpose of this document is to provide an overview of the
  Linking process and help in identifying causes of 'unresolved
  external symbols'.
      The code for printf is in a module in the run time library.
  When one calls printf in a C/C++ module, the compiler creates a
  record ( referred to as EXTDEF - EXTernal DEFinition ) which
  indicates the call to an 'extern'al function.  The linker then
  looks at that OBJ, along with all the other modules and libraries
  specified and attempts to find another module ( .OBJ or .LIB )
  which defines/provides the symbol printf.
  If successful in the search, the call is printf is resolved;
  Otherwise the linker generates an error indicating that 'printf'
  is an undefined symbol.
  The error message, however, is very often not the result of
  leaving out the module containing the symbol being looked for but
  rather a discrepancy between the name used by the caller ( the
  C/C++ module calling printf() in the case mentioned above ) and
  the supplier ( the LIBRARY containing the code to printf()  ).
  The *real* name of any symbol is almost always different from the
  name/identifier used by the programmer.   For example, the *real*
  name ( by *real* name we mean the idenfier used/generated by the
  tools ) of strcpy is:  '_strcpy'.   The *real* name of a symbol
  depends on the various settings and options.   The relevant ones
  are list below:
       Calling Conventions:
              > cdecl
              > pascal
              > fastcall
      Compiler Settings:
              > generate underbars
              > unsigned chars        ( C++ only )
      Optimizations:
              > Object Data Calling   ( C++ only )
      Virtual Table:
              > Far Virtual Tables
      Language used:
              > C
              > C++
              > Assembly
  Furthermore there are two options which will affect how the
  linker attempts to match symbols:
               > Case sensitive link
               > Case sensitive exports ( Windows only )
  The following is a discussion of how the above mentioned options
  affect the *real* name of symbols, hence the resolution of
  symbols.
  Calling Conventions:
  ====================
       The Borland/Turbo C++ allows one to specify the default
  calling convention.  This default can be overriden by using the
  'pascal', '_fastcall' or 'cdecl' keywords, however.  Whether set
  globally or on individual function instances, the calling
  convention affects the name of functions;  by default, when the
  compiler encounters a function declared as,
  int Foo( int );               [ or 'int cdecl Foo( int )' ];
  the name generated is _Foo: that is, the resulting name has the
  same case but is preceeded with a leading underscore.  The
  generation of the underscore is the default behavior, and is
  neccessary when one links to the run time libraries.  There is no
  'printf' symbol in the RTL (!), but there is a '_printf'.
  While the C calling convention implies 'Case Sensitivity' and
  'Generation of Underbars', Borland/Turbo C++ provides separate
  settings for the generation of underbars and the calling
  convention:  Generation of Underbars can be controled from the
  Options | Compiler | Advanced Code Generation Dialog, or the -u
  option from the command line.  ( -u- would turn it off, it is on
  by default);  the 'Calling Convention' can be modified via the
  Options | Compiler | Entry/Exit Code Dialog.
  If our function 'Foo' is declared with the pascal modifier, for
  example:
  int pascal Foo( int );
  ( Or if the default 'Calling Convention' is set to 'PASCAL' ) the
  resulting name will be FOO:  that is, all upercase with no
  underscore.  The '_fastcall' modifier is similar to 'cdecl' in
  regards to Case Sensitivity but the underscore character is
  replaced with the '.   Hence:
  int _fastcall Foo( int );
  will result in the '@Foo' symbol.
  Therefore, mismatching the calling conventions may/will result in
  'Undefined Symbols' - Watch for clues in the undefined symbol
  name provided in the Linker error messages ( e.g. look at the
  Case Sensitivity and any leading characters ) to spot cases of
  incorrect settings in the 'Calling Convention' and/or 'Generation
  of Underbars'.
  NAME MANGLING:
  ==============
       The C++ language uses yet another naming convention as part
  of its implementation of 'type safe linkage'.  Imagine a function
  foo which take two longs [ e.g. void foo( long, long ) ]; what if
  someone has it incorrectly prototyped in a calling module as
  taking two floats  [ e.g.  void foo( float, float ); ].  The
  results of such a call will be unpredictable.  When using the C
  language, the linker would resolve such a call since the symbol
  the compiler uses to call the function taking two floats will be
  '_foo', and the name the compiler used in the module which
  implements the function taking two longs is also '_foo'.
  In C++, however, the name the compiler generates for a function
  is a 'mangled' name: it is 'encrypted' based on the parameters
  types the function expects.  In the scenario described in the
  prior paragraph, the call to 'foo' will not be resolved since the
  compiler will generate different names for 'void foo( float,
  float )'  and  'void foo( long, long )'.
  Because of the fact that a C++ function's ( real! ) name depends
  on the types of its parameters, if unsigned chars is used as a
  compiler option, it will change the name of functions declared to
  take a char, or char *.  Unsigned chars is off by default, it is
  turned on under the Options | Compiler | Code generation menu.
  Or by specifying the -K option with the command line compiler.
  Watch out for potential 'Undefined Symbol' messages caused by a
  mismatched of char v. unsigned char.
  The 'virtual mechanism' of C++ is implemented via a table
  commonly referred to as 'Virtual Table' ( or VMT - Virtual Method
  Table ).  Various settings of the Compiler dictate whether the
  Table ends up in the Default Data Segment or in a Far Segment (
  namely Memory Model, '_export' and 'huge' class modifiers,
  Virtual Table Control Options etc ).  To further enforce 'type-
  safe-linkage', the Borland/Turbo C++ compiler include the
  'distance' of the Virtual Table as part of its 'Name-Mangling'
  logic.  This prevents the linker from resolving function calls
  which would crash at run-time because of mis-matched 'Virtual
  Table Control' settings.   In the same token, Borland provides
  the 'Object Data Calling convention' for improved efficiency of
  C++ code.  Once again, the 'Name-mangling' algorithm also
  reflects the enabling of 'Object Data Calling'.  This ensures
  that function calls involving mismatched 'Object Data Calling'
  convention between caller and callee will be caught at link time
  ( instead of resulting in erratic run-time behaviour! ) .
  To illustrate the effect of 'Virtual Table Control' and 'Object
  Data Calling', let's create a simple class and look at the
  effects of the various settings on the resulting names:
  class  Test
  {
       public:
           virtual int Process( void );
  };
  int main( void )
  {
       Test t;
       return t.Process();
  }
  The following table illustrates the effects of Compiler Settings
  on the *actual* name generated for the member function 'int
  Test::Process(void)'.
       +----------------------------------------------------------+
       | Object Call. | Far V. Tbl. | Huge Md. |  [ REAL  NAME ]  |
       |--------------+-------------+-----------------------------+
       |      No      |     No      |  No     > @Test@Process$qv  |
       |--------------+-------------+-----------------------------+
       |      No      |     Yes     |  No     > @Test@0Process$qv |
       |--------------+-------------+-----------------------------+
       |      Yes     |     No      |  No     > @Test@1Process$qv |
       |--------------+-------------+-----------------------------+
       |     Yes      |     No      |  Yes    > @Test@2Process$qv |
       +--------------+-------------+-----------------------------+
  ( NOTE:  Using the '_export' or 'huge' keyword when defining a
           class results in Far Virtual Tables for the class ).
  'Undefined Symbol Messages' caused by mismatching Virtual Table
  Controls or Object Data Calling conventions may be hard to
  identified;  it is often useful to use the TDUMP.EXE utility to
  find the actual names of the unresolved symbols:  watch out of
  any '0', '1' or '2' following the '@ClassName@' portion of the
  real names.
  LANGUAGE USED:
  ==============
       By default an assembler ( including TASM  ) does not modify
  public names, but merely converts them to upper case.  With TASM,
  the /mx option will force the assembler to treat public symbols
  with case sensitivity.  Without /mx, a call to _foo from an
  assembly module would look like _FOO to the linker, which could
  cause undefined symbols when linking C and assembly.  ( NOTE:
  TASM also has extension which will cause the automatic generation
  of underscores.  See. .MODEL , Language directives from
  your TASM manual ).
  As mentioned in the above section about 'Name Mangling', the C++
  language uses a different Naming Convention from the C language.
  This can result in undefined symbols when calling C from C++ ( or
  vice-versa ).  C++ modules should use the 'extern "C"' syntax
  when interfacing with C modules.  ( see. Name Mangling section of
  Programmer's Guide manual regarding the mentioned syntax ).
  LINKER SETTINGS:
  ================
       By default, the linker will treat _foo and _FOO as different
  symbols.  However, one can control whether the linker pays
  attention to Case Sensitivity via an option:
       The Option can be set via the Options | Linker | Settings
  dialog (IDE), or the /c option with TLINK. ( /c: Enables Case
  Sensitivity [default], /c- turns Option off).
       For example, if the option is disabled, a call to _foo could
  be resolved to _FoO.
       When creating a Windows application, not only can one link
  to 'static' modules ( .OBJs or .LIBs which are a collection of
  .OBJs), but one can also link to dynamic libraries ( i.e. the
  resolution of the call is completed by Windows at load time ).
  Functions residing in DLLs and called from one's EXE are said to
  be imported.  Functions that one codes in an .EXE or .DLL and
  which are called by Windows/Other Exes/DLLs are said to be
  exported.
       Functions are imported in two ways: by listing them in the
  IMPORTS section of the .DEF file, or by linking to an import
  library.  Functions can be exported by two methods: by using the
  _export keyword in the source code, or listing the functions in
  the EXPORTS section of the .DEF file.
       So suppose our App. calls a symbol _foo which is in a DLL.
  The linker can treat symbols coming from an import library, or
  IMPORTS section of the .DEF file with or without case
  sentitivity, ( determined by the setting of case sensitive
  exports under the Options | Linker | Settings Dialog or /C option
  on the TLINK command line ).  If this setting is NOT enabled,
  then the Linker treats symbols in import libs or IMPORTS sections
  as all uppercase.  It then considers these upper case symbols
  during the link phase.  At that point it is doing normal linking
  using the setting of the case sensitive link option.  If we are
  importing both _foo and _FOO without the /C option, the linker
  can only resolve the call to _FOO.
       If we are calling _foo, ( NOTE: foo is a cdecl function )
  and performing a case sensitive link, but do not have case
  sensitivity on EXPORTS, _foo will show up as undefined.
       > Imported cdecl functions and C++ names will link when /c
       > and /C are both enabled, or neither are enabled*.
  C++ names are always generated with lowercase letters.  When
  importing or exporting C++ names, it is recommended that one uses
  both the /c and /C options.
  Now let's apply the above to some common scenarios and provide
  possible diagnostics and suggestions:
  PROBLEM:
       All the functions in a 3rd party library are undefined!
  SOLUTION:
       3rd party libraries must be explicitly linked in.  To
  explicitly link to a 3rd party library from the IDE, open a
  project file and insert the .LIB file into the project file.
  The project file also needs to have all of your source code files
  listed in it.  From the command line, insert the .LIB on your
  command line to TLINK.
  PROBLEM:
       All the functions in the RTL are undefined!
  SOLUTION:
       You need to link in Cx.LIB, where x is the memory model.  A
  feature of the IDE in Turbo C++ and Borland C++ v2.x is that if
  you put a .LIB in the project file which starts out as Cx where x
  is a memory model, the new library overrides the normal run time
  library, and the latter will not be linked in ( e.g. using a
  library named CSERVE.LIB ).  Rename any such libraries, then the
  normal Cx.LIB will automaticly be linked in.  ( Borland C++ 3.x
  has a dialog for specifying if the Run Time Libraries should be
  linked in ).
  PROBLEM:
       When mixing C and C++ modules (.c and .cpp source) symbols
  are undefined.
  SOLUTION:
       Because of name mangling (see above) the symbol the linker
  sees being called from a C++ module will not look like the symbol
  in the C module.  To turn name mangling off when prototyping
  functions:
       // SOURCE.CPP
       extern "C" {
            int Cfunc1( void );
            int Cfunc2( int  );
       }
  NOTE:  You can also disable name-mangling for functions written
  in C++ and called from C.
       A C++ compile will happen if the source code has a .CPP
  extension, or Options | Compiler | C++ options use C++ compiler
  is set to always.
  PROBLEM:
       randomize and other macros are coming up as undefined
  symbols.
  SOLUTION:
       Turn keywords to Borland C++.  Since some macros are not
  ANSI compatible, the header files will not define them if
  compiled with ANSI, or UNIX keywords on.
  PROBLEM:
        min and max are coming up undefined.
  SOLUTION:
       These macros are only included in a C compile, and will not
  be seen by the compiler if compiling in C++.  In C, you must
  #include  to use them.
  PROBLEM:
       I cannot get my assembly modules to link with my C/C++
  program.
  SOLUTION:
       For C++, see above.  Otherwise, the .ASM must be assembled
  with case sensitivity on public symbols.  ( /mx for TASM ).  It
  must also match the C naming convention, which will have an
  underscore in front of the name.  So given,
       int foo(  void );
  in the C module, you need to
       call _foo
  from the assembly module.  (NOTE: TASM has extensions which will
  automatically generate underscores for you).  Also, make sure the
  .OBJ which has the assembly code is listed in the project file,
  or on the tlink line.
  PROBLEM:
       wsprintf is comming up undefined.
  SOLUTION:
       In Borland C++ 2.0, to use wsprintf when case sensitive
  exports is on, you need to reverse a define in windows.h via the
  following:
  #ifdef   wsprintf
  #undef   wsprintf
  #define  wsprintf wsprintf
  extern   "C" int FAR cdecl wsprintf( LPSTR, LPSTR, ... );
  #endif
  To call wsprintf (or any cdecl imported function ) with case
  sensitive exports off, you need to match an upper case name.
  Thus windows.h #defines wsprintf to be WSPRINTF.  wsprintf is one
  of the cdecl functions from windows, so the compiler will
  generate a lower case symbol for when calling it.
  PROBLEM:
       FIWRQQ and FIDRQQ are undefined
  SOLUTION:
       These symbols are in the EMU or FP87 library.  You must link
  it in explicitly when using TLINK, or set the IDE to link it in
  under the Options | Compiler | Advanced Code Generation Floating
  point box.
  PROBLEM:
       Warning attempt to export non-public symbol ...
  SOLUTION:
       The exports section of the .DEF file has a symbol which does
  not match one the compiler generated in the source code.  This
  will happen if:
       - The source was compile in C++ (the symbol name will be
         mangled).  Resolve by exporting with the _export keyword,
         compiling in C, or declaring the function as extern "C".
       - Case sensitive exports is ON, you are exporting a PASCAL
         function, and exporting it like:  WndProc.  Resolve by
         exporting as WNDPROC or by turning case sensitive exports
         off.
       - You are exporting a cdecl function.  If declared as
                 int foo( void );
         export as _foo and turn case sensitive exports on ( or
         just use the _export keyword).
       NOTE: When using the '_export' keyword, it must be used in
             the prototype of the function:
                 i.e. int FAR _export foo( int );
  PROBLEM:
       C++ and DLL linking problems.
  SOLUTION:
       classes declared in the DLL need to be declared as the
  following:
       class _export A
       {
            ...
       };
       When defined in the EXE, the same must be prototyped as:
       class huge A
       {
            ...
       };
       ( see user's guide for more info).
  Then, link with /c and /C on ( i.e. both case senstive link and
  case sensitive exports ENABLED ), when building BOTH the DLL and
  the calling EXE.
  PROBLEM:
       OWL and undefined symbols.
  SOLUTION:
       If linking to the static libraries:
            - with BC 2.0, link in owlwx.lib, tclasswx.lib, and
              sallocwx.lib. (You don't need sallocwx.lib with BC
              v 3.x ).
            - do NOT define _CLASSDLL in the code generation
              dialog, or before including owl.h.
            - link with /c and /C.  (from IDE, under linker
              options, case sensitive link and case sensitive
              exports).
            - Do NOT compile with -K or unsigned char's on.  You
              will get several undefined symbols in this case.
       If linking to the OWL DLL, DO define _CLASSDLL before
  including OWL.H  and use /c and /C linker options ( i.e. both
  Case Sensitive Link and Case Sensitive Exports ENABLED ).
  PROBLEM:
       With an OWL App., wsprintf is undefined in module when
       linking to the static libs.
  SOLUTION:
       Link with /C ( i.e. case sensitive exports ENABLED ).
  PROBLEM:
       _main is an undefined symbol.
  SOLUTION:
       main is the entry point for every C/C++ program.  Make sure
  you write a function called main (all lowercase) in your program.
  If you have a project file loaded, make sure your source code
  file (.c or .cpp file) which has main in it is listed in the .prj
  file.   Make sure generate underbars is turned on.
  PROBLEM:
       iostream members, like <