LoadLibraryExW function (libloaderapi.h)

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

Syntax

HMODULE LoadLibraryExW(
  [in] LPCWSTR lpLibFileName,
       HANDLE  hFile,
  [in] DWORD   dwFlags
);

Parameters

[in] lpLibFileName

A string that specifies the file name of the module to load. This name is not related to the name stored in a library module itself, as specified by the LIBRARY keyword in the module-definition (.def) file.

The module can be a library module (a .dll file) or an executable module (an .exe file). If the specified module is an executable module, 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.

If the string specifies a module name without a path and the file name extension is omitted, and the module name does not contain any point character (.), then the function appends the default library extension ".DLL" to the module name. To prevent the function from appending ".DLL" to the module name, include a trailing point character (.) in the module name string.

If the string specifies a fully qualified path, the function searches only that path for the module. When specifying a path, be sure to use backslashes (\), not forward slashes (/). For more information about paths, see Naming Files, Paths, and Namespaces.

If the string specifies a module name without a path and more than one loaded module has the same base name and extension, the function returns a handle to the module that was loaded first.

If the string specifies a module name without a path and a module of the same name is not already loaded, or if the string specifies a module name with a relative path, the function searches for the specified module. The function also searches for modules if loading the specified module causes the system to load other associated modules (that is, if the module has dependencies). The directories that are searched and the order in which they are searched depend on the specified path and the dwFlags parameter. For more information, see Remarks.

If the function cannot find the module or one of its dependencies, the function fails.

hFile

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

[in] dwFlags

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.

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

The LoadLibraryEx function is very similar to the LoadLibrary function. The differences consist of a set of optional behaviors that LoadLibraryEx provides:

• LoadLibraryEx can load a DLL module without calling the DllMain function of the DLL.
• 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.
• LoadLibraryEx can find modules and their associated modules by using either of two search strategies or it can search a process-specific set of directories.

The calling process can use the handle returned by LoadLibraryEx 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.

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

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.

Loading a DLL as a Data File or Image Resource

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, two separate mappings are created for the file.

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(handle) || LDR_IS_DATAFILE(handle))

The following table describes these macros.

Use the FreeLibrary function 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.

Searching for DLLs and Dependencies

The LoadLibraryEx function uses the standard search path in the following cases:

• The file name is specified without a path and the base file name does not match the base file name of a loaded module, and none of the LOAD_LIBRARY_SEARCH flags are used.
• A path is specified but LOAD_WITH_ALTERED_SEARCH_PATH is not used.
• The application has not specified a default DLL search path for the process using SetDefaultDllDirectories.

If lpFileName specifies a relative path, the entire relative path is appended to every token in the DLL search path. To load a module from a relative path without searching any other path, use GetFullPathName to get a nonrelative path and call LoadLibraryEx with the nonrelative path. If the module is being loaded as a datafile and the relative path starts with "." or "..", the relative path is treated as an absolute path.

If lpFileName specifies an absolute path and dwFlags is set to LOAD_WITH_ALTERED_SEARCH_PATH, LoadLibraryEx uses the altered search path. The behavior is undefined when LOAD_WITH_ALTERED_SEARCH_PATH flag is set, and lpFileName specifies a relative path.

The SetDllDirectory function can be used to modify the search path. This solution is better than using SetCurrentDirectory or hard-coding the full path to the DLL. However, be aware that using SetDllDirectory effectively disables safe DLL search mode while the specified directory is in the search path and it is not thread safe. If possible, it is best to use AddDllDirectory to modify a default process search path. For more information, see Dynamic-Link Library Search Order.

An application can specify the directories to search for a single LoadLibraryEx call by using the LOAD_LIBRARY_SEARCH_* flags. If more than one LOAD_LIBRARY_SEARCH flag is specified, the directories are searched in the following order:

• The directory that contains the DLL (LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR). This directory is searched only for dependencies of the DLL to be loaded.
• The application directory (LOAD_LIBRARY_SEARCH_APPLICATION_DIR).
• Paths explicitly added to the application search path with the AddDllDirectory function (LOAD_LIBRARY_SEARCH_USER_DIRS) or the SetDllDirectory function. If more than one path has been added, the order in which the paths are searched is unspecified.
• The System32 directory (LOAD_LIBRARY_SEARCH_SYSTEM32).

Windows 7, Windows Server 2008 R2, Windows Vista and Windows Server 2008:  The LOAD_LIBRARY_SEARCH_ flags are available on systems that have KB2533623 installed. To determine whether the flags are available, use GetProcAddress to get the address of the AddDllDirectory, RemoveDllDirectory, or SetDefaultDllDirectories function. If GetProcAddress succeeds, the LOAD_LIBRARY_SEARCH_ flags can be used with LoadLibraryEx.

If the application has used the SetDefaultDllDirectories function to establish a DLL search path for the process and none of the LOAD_LIBRARY_SEARCH_* flags are used, the LoadLibraryEx function uses the process DLL search path instead of the standard search path.

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.

Security Remarks

Do not use the SearchPath function to retrieve a path to a DLL for a subsequent LoadLibraryEx call. The SearchPath function uses a different search order than LoadLibraryEx and it does not use safe process search mode unless this is explicitly enabled by calling SetSearchPathMode with BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Therefore, SearchPath is likely to first search the user's current working directory for the specified DLL. If an attacker has copied a malicious version of a DLL into the current working directory, the path retrieved by SearchPath will point to the malicious DLL, which LoadLibraryEx will then load.

Do not make assumptions about the operating system version based on a LoadLibraryEx call that searches for a DLL. If the application is running in an environment where the DLL is legitimately not present but a malicious version of the DLL is in the search path, the malicious version of the DLL may be loaded. Instead, use the recommended techniques described in Getting the System Version.

For a general discussion of DLL security issues, see Dynamic-Link Library Security.

Examples

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

Requirements

See also

DllMain

Dynamic-Link Library Functions

Dynamic-Link Library Search Order

Dynamic-Link Library Security

FindResource

FreeLibrary

GetProcAddress

GetSystemDirectory

GetWindowsDirectory

LoadLibrary

LoadResource

OpenFile

Run-Time Dynamic Linking

SearchPath

SetDllDirectory

SetErrorMode