An optional entry point into a dynamic-link library (DLL). When the system starts or terminates a process or thread, it calls the entry-point function for each loaded DLL using the first thread of the process. The system also calls the entry-point function for a DLL when it is loaded or unloaded using theLoadLibrary[ http://msdn2.microsoft.com/ko-kr/library/ms684175.aspx ] andFreeLibrary[ http://msdn2.microsoft.com/ko-kr/library/ms683152.aspx ] functions.
Warning There are serious limits on what you can do in a DLL entry point. To provide more complex initialization, create an initialization routine for the DLL. You can require applications to call the initialization routine before calling any other routines in the DLL. Alternatively, the initialization routine can create a file with an ACL that restricts access, and each routine in the DLL would call the initialization routine if the file does not exist.
BOOL WINAPI DllMain( HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpvReserved );
Parameters
- hinstDLL
- [in] Handle to the DLL module. The value is the base address of the DLL. TheHINSTANCEof a DLL is the same as theHMODULEof the DLL, sohinstDLLcan be used in calls to functions that require a module handle.
- fdwReason
- [in] Indicates why the DLL entry-point function is being called. This parameter can be one of the following values.
| Value | Meaning |
|---|
DLL_PROCESS_ATTACH
1 | The DLL is being loaded into the virtual address space of the current process as a result of the process starting up or as a result of a call toLoadLibrary. DLLs can use this opportunity to initialize any instance data or to use theTlsAlloc[ http://msdn2.microsoft.com/ko-kr/library/ms686801.aspx ] function to allocate a thread local storage (TLS) index. |
DLL_THREAD_ATTACH
2 | The current process is creating a new thread. When this occurs, the system calls the entry-point function of all DLLs currently attached to the process. The call is made in the context of the new thread. DLLs can use this opportunity to initialize a TLS slot for the thread. A thread calling the DLL entry-point function with DLL_PROCESS_ATTACH does not call the DLL entry-point function with DLL_THREAD_ATTACH. Note that a DLL's entry-point function is called with this value only by threads created after the DLL is loaded by the process. When a DLL is loaded usingLoadLibrary, existing threads do not call the entry-point function of the newly loaded DLL. |
DLL_THREAD_DETACH
3 | A thread is exiting cleanly. If the DLL has stored a pointer to allocated memory in a TLS slot, it should use this opportunity to free the memory. The system calls the entry-point function of all currently loaded DLLs with this value. The call is made in the context of the exiting thread. |
DLL_PROCESS_DETACH
0 | The DLL is being unloaded from the virtual address space of the calling process as a result of unsuccessfully loading the DLL, termination of the process, or a call toFreeLibrary[ http://msdn2.microsoft.com/ko-kr/library/ms683152.aspx ] . The DLL can use this opportunity to call theTlsFree[ http://msdn2.microsoft.com/ko-kr/library/ms686804.aspx ] function to free any TLS indices allocated by usingTlsAllocand to free any thread local data. Note that the thread that receives the DLL_PROCESS_DETACH notification is not necessarily the same thread that received the DLL_PROCESS_ATTACH notification. |
- lpvReserved
- [in] IffdwReasonis DLL_PROCESS_ATTACH,lpvReservedis NULL for dynamic loads and non-NULL for static loads.
IffdwReasonis DLL_PROCESS_DETACH,lpvReservedis NULL ifFreeLibraryhas been called or the DLL load failed and non-NULL if the process is terminating.
Return Value
When the system calls theDllMainfunction with the DLL_PROCESS_ATTACH value, the function returns TRUE if it succeeds or FALSE if initialization fails. If the return value is FALSE whenDllMainis called because the process uses theLoadLibraryfunction,LoadLibraryreturns NULL. (The system immediately calls your entry-point function with DLL_PROCESS_DETACH and unloads the DLL.) If the return value is FALSE whenDllMainis called during process initialization, the process terminates with an error. To get extended error information, callGetLastError[ http://msdn2.microsoft.com/ko-kr/library/ms679360.aspx ] .
When the system calls theDllMainfunction with any value other than DLL_PROCESS_ATTACH, the return value is ignored.
Remarks
DllMainis a placeholder for the library-defined function name. You must specify the actual name you use when you build your DLL. For more information, see the documentation included with your development tools.
During initial process startup or after a call toLoadLibrary, the system scans the list of loaded DLLs for the process. For each DLL that has not already been called with the DLL_PROCESS_ATTACH value, the system calls the DLL's entry-point function. This call is made in the context of the thread that caused the process address space to change, such as the primary thread of the process or the thread that calledLoadLibrary. Access to the entry point is serialized by the system on a process-wide basis. Threads inDllMainhold the loader lock so no additional DLLs can be dynamically loaded or initialized.
If the DLL's entry-point function returns FALSE following a DLL_PROCESS_ATTACH notification, it receives a DLL_PROCESS_DETACH notification and the DLL is unloaded immediately. However, if the DLL_PROCESS_ATTACH code throws an exception, the entry-point function will not receive the DLL_PROCESS_DETACH notification.
There are cases in which the entry-point function is called for a terminating thread even if the entry-point function was never called with DLL_THREAD_ATTACH for the thread:
- The thread was the initial thread in the process, so the system called the entry-point function with the DLL_PROCESS_ATTACH value.
- The thread was already running when a call to theLoadLibraryfunction was made, so the system never called the entry-point function for it.
When a DLL is unloaded from a process as a result of an unsuccessful load of the DLL, termination of the process, or a call toFreeLibrary[ http://msdn2.microsoft.com/ko-kr/library/ms683152.aspx ] , the system does not call the DLL's entry-point function with the DLL_THREAD_DETACH value for the individual threads of the process. The DLL is only sent a DLL_PROCESS_DETACH notification. DLLs can take this opportunity to clean up all resources for all threads known to the DLL.
If you terminate a process by callingTerminateProcess[ http://msdn2.microsoft.com/ko-kr/library/ms686714.aspx ] orTerminateJobObject[ http://msdn2.microsoft.com/ko-kr/library/ms686709.aspx ] , the DLLs of that process do not receive DLL_PROCESS_DETACH notifications. If you terminate a thread by callingTerminateThread[ http://msdn2.microsoft.com/ko-kr/library/ms686717.aspx ] , the DLLs of that thread do not receive DLL_THREAD_DETACH notifications.
The entry-point function should perform only simple initialization or termination tasks. It must not call theLoadLibrary[ http://msdn2.microsoft.com/ko-kr/library/ms684175.aspx ] orLoadLibraryEx[ http://msdn2.microsoft.com/ko-kr/library/ms684179.aspx ] function (or a function that calls these functions), because this may create dependency loops in the DLL load order. This can result in a DLL being used before the system has executed its initialization code. Similarly, the entry-point function must not call theFreeLibrary[ http://msdn2.microsoft.com/ko-kr/library/ms683152.aspx ] function (or a function that callsFreeLibrary) during process termination, because this can result in a DLL being used after the system has executed its termination code.
Because Kernel32.dll is guaranteed to be loaded in the process address space when the entry-point function is called, calling functions in Kernel32.dll does not result in the DLL being used before its initialization code has been executed. Therefore, the entry-point function can call functions in Kernel32.dll that do not load other DLLs. For example,DllMaincan createsynchronization objects[ http://msdn2.microsoft.com/ko-kr/library/ms686364.aspx ] such as critical sections and mutexes, and use TLS. Unfortunately, there is not a comprehensive list of safe functions in Kernel32.dll.
Windows 2000: Do not create a named synchronization object inDllMainbecause the system will then load an additional DLL. This restriction does not apply to subsequent versions of Windows.
Calling functions that require DLLs other than Kernel32.dll may result in problems that are difficult to diagnose. For example, calling User, Shell, and COM functions can cause access violation errors, because some functions load other system components. Conversely, calling functions such as these during termination can cause access violation errors because the corresponding component may already have been unloaded or uninitialized.
Because DLL notifications are serialized, entry-point functions should not attempt to communicate with other threads or processes. Deadlocks may occur as a result.
For information on best practices when writing a DLL, seehttp://www.microsoft.com/whdc/driver/kernel/DLL_bestprac.mspx[ http://www.microsoft.com/whdc/driver/kernel/dll_bestprac.mspx ] .
If your DLL is linked with the C run-time library (CRT), the entry point provided by the CRT calls the constructors and destructors for global and static C++ objects. Therefore, these restrictions forDllMainalso apply to constructors and destructors and any code that is called from them.
Example Code
For an example, seeDynamic-Link Library Entry-Point Function[ http://msdn2.microsoft.com/ko-kr/library/ms682596.aspx ] .
Requirements
| Client | Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation, Windows Me, Windows 98, or Windows 95. |
|---|
| Server | Requires Windows Server "Longhorn", Windows Server 2003, Windows 2000 Server, or Windows NT Server. |
|---|
See Also
Dynamic-Link Library Entry-Point Function[ http://msdn2.microsoft.com/ko-kr/library/ms682596.aspx ]
Dynamic-Link Library Functions[ http://msdn2.microsoft.com/ko-kr/library/ms682599.aspx ]
FreeLibrary[ http://msdn2.microsoft.com/ko-kr/library/ms683152.aspx ]
GetModuleFileName[ http://msdn2.microsoft.com/ko-kr/library/ms683197.aspx ]
LoadLibrary[ http://msdn2.microsoft.com/ko-kr/library/ms684175.aspx ]
TlsAlloc[ http://msdn2.microsoft.com/ko-kr/library/ms686801.aspx ]
TlsFree[ http://msdn2.microsoft.com/ko-kr/library/ms686804.aspx ]