PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 1/14 TITLE : Resolving Undefined Symbol linker messages. 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 ) PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 2/14 TITLE : Resolving Undefined Symbol linker messages. 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 PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 3/14 TITLE : Resolving Undefined Symbol linker messages. 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 PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 4/14 TITLE : Resolving Undefined Symbol linker messages. 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 ) PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 5/14 TITLE : Resolving Undefined Symbol linker messages. { 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 PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 6/14 TITLE : Resolving Undefined Symbol linker messages. 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 PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 7/14 TITLE : Resolving Undefined Symbol linker messages. 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 PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 8/14 TITLE : Resolving Undefined Symbol linker messages. 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. PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 9/14 TITLE : Resolving Undefined Symbol linker messages. 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 PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 10/14 TITLE : Resolving Undefined Symbol linker messages. #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). PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 11/14 TITLE : Resolving Undefined Symbol linker messages. 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 PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 12/14 TITLE : Resolving Undefined Symbol linker messages. 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 << operator are undefined SOLUTION: turn options | compiler | code generation | unsigned chars off ( do not use -K on the command line). PROBLEM: PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 13/14 TITLE : Resolving Undefined Symbol linker messages. Getting undefined symbols LLSH, SCOPY FMUL, FDIV, etc SOLUTION: Many of the helper functions have changed names from Turbo C 2.0 to Borland C++. This functions were called from Turbo C 2.0. The solution is to recompile any .OBJ or .LIB them with Borland C++. SNOOPING AT THE REAL NAMES: =========================== An .OBJ file is a collection of records. When you call a function, or reference a symbol not defined in your module, the compiler generates an external definition record in the OBJ. This external definition record has the symbol which the linker must resolve. When you define a function, or make storage for some data, the compiler generates a public definition record for that module (unless you declared the item as static, that makes it private to that module). One of the tasks of the Linker is to match Public Definitions and External Definitions ( PUBDEFs and EXTDEFs ). To see the symbols the LINKER has to deal with, use the TDUMP.EXE utility provided with the Borland C++ package: e.g. tdump -m -oiEXTDEF some.obj The above will show all the EXTDEF (external definition) records in an obj. Be sure to add the -m option when coding in C++. e.g. tdump -m -oiPUBDEF some.obj The above will display all the PUBDEF (public definition) records. Let's assume you've purchased a third party library and a symbol provided the the library is unresolved; the possible steps in identifying the problem could include: - Create a Listing of symbols in the Library using TLIB PRODUCT : Borland C++ NUMBER : 1029 VERSION : 3.x OS : ANY DATE : October 19, 1993 PAGE : 14/14 TITLE : Resolving Undefined Symbol linker messages. eg. TLIB NEWLIB.LIB,NEWLIB.LST - TDUMP the .OBJ file which was created from the .C/.CPP module calling the desired function. eg. TDUMP -m -oiEXTDEF MYCODE.OBJ MYCODE.LST - Attempt to find any discrepancies between the name in NEWLIB.LST and the one in MYCODE.LST and ascertain that the Library does indeed provide the desired function. Windows Programmers will find the IMPDEF.EXE utility ( in addition to TDUMP and TLIB ) a very useful tool to help identify unresolved symbols when DLLs and/or Import Libraries are involved.