Author: Embarcadero USA
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 |
Technical Information Database TI2407C.txt Linking to Functions in Third-Party DLLs Category :General Platform :All Product :Borland C++ All Description: Linking to Functions in Third-Party Dynamic Link Libraries ======= == ========= == =========== ======= ==== ========= The use of dynamic link libraries, or DLLs, is fundamental to Windows programming. Windows itself is a set of DLLs; when you call a Windows API function in your program, Windows finds the address of the function at run-time. Dynamic linking is not limited to Windows API calls;any library used for static linking can be rebuilt as a DLL. One advantage of DLLs is that they share a common file format, which is not the case for static libraries. Frequently, third-party static libraries such as Microsoft's use file formats that cannot be read by TLINK. If the same library is available in DLL form, linking will usually be possible. This document discusses two methods for linking to functions in a DLL: 1) import libraries, and 2) module definition files. It also addresses "undefined symbol" messages when attempting to link DLLs and gives methods for resolving these errors. Import Libraries ------ --------- An import library contains linker symbols for the function names in a DLL and reference information which the linker uses to construct a table in your .EXE file. At run-time, Windows uses the table to resolve function calls. You already use an import library whenever you write a Windows program: the library IMPORT.LIB is linked into your application to resolve calls to the Windows API functions. (To see this in your project, set the "Show run-time nodes" option under Options | Environment | Project View). To build an import library for a DLL, use the IMPLIB utility: IMPLIB LibName DLLName where "LibName" is the name of the import library and "DLLName" is the name of the DLL you wish to link to. Then add the import library to your project to link to the DLL. Undefined Symbols --------- ------- Of course, just as with static linking, there is no guarantee that the linker symbols generated by your compiler in your .OBJ file will match the linker symbols in the import library. The most common cause of "undefined symbol" error messages during linking is a language mismatch -- your program is written in C++, and the DLL is written in C. Extern C ------ - For most compilers, linker symbols in C are generated by simply prepending an underbar to the function name. In C++, a more sophisticated scheme must be used to generate a unique symbol for each declaration of an overloaded function; this is called "name mangling." Unfortunately, name mangling is not standardized, but varies from one compiler vendor to another. DLL vendors, aware of this problem, generally try to write their products in C to facilitate linking. However, if you are writing a C++ program, the compiler will automatically generate name-mangled symbols for all function names unless you explicitly tell it otherwise. To turn off name mangling for a function name, declare the function as extern "C": extern "C" void YourFunctionName(int); If you are linking with multiple functions in a header file, you can wrap the include directive within an extern "C" declaration: extern "C" { #include "somedll.h" }; Calling Conventions ------- ----------- What if the extern "C" declaration still leaves you with an undefined symbol? The first thing to check is whether you are using the correct calling convention in your function declaration. If you think you are not using a calling convention, you're wrong -- the compiler is assuming a default calling convention. The calling convention tells the compiler how parameters are pushed on the stack, and how the stack is cleaned up upon returning from a function call. It also tells the compiler how to generate linker symbols. In Borland C++, the default calling convention is cdecl, where parameters are pushed on the stack from right to left and the caller cleans up the stack. If you're programming in 16 bits, however, you will often attempt to link with functions that use the same calling convention as the 16-bit Windows API -- pascal, in which parameters are pushed on the stack from left to right and the called function cleans up the stack. The cdecl convention produces symbols that have a leading underscore and are case sensitive. The pascal convention produces symbols that have no leading underscore and are not case sensitive -- i.e., all letters are uppercase. In the 32-bit world, a different kind of mismatch is common. The stdcall calling convention, used by the 32-bit Windows API, produces symbols that are case sensitive, but with no leading underscore. It is sometimes possible to force a symbol match by changing compiler and linker options, but you have to be careful: you need to match calling conventions as well as symbols. Suppose that while you're compiling in 16 bits, you turn off the compiler option to generate underbars (Options | Project | Compiler | Compiler Output) and you find that the undefined symbol messages for the functions in your DLL have disappeared. You're probably safe, because most likely the DLL functions use the cdecl calling convention, and the DLL compiler did not generate leading underbars. But if you're compiling in 32 bits, you've probably got a mismatch in calling conventions -- most likely, the DLL functions use the stdcall convention. Borland C++ provides keywords that enable you to inform the compiler of the appropriate calling convention for a function. For example, a declaration for an externally defined pascal function would look like this: void _far _pascal YourFunctionName(int); (The _far modifier tells the compiler that the function definition is in a far data segment, always the case with 16-bit DLLs.) For a stdcall function, the declaration would be void __stdcall YourFunctionName(int); For portability, you may use the WINAPI macro for both declarations: void WINAPI YourFunctionName(int); WINAPI is defined as _far _pascal in 16 bits, and __stdcall in 32 bits. Seeing What the Linker Sees ------ ---- --- ------ ---- If you have been unable to resolve an undefined symbol with the methods discussed so far, it's time to look and see what linker symbols are being generated by the compiler and compare them with those in the DLL. Borland C++ has two tools for this purpose: TDUMP and IMPDEF. Run TDUMP on your .OBJ file with the -m option to show C++ name mangling and the -oiextdef option to show externally defined symbols. You can also use -oipubdef to see what symbols are being made public by an .obj file. tdump -m -oiextdef yourobj.obj > yourobj.lst It should be an easy matter to identify the "undefined symbols" the linker is complaining about. With name mangling (-m option) turned on, TDUMP shows a symbol as the linker sees it, with additional characters appearing before and after the function name. For example, the function declaration extern void foo() becomes @foo$qv IMPDEF takes two parameters, the name of a module definition file for the DLL, and the name of the DLL. impdef somedll.def somedll.dll The output of IMPDEF is the module definition file somedll.def, which contains an "EXPORTS" section listing the linker symbol for each exported function, followed by an ordinal value of the function. You'll probably recognize the function you're trying to link to, and see why the linker is having trouble; the function name within the symbol is the same, but the characters in which it is embedded, if any, are different. Resolving Undefined Symbols with Module Definition Files --------- --------- ------- ---- ------ ---------- ----- Let's say the DLL's compiler uses a different name-mangling convention, and has written the symbol for foo() as &foo%xy. How do you tell the linker that @foo$qv is the same as &foo%xy ? It can easily be done by aliasing the symbol in your program's module definition file. Edit the file to create an "IMPORTS" section, and list each undefined symbol, followed by an equal sign, the name of the DLL's module definition file without the extension, and the symbol as it appears in that file. For example, if &foo%xy appears in the EXPORTS section of SOMEDLL.DEF, you would alias @foo$qv as follows: @foo$qv=SOMEDLL.&foo%xy References ---------- For further information, see TI 1029, Resolving Undefined Linker Symbol Messages. Reference: 7/2/98 10:40:50 AM |
Learn how to utilize constexpr variables and constexpr functions in this tutorial.
Article originally contributed by Borland Staff
Reduce development time and get to market faster with RAD Studio, Delphi, or C++Builder.
Design. Code. Compile. Deploy.
Start Free Trial Upgrade Today
Free Delphi Community Edition Free C++Builder Community Edition
Design. Code. Compile. Deploy.
Start Free Trial Upgrade Today
Free Delphi Community Edition Free C++Builder Community Edition
