Loads the specified module into the address space of the calling process. The specified module may cause other modules to be loaded.

Syntax

HMODULE WINAPI LoadLibraryEx(
  __in        LPCTSTR lpFileName,
  __reserved  HANDLE hFile,
  __in        DWORD dwFlags
);

Parameters

lpFileName [in]

The name of the module. This can be a library module (a .dll file) or an executable module (an .exe file). This name is the file name of the module; it is not related to the name stored in a library module itself, as specified by the LIBRARY keyword in the module-definition (.def) file.

If the string specifies a path, but the file does not exist in the specified directory, the function fails. When specifying a path, be sure to use backslashes (\), not forward slashes (/).

If the string does not specify a path, and the file name extension is omitted, the function appends the default library extension .dll to the file name. However, the file name string can include a trailing point character (.) to indicate that the module name has no extension.

If the string does not specify a path, the function uses a standard search strategy to find the file. See the Remarks for more information.

If loading the specified module into the address space causes the system to load other associated modules, the function can use either the standard search strategy or an alternate search strategy to find those modules. See the Remarks for more information.

If the specified module is an .exe file, static imports are not loaded; instead, the module is loaded as if DONT_RESOLVE_DLL_REFERENCES was specified. See the dwFlags parameter for more information.

hFile

This parameter is reserved for future use. It must be NULL.

dwFlags [in]

The action to be taken when loading the module. If no flags are specified, the behavior of this function is identical to that of the LoadLibrary function. This parameter can be one of the following values.

Value	Meaning
DONT_RESOLVE_DLL_REFERENCES 0x00000001	If this value is used, and the executable module is a DLL, the system does not call DllMain for process and thread initialization and termination. Also, the system does not load additional executable modules that are referenced by the specified module. Note  Use extreme care when using this value. If LoadLibrary or LoadLibraryEx is called for the same DLL after the DLL is loaded, then the DLL references will not have been resolved. This is because the second call to LoadLibrary or LoadLibraryEx simply returns a handle to the already loaded DLL. In this case, the process is likely to terminate abnormally. If you are planning only to access data or resources in the DLL, it is better to use LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE or LOAD_LIBRARY_AS_IMAGE_RESOURCE or both.
LOAD_IGNORE_CODE_AUTHZ_LEVEL 0x00000010	If this value is used, the system does not perform automatic trust comparisons on the DLL or its dependents when they are loaded. Windows 2000:  This value is not supported.
LOAD_LIBRARY_AS_DATAFILE 0x00000002	If this value is used, the system maps the file into the calling process's virtual address space as if it were a data file. Nothing is done to execute or prepare to execute the mapped file. Therefore, you cannot call functions like GetModuleFileName, GetModuleHandle or GetProcAddress with this DLL. Using this value causes writes to read-only memory to raise an access violation. Use this flag when you want to load a DLL only to extract messages or resources from it. This value can be used with LOAD_LIBRARY_AS_IMAGE_RESOURCE. For more information, see Remarks.
LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE 0x00000040	Similar to LOAD_LIBRARY_AS_DATAFILE, except that the DLL file on the disk is opened for exclusive write access. Therefore, other processes cannot open the DLL file for write access while it is in use. However, the DLL can still be opened by other processes. This value can be used with LOAD_LIBRARY_AS_IMAGE_RESOURCE. For more information, see Remarks. Windows Server 2003 and Windows XP/2000:  This value is not supported.
LOAD_LIBRARY_AS_IMAGE_RESOURCE 0x00000020	If this value is used, the system maps the file into the process's virtual address space as an image file. However, the loader does not load the static imports or perform the other usual initialization steps. Use this flag when you want to load a DLL only to extract messages or resources from it. Unless the application depends on the image layout, this value should be used with either LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE or LOAD_LIBRARY_AS_DATAFILE. For more information, see the Remarks section. Windows Server 2003 and Windows XP/2000:  This value is not supported.
LOAD_WITH_ALTERED_SEARCH_PATH 0x00000008	If this value is used and lpFileName specifies an absolute path, the system uses the alternate file search strategy discussed in the Remarks section to find associated executable modules that the specified module causes to be loaded. If this value is used and lpFileName specifies a relative path, the behavior is undefined. If this value is not used, or if lpFileName does not specify a path, the system uses the standard search strategy discussed in the Remarks section to find associated executable modules that the specified module causes to be loaded.

Return Value

If the function succeeds, the return value is a handle to the loaded module.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

Remarks

If lpFileName does not include a path and there is more than one loaded module with the same base name and extension, the function returns a handle to the module that was loaded first.

The calling process can use the handle returned by this function to identify the module in calls to the GetProcAddress, FindResource, and LoadResource functions.

To enable or disable error messages displayed by the loader during DLL loads, use the SetErrorMode function.

The LoadLibraryEx function is very similar to the LoadLibrary function. The differences consist of a set of optional behaviors that LoadLibraryEx provides. First, LoadLibraryEx can load a DLL module without calling the DllMain function of the DLL. Second, LoadLibraryEx can use either of two file search strategies to find modules that are associated with the specified module. Third, LoadLibraryEx can load a module in a way that is optimized for the case where the module will never be executed, loading the module as if it were a data file. You select these optional behaviors by setting the dwFlags parameter; if dwFlags is zero, LoadLibraryEx behaves identically to LoadLibrary.

The LOAD_LIBRARY_AS_DATAFILE, LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE, and LOAD_LIBRARY_AS_IMAGE_RESOURCE values affect the per-process reference count and the loading of the specified module. If any of these values is specified for the dwFlags parameter, the loader checks whether the module was already loaded by the process as an executable DLL. If so, this means that the module is already mapped into the virtual address space of the calling process. In this case, LoadLibraryEx returns a handle to the DLL and increments the DLL reference count. If the DLL module was not already loaded as a DLL, the system maps the module as a data or image file and not as a executable DLL. In this case, LoadLibraryEx returns a handle to the loaded data or image file but does not increment the reference count for the module.

If LoadLibraryEx is called twice for the same file with LOAD_LIBRARY_AS_DATAFILE, LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE, or LOAD_LIBRARY_AS_IMAGE_RESOURCE specified for the dwFlags parameter, two separate mappings are created for the file.

LOAD_LIBRARY_AS_DATAFILE does not prevent other processes from modifying the module while it is loaded. Because this can make your application less secure, you should use LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE instead of LOAD_LIBRARY_AS_DATAFILE when loading a module as a data file, unless you specifically need to use LOAD_LIBRARY_AS_DATAFILE. Specifying LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE prevents other processes from modifying the module while it is loaded. Do not specify LOAD_LIBRARY_AS_DATAFILE and LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE in the same call.

When the LOAD_LIBRARY_AS_IMAGE_RESOURCE value is used, the module is loaded as an image using portable executable (PE) section alignment expansion. Relative virtual addresses (RVA) do not have to be mapped to disk addresses, so resources can be more quickly retrieved from the module. Specifying LOAD_LIBRARY_AS_IMAGE_RESOURCE prevents other processes from modifying the module while it is loaded.

Unless an application depends on specific image mapping characteristics, the LOAD_LIBRARY_AS_IMAGE_RESOURCE value should be used with either LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE or LOAD_LIBRARY_AS_DATAFILE. This allows the loader to choose whether to load the module as an image resource or a data file, selecting whichever option enables the system to share pages more effectively. Resource functions such as FindResource can use either mapping.

To determine how a module was loaded, use one of the following macros to test the handle returned by LoadLibraryEx.

 #define LDR_IS_DATAFILE(handle)      (((ULONG_PTR)(handle)) &  (ULONG_PTR)1)
#define LDR_IS_IMAGEMAPPING(handle)  (((ULONG_PTR)(handle)) & (ULONG_PTR)2)
#define LDR_IS_RESOURCE(handle)      (LDR_IS_IMAGEMAPPING(x) || LDR_IS_DATAFILE(x))

The following table describes these macros.

The FreeLibrary function should be used to free a loaded module, whether or not loading the module caused its reference count to be incremented. If the module was loaded as a data or image file, the mapping is destroyed but the reference count is not decremented. Otherwise, the DLL reference count is decremented. Therefore, it is safe to call FreeLibrary with any handle returned by LoadLibraryEx.

It is not safe to call LoadLibraryEx from DllMain. For more information, see the Remarks section in DllMain.

The LoadLibraryEx function performs a standard search for modules if the file name is specified without a path and the base file name does not match the base file name of a loaded module, or there is a path specified but LOAD_WITH_ALTERED_SEARCH_PATH is not used. If a path is specified and dwFlags is set to LOAD_WITH_ALTERED_SEARCH_PATH, the LoadLibraryEx function uses an alternate file search strategy. The specified path must be an absolute path. LOAD_WITH_ALTERED_SEARCH_PATH does not work with relative paths. For more information about alternate search strategies, see Dynamic-Link Library Search Order.

The search path can be altered using the SetDllDirectory function. This solution is recommended instead of using SetCurrentDirectory or hard-coding the full path to the DLL.

If a path is specified and there is a redirection file associated with the application, the LoadLibraryEx function searches for the module in the application directory. If the module exists in the application directory, LoadLibraryEx ignores the path specification and loads the module from the application directory. If the module does not exist in the application directory, the function loads the module from the specified directory. For more information, see Dynamic Link Library Redirection.

If you call LoadLibraryEx with the name of an assembly without a path specification and the assembly is listed in the system compatible manifest, the call is automatically redirected to the side-by-side assembly.

Visual C++:  The Visual C++ compiler supports a syntax that enables you to declare thread-local variables: _declspec(thread). If you use this syntax in a DLL, you will not be able to load the DLL explicitly using LoadLibraryEx on versions of Windows prior to Windows Vista. If your DLL will be loaded explicitly, you must use the thread local storage functions instead of _declspec(thread). For an example, see Using Thread Local Storage in a Dynamic Link Library.

Examples

For an example, see Looking Up Text for Error Code Numbers.

Requirements

See Also

DllMain
Dynamic-Link Library Functions
FindResource
FreeLibrary
GetProcAddress
GetSystemDirectory
GetWindowsDirectory
LoadLibrary
LoadResource
OpenFile
Run-Time Dynamic Linking
SearchPath
SetDllDirectory
SetErrorMode

Send comments about this topic to Microsoft

Build date: 8/7/2008