Applies to: desktop apps only
Adds a directory to the search path used to locate DLLs for the application.
Syntax
BOOL WINAPI SetDllDirectory( __in_opt LPCTSTR lpPathName );
Parameters
- lpPathName [in, optional]
-
The directory to be added to the search path. If this parameter is an empty string (""), the call removes the current directory from the default DLL search order. If this parameter is NULL, the function restores the default search order.
Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
The SetDllDirectory function affects all subsequent calls to the LoadLibrary and LoadLibraryEx functions. It also effectively disables safe DLL search mode while the specified directory is in the search path.
After calling SetDllDirectory, the standard DLL search path is:
- The directory from which the application loaded.
- The directory specified by the lpPathName parameter.
- The system directory. Use the GetSystemDirectory function to get the path of this directory. The name of this directory is System32.
- The 16-bit system directory. There is no function that obtains the path of this directory, but it is searched. The name of this directory is System.
- The Windows directory. Use the GetWindowsDirectory function to get the path of this directory.
- The directories that are listed in the PATH environment variable.
Each time the SetDllDirectory function is called, it replaces the directory specified in the previous SetDllDirectory call. To specify more than one directory, use the AddDllDirectory function and call LoadLibraryEx with LOAD_LIBRARY_SEARCH_USER_DIRS.
To revert to the standard search path used by LoadLibrary and LoadLibraryEx, call SetDllDirectory with NULL. This also restores safe DLL search mode based on the SafeDllSearchMode registry value.
To compile an application that uses this function, define _WIN32_WINNT as 0x0502 or later. For more information, see Using the Windows Headers.
Requirements
|
Minimum supported client | Windows Vista, Windows XP with SP1 |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | SetDllDirectoryW (Unicode) and SetDllDirectoryA (ANSI) |
See also
- AddDllDirectory
- Dynamic-Link Library Search Order
- GetDllDirectory
- GetSystemDirectory
- GetWindowsDirectory
- LoadLibrary
- LoadLibraryEx
Send comments about this topic to Microsoft
Build date: 3/6/2012
When you launch a child process and Windows searches for its implicitly-linked DLL dependencies, whether or not the current directory is searched depends on whether or not your process (i.e. the parent of the one just launched) has called SetDllDirectory("").
In other words, if you make your own process more secure by calling SetDllDirectory(""), you may in turn break child processes which require the unsecure setting.
Equally, whether or not that DLL lookup is done in a secure way when your own process starts is up to the whim of the process that creates you.
This doesn't affect dynamic linking, i.e. LoadLibrary; that is still up to each process by itself. The inheritance issue only affects how implicitly-linked DLLs are found.
It seems to me that it would make sense to have an exe-manifest setting which (subject to the CWDIllegalInDllSearch registry setting's override), forces the CWD into or out of the DLL search path, and which takes effect from the moment the process is started, rather than the moment control passes to user-written code. That would also fix problems where framework code (such as MFC until a recent patch) does unsafe LoadLibrary calls during startup, before user-written code has had a chance to call SetDllDirectory.
I have written about this issue in more detail, including a C++ project you can use to verify what I've said, here:
http://www.pretentiousname.com/setdlldirectory_inheritance/index.html