The _DLL_InitTerm function (Windows)

Every time an instance of a DLL is loaded its environment must be initialized. When you are finished with the DLL, its environment must be terminated. You can accept the default initialization and termination, which is included automatically by default, or write your own initialization and termination function.

The initialization and termination function for subsystem and regular DLLs must have the following prototype:

unsigned long __stdcall _DLL_InitTerm(HINSTANCE hModule,
                                      DWORD ulFlag,
                                      LPVOID dummy);

The _DLL_InitTerm function must be compiled using __stdcall linkage, because it is called by the operating system loader.

The _DLL_InitTerm function has three parameters:

This function is also called when a thread is created or ends, in which case the ulFlag parameter is set to DLL_THREAD_ATTACH or DLL_THREAD_DETACH, respectively. For more details, refer to the DLLEntryPoint in the Win32 API Reference.

The return code from _DLL_InitTerm tells the loader if the initialization or termination was performed successfully. If the call was successful, _DLL_InitTerm returns a nonzero value. A return code of 0 indicates that the function failed.

You can perform any specialized initialization and termination you want. For example, you can set initial values to variables as part of the initialization. You must also make sure you initialize and terminate the environment properly. If you change a subsystem DLL at a later time to use the regular runtime libraries, you modify your _DLL_InitTerm function to ensure that the runtime environment is correctly initialized.

If you can accept the default initialization and termination done by _DLL_InitTerm and want just to perform specialized initialization and termination actions required by your DLL, you may find it easier to provide your own version of function DllMain and use the default _DLL_InitTerm function. The function DllMain has the same linkage, return type, and argument list as _DLL_InitTerm. The default _DLL_InitTerm calls DllMain. The default DllMain is an empty function.

Both _DLL_InitTerm and DllMain can call functions in the VisualAge C++ run-time library. If you provide just DllMain, you do not have to perform the following standard initialization and termination actions.

Initializing the Environment
You may have make three initializations for your DLL:

  1. If you are not building a subsystem DLL, you must initialize the run-time environment before you call any functions in the VisualAge C++ run-time library. Call _CRT_init before the call before you call any other library functions. Here is the prototype of _CRT_init:
    int _Optlink _CRT_init(void);
    If the run-time environment is successfully initialized, _CRT_init returns 0. A return code of -1 indicates an error. If an error occurs, an error message is written to file handle 2, which is the standard stream stderr.
  2. If your DLL contains C++ code, you call __ctordtorInit after _CRT_init to ensure that static constructors and destructors are initialized properly. Here is the prototype for __ctordtorInit:
    void __ctordtorInit(int flag);
    Calling _ctordtorInit with a value of 0 for flag causes constructors to be called for process initialization. Calling the function with a non-zero value for flag causes only constructors for thread-specific objects in the current thread to be called. In your DLL startup, you should call __ctordtorInit with a value of 0.
  3. If you are using subsystem memory in a subsystem DLL, call _rmem_init().

Terminating the Environment
You must call matching termination functions for the initialization functions:

  1. If your DLL contains C++ code, you must also call __ctordtorTerm before you call _CRT_term to ensure that static constructors and destructors are terminated correctly. Here is the prototype for __ctordtorTerm:
    void __ctordtorTerm(int flag);
    Calling __ctordtorTerm with a value of 0 for flag causes destructors to be called for process termination. Calling the function with a non-zero value for flag causes only destructors for thread-specific objects in the current thread to be called.
  2. If your DLL is statically linked and you are not using the subsystem library, you must use the _CRT_term function to correctly terminate the C runtime environment. Here is the prototype of _CRT_term:
    void _Optlink _CRT_term(void);
    After you have called _CRT_term, you cannot call any other library functions. If your DLL is dynamically linked, you cannot call library functions in the termination section of your _DLL_InitTerm function.
  3. If you are using subsystem memory in a subsystem DLL, call _rmem_term().

Example of a _DLL_InitTerm Function
Example of a Subsystem _DLL_InitTerm Function



Static and Dynamic Link Libraries
Subsystems
Run-Time Library Environments
Calling Conventions


Build Dynamic Link Libraries
Initialize and Terminate Your DLL environment
Build Subsystems


Subsysem Library Functions