Learning to write programs in C/C++


1. How does the Stringizing operator work in C/C++?

The C/C++ preprocessor recognizes various operators that convert tokens to strings. If the '#' character occurs at the start of a parameter on the right hand side of a #define statement, the corresponding argument is enclosed in quotes. For example:

  #define VERSION 100
  #define PRODUCT "Acme"
  #define _STR(i) #i
  #define STR(i)  _STR(i)

  i = VERSION;                // i=100
  strcpy(s1, _STR(VERSION));  // strcpy(s1, "VERSION");
  strcpy(s1, STR(VERSION));   // strcpy(s1, "100");
  strcpy(s1, _STR(PRODUCT));  // strcpy(s1, "PRODUCT");
  strcpy(s1, STR(PRODUCT));   // strcpy(s1, "\"Acme\"");

The _STR macro encloses its arguments in quotes, for example _STR(VERSION) expands to "VERSION". The STR macro (no underscore) is replaced by _STR with an underscore, but if its argument is a macro it will also cause the macro to be expanded. For example, STR(VERSION) expands to _STR(100) which is further expanded to "100".

Therefore in the code above, _STR causes any macro argument to be converted to a string, and STR causes the value of the macro to be converted to a string. Both are useful in different cases.

2. How do I write DLLs in C/C++ and call them from different languages?

Using Visual C/C++ to write a DLL

32 bit DLLs produced with Visual C/C++ should have functions with the modifiers "_declspec(dllexport)" and "_stdcall", interestingly both "_declspec" and "_stdcall" seem to work with one or two leading underscores. The "_declspec(dllexport)" modifier causes the function to be placed in the DLL exported names table without the use of a DEF file, although we return to this topic later. The "_stdcall" modifier makes the function use the standard calling convention which passes parameters from right to left and in which the called function cleans up the stack, as used by the Windows API and Visual Basic. DLLs are easier in 32 bit Windows as you do not have to worry about special compiler options to set up the registers correctly or the memory model. To export a function func from a DLL called "mydll.dll":

  #define EXPORT _declspec(dllexport)
  // CALLBACK is defined in the Windows header files
  // it is defined as __stdcall

  return_type EXPORT CALLBACK func(parameters)
  { ... }

To check the exported functions type:

  dumpbin /exports mydll.dll

To call this function from a Pascal program it must be prototyped as follows:

  function func(parameters):return_type; stdcall;
  function func; stdcall; external 'Mydll';

To explain these, the C code declares and exports func from source code that is compiled into a DLL. By using #define EXPORT and CALLBACK we can have the same code compiling for 16 and 32 bits. There is an MS KB article Q123870 "Portable DLL Example Using _declspec() and _export" which claims that "_declspec(dllexport)" should go before the function return type and will not work if positioned in the code as shown, however under Visual C/C++ this does not appear to be a problem. The Microsoft article was written for Visual C/C++ v1 and v2 so possibly Microsoft improved the compiler after the article. The CALLBACK macro chooses the proper calling convention for 16 and 32 bits, it basically means to pass the parameters in the same way they would be passed to an API function. WINAPI is equivalent to CALLBACK in 16 and 32 bit Windows.

After compiling the C DLL use "dumpbin.exe" supplied with Visual C/C++ to produce a list of all exported functions and check the proper functions are exported. Client code will not be able to call routines from the DLL that are not in the exported list. DLLs are name sensitive so the exact matching name must be used when calling into the DLL from Pascal or Visual Basic. Note that without a DEF file a function Fred will be exported as "_Fred@N" where N is the number of bytes passed on the stack, this is known as "stdcall name mangling" and is discussed later.

To call the function from Pascal the function is prototyped, then in the unit implementation it is declared as being external in the named DLL. The function name used in the external declaration must be a legal Pascal identifier, also it must be an exact case sensitive match for the function as exported from the DLL. This is what makes dumpbin so useful, as it is a way of checking the exported name. Pascal must use the stdcall parameter passing convention otherwise it defaults to optimized parameter passing which puts parameters in registers and is incompatible with the DLL. Also the types of the parameters used in the Pascal prototype must exactly match the actual parameters used by the function in the DLL, otherwise the call and the function will interpret the stack differently.

Stdcall name mangling

As discussed Visual C/C++ uses stdcall name mangling, which causes a function "Fred" to be exported as "_Fred@N" where N is the number of bytes of stack required. C++ uses more complex name mangling which is not discussed here. The stdcall name mangling is done to bring an element of type safety into C programs consisting of separate object modules linked together, as the linker will detect most cases in which a prototype or call uses the wrong numbers of parameters.

Unfortunately the stdcall name mangling is unacceptable for a generic DLL that is to be called from Pascal or Visual Basic, also it is not used by the Windows API DLLs as you can easily tell by running dumpbin on GDI32.DLL. Also the name mangling makes it difficult to call the DLL from Pascal as the function identifier cannot include the "@" sign. Thus we must undo the mangling by naming the exports in the DEF file. This uses an alias scheme whereby we give the mangled function name followed by the alias by which it is to be exported from the DLL, however the linker helps us by not requiring the alias if it can match up the name to the function without ambiguity. This means all we have to do is to list the un-mangled exported function names in the EXPORTS section using the same case as the functions were declared with. Thus "mydll.dll" above would have the following DEF file:

  LIBRARY "mydll"

When the DEF file is processed by the linker, it realizes we want to export the function using the name given (func), and it matches the export to the occurrence of func in the code. After undoing the mangling use dumpbin to read the names exactly as they are exported. Assuming the function is exported properly, it can be called from Pascal code as long as the exported Pascal identifier in the DLL interface unit exactly matches the name. Although Pascal identifiers are not case sensitive, this is a situation where the Pascal compiler uses the external function identifier exactly as it is written for load time linking to the DLL.

In theory both Pascal and Visual Basic can get round the mangling problem by using aliasing, which is a system in which the function name is followed by the real name as exported by the DLL. In Pascal use the "name" keyword or in Visual Basic use the "alias" keyword, followed by the mangled name exported from the DLL. But this is awkward since you have to know or work out the mangled names to alias them properly. Also it is not the standard way of writing DLLs, which should export functions without mangling the names. The Windows API DLLs export functions without mangling.

DLL callbacks and why WINAPI is the same as CALLBACK

It is possible to allow the DLL to make calls back into the client code, which is useful if you are writing a DLL to implement a callback function, or designing an event driven interface. The concept is the client calls a function in a DLL, passes the DLL a pointer to a function that resides in the client, and the DLL function will make calls back into the client using the pointer.

In essence this is the same situation as when a client calls into a DLL. Whether a call is made into a DLL, or a call is made from a DLL back into an EXE file, the called function should use the EXPORT CALLBACK (or EXPORT WINAPI) modifiers to ensure the function is in the DLLs exported names table and the parameters are passed correctly. This is why WINAPI and CALLBACK are equivalent, as in essence there is no difference between calling an API function which is in a DLL, and having the Windows DLL calling back into the application's EXE file or an application DLL. Thus we call CreateWindow which has the modifier WINAPI, and Windows may call one of our window functions or an enumeration callback, which have the modifiers CALLBACK.

Thus if we write a function func in a DLL that accepts a pointer to a function as one of its parameters, the DLL function will be able to make calls back into the calling EXE file. We are using callbacks in the same way that Windows does. When func has made its callback, the call tree will look something like this:

  callback_func (in the EXE file)
  func (in the DLL)
  main (in EXE file)

Function main starts by calling func which is in the DLL and passing a pointer to callback_func. In the DLL func uses the function pointer to call back into the EXE file. Then we are back in callback_func.

Other DLL issues

DLLs must support multi tasking because they may be used by several clients simultaneously. This means all data should be passed as parameters, or should be local variables (stack based) or should be attached to window (HWND) structures. Because the DLL resides in the caller's stack, the local variables will be correct for each of the DLL's clients. There is a Build - Settings - Libraries option which should be used to choose the multi threaded RTL.

DLLs reside on their caller's stack so they should conserve stack space. A stack overflow in the client will produce an error message from the client RTL, but a stack overflow in the DLL will produce an error message from the C RTL.

DLLs should not use any static or global data as they should be fully re-entrant allowing code to be simultaneously executed by different applications. However there is no objection to the DLL storing constant data in its data segment. In effect this happens anyway as string literals are stored in a read-only data segment common to all instances of the DLL.

Any windows and window classes created in the DLL belong to the hInstance that created the window or class. It is best if the client passes its hInstance and the DLL uses this to create the window / class, so that these resources are cleared up properly when the client terminates.

The DLL should not malloc/free memory because it will be managed by the DLL's own version of the C RTL. There would be a danger of memory being allocated in the client and freed in the DLL (or vice versa) which would cause problems because the two would use different memory block lists. If the DLL must allocate memory use GlobalAllocPtr() and GlobalFreePtr(), and balance the calls within the one DLL function. Memory allocated in a DLL with GlobalAllocPtr() belongs to the client app, and will thus be automatically freed when the client terminates.

Memory leaks in the DLL are potentially more serious because the DLL will only be unloaded and the blocks returned when all clients terminate. If there are problems whereby the DLL uses memory, look for an obscure MS tech note that discusses the heapmin function. It may be necessary to pack the heap to return the blocks.

Again the client and DLL have different run time libraries so there is no way file handles or any C run time low-level structures can be shared between the DLL and the caller. If the DLL has to operate on files, it should do so within a single function call and balance the calls to fopen/fclose.

Auto loading DLLs under Windows

Under Windows NT / 2000 / XP it is possible to specify DLLs that are loaded into the context of all processes when they start. This is useful for custom controls as they can initialize themselves in the DLL startup code. These DLLs are stored in the registry entry:

HKEY_LOCAL_MACHINE\ Software\ Microsoft\ Windows NT\ CurrentVersion\ Windows \ APPINIT_DLLS

Refer to "Window Classes in Win32", Kyle Marsh, MSDN for more details.

Using Visual C/C++ v1.5 to write a 16 bit DLL

The information in this section is kept for historical interest only. 32 bit Windows has been available from 1995, and 16 bit DLLs are obsolete.

In 16 bit Windows using Visual C/C++ v1.5, give functions the modifiers "_export" and "_far _pascal". The "_export" modifier causes the function to be placed in the DLL exported names table and ensures the registers are set up correctly when the function is called, by loading the DS register from a constant value set up in the DLL at load time (DS cannot be loaded from SS as DS != SS for a DLL). The "_far _pascal" modifiers use the normal DLL parameter passing convention, which specifies DLLs are in a separate segment ("_far") and that the "_pascal" parameter passing system is used, which is that parameters are passed left to right and that the called function cleans up the stack. These conventions are the ones used when calling DLLs from Delphi Pascal or Visual Basic. Also these conventions are used by the Windows API which are really just large DLLs with a defined interface.

Strictly speaking you can write DLLs without either "_export" or "_far _pascal", by naming the exported functions in a DEF file and relying on the default "_cdecl" parameter passing convention. Such a DLL could be called up from other C programs, or even from Pascal by using inline assembler and cleaning up the stack properly. But this is more complex, and for the purposes of this discussion we want to write generic DLLs that can be called from Pascal or Basic with as little work as possible. Thus in the rest of this discussion we assume the "_export" and "_far _pascal" modifiers are used. To export a function "func" from a DLL called "mydll.dll":

  #define EXPORT _export
  // CALLBACK is defined in the Windows header files
  // It is defined as _far _pascal

  return_type EXPORT CALLBACK func(parameters)
  { ... }

To check the exported functions type:

  exehdr /verbose mydll.dll

To call this function from a 16 bit Delphi Pascal program it must be prototyped as follows:

  function func(parameters):return_type;
  function func; external 'Mydll';

To explain these, the C code declares and exports func from source code that is compiled into a DLL. When compiling the DLL the large memory model (/ALw) should be used to avoid problems with near pointers that are a nasty hangover from Windows v3 real mode. Specify SS != DS as SS is the caller's DGROUP and DS is the DLL's DGROUP, and specify DS not loaded on entry, so the DLL can access its own DGROUP. Fixups are automatically set when the DLL is loaded so it can access its own data segment.

After compiling the C DLL use "exehdr.exe" supplied with Visual C/C++ v1.5 to produce a list of all exported functions to make sure the proper functions are exported. Client code will not be able to call routines from the DLL that are not in the exported list. The names in the list are not case sensitive and exehdr produces them all in upper case, thus an exported function MYFUNC can be successfully called from a Pascal function MyFunc. The same should also apply to 16 bit Visual Basic.

The 16 bit Delphi Pascal code will be placed in a unit that interfaces to the DLL. Normally a separate unit is produced for each DLL although this is not essential. First the unit declares a prototype for the function including all the parameters - the types of these must match the types expected by the function in the DLL. For example if a Delpi program specifies an integer followed by a string pointer, when Delphi calls the DLL function it will push a 2-byte integer then a 4-byte pointer onto the stack. In the DLL the function must be written to expect the same parameters, then it will interpret the stack frame as containing the same types and it will pop the same values off the stack when it returns. If the headers are mismatched the DLL function will receive and return bad data, and the stack will probably be misaligned on return, and the result will be the program will crash at a point sufficiently distant from the bad call so as to be confusing. To avoid this it is important to check the Pascal prototypes match the C prototypes.

16 bit code requires the LARGE memory model which supports multiple code segments and a single private DLL data segment. This model ensures we use versions of the C run time functions that cope with proper segmented (seg:ofs) 4 byte pointers, everything works properly and we never have to use the "near" or "far" keywords. It should be possible to grep the entire source to check "near" and "far" are not used anywhere. Any attempt to use other memory models or a mixed model is unnecessary and is a short cut to insanity. If enumeration callbacks such as EnumTaskWindows() and similar routines are used in a DLL they must also be declared EXPORT CALLBACK. The EXPORT keyword ensures the DS register is set correctly for 16 bits. Without EXPORT DS will be loaded from SS, which will cause the callback to use the wrong data segment when it is used from a DLL.

There is inconsistency between the same source compiled into a 16 bit and a 32 bit DLL, in that a 16 bit DLL shares its data between callers and a 32 bit DLL defaults to private data per caller. This would cause problems if a DLL used global variables as a 16 bit client would change the value for other 16 bit clients, but a 32 bit client could not set a global value that would be accessible to other 32 bit clients. In most cases this should not matter as DLLs should not use static or global variables - all data they use should be allocated and attached to windows, or passed as parameters.

If all functions are exported and prototyped correctly the Pascal code can call the C DLL as if it were an extension of its own code. This is the same way in which the Pascal RTL calls the Windows API functions - Borland provide a large import unit "windows.pas" which has external declarations for the entire API.

When using DLL callbacks (ie if the DLL calls back into the client EXE file), the usual compiler options have to be set. The DLL function func must have the EXPORT CALLBACK modifiers so the registers are set up correctly. In the DLL SS=client's SS, and DS=the DLL's own DGROUP. Thus SS!=DS and DS is not loaded from SS on entry applies for the DLL. Back in the EXE file the callback_func also needs to load DS on entry, as when the callback is made DS will be set to the DLLs DGROUP and DS will not equal SS, to fix this the callback function needs to load its DS from SS on entry. Otherwise unpleasentnesses will arise such as Windows calling a winproc in the client and using the DLL's DGROUP, or calling the DLL's winprocs with the client's DGROUP. This causes strange effects as constants are usually stored in DGROUP so if DS is wrongly set all the program's constants (usually string literals) will suddenly change their values.

When starting experiments with callbacks, it was useful to create a small function (CheckDS) that ensures the DS register has been correctly restored. CheckDS can be called at the start of DLL functions and the callback functions in the EXE file. A short string literal is declared which will automatically be put in DGROUP, then CheckDS checks the constant has the same value by getting and testing each character from the string literal. Then if the DS register has been changed the reference to the constant will pick out random data from someone else's DGROUP, the comparison test will fail and CheckDS can display a message box and halt.