_DLL_InitTerm -- Initialize and Terminate DLL Environment

Format

unsigned long __stdcall
_DLL_InitTerm(HINSTANCE modhandle,
                              DWORD flag, LPVOID dummy);
/* no header file - defined in runtime startup code */

Language Level: Extension
_DLL_InitTerm is the initialization and termination entry point for a DLL. When each new process or thread gains access to the DLL, _DLL_InitTerm initializes the necessary environment for the DLL, including storage, semaphores, and variables. When each process or thread frees its access to the DLL, _DLL_InitTerm terminates the DLL environment created for that process or thread.

The default _DLL_InitTerm function supplied by IBM C and C++ Compilers performs the actions required to initialize and terminate the runtime environment, or for subsystem DLLs, to initialize and terminate memory functions. It is called automatically when you link to the DLL. If your DLL requires initialization or termination actions in addition to the actions performed in the default function, you will need to create your own _DLL_InitTerm function.

If the value of the flag parameter, on OS/2, is 0, the DLL environment is initialized. If the value of the flag parameter is 1, the DLL environment is ended.

On Windows, the flag parameter has four values defined in windows.h. If the value of the flag parameter is:

DLL_PROCESS_ATTACH The DLL environment is initialized
DLL_PROCESS_DETACH The DLL environment is ended
DLL_THREAD_ATTACH A new thread that can access the DLL has been created in the process.
DLL_THREAD_DETACH A thread has terminated

The modhandle parameter is the module handle assigned by the operating system for this DLL. For Windows, you can use the module handle as a parameter to various Win32 API calls. For example, you can call GetModuleFileName with the module handle to return the fully-qualified path name of the DLL, which tells you where the DLL was loaded from.

On OS/2, you can use the module handle as a parameter to various OS/2 API calls. For example, you can call DosQueryModuleName with the module handle to return with the fully-qualified path name of the DLL, which tells you where the DLL was loaded from. Because it is called by the operating system loader, you must compile your _DLL_InitTerm function with _System linkage.

On Windows, because it is called by the operating system loader, you must compile your _DLL_InitTerm function with __stdcall linkage.

Note: A _DLL_InitTerm function for a subsystem DLL has the same prototype, but the content of the function is different because there is no runtime environment to initialize or terminate.

Return Value
The return code is significant only when the value of the flag parameter is DLL_PROCESS_ATTACH. The return code from _DLL_InitTerm tells the loader if the initialization was performed successfully. If the call was successful, _DLL_InitTerm returns a nonzero value. A return code of 0 indicates that the function failed. If a failure is indicated, the loader will not load the program that is accessing the DLL.

This function is also called by the operating system in thread creation and termination. When the value of the flag parameter is DLL_THREAD_ATTACH, a new THREAD has been created in the process. When the value of the flag parameter is DLL_THREAD_DETACH, a thread has terminated.

Examples



Create a Dynamic Link Library


_CRT_init -- Initialize DLL Runtime Environment
_CRT_term -- Terminate DLL Runtime Environment
_rmem_init -- Initialize Memory Functions for Subsystem DLL
_rmem_term -- Terminate Memory Functions for Subsystem DLL
_tmem_init -- Initialize Memory Functions for Subsystem DLL
_tmem_term -- Terminate Memory Functions for Subsystem DLL
/Ge compiler option