Share via


LoadLibraryW 函式 (libloaderapi.h)

將指定的模組載入呼叫行程的位址空間。 指定的模組可能會導致載入其他模組。

如需其他載入選項,請使用 LoadLibraryEx 函 式。

語法

HMODULE LoadLibraryW(
  [in] LPCWSTR lpLibFileName
);

參數

[in] lpLibFileName

模組的名稱。 這可以是連結庫模組, (.dll 檔案) 或可執行檔模組, (.exe 檔案) 。 如果指定的模組是可執行的模組,則不會載入靜態匯入;相反地,系統會使用 旗標載入 LoadLibraryEx ,就像是載入模組 DONT_RESOLVE_DLL_REFERENCES 一樣。

指定的名稱是模組的檔名,與儲存在連結庫模組本身的名稱無關,如模塊定義 (.def) 檔案中的 LIBRARY 關鍵詞所指定。

如果字串指定完整路徑,函式只會搜尋模組的路徑。

如果字串指定相對路徑或沒有路徑的模組名稱,則函式會使用標準搜尋策略來尋找模組;如需詳細資訊,請參閱。

如果函式找不到模組,則函式會失敗。 指定路徑時,請務必使用反斜杠 (\) ,而不是 (/) 斜線。 如需路徑的詳細資訊,請參閱 命名檔案或目錄

如果字串指定沒有路徑的模組名稱,而且省略擴展名,函式會將預設連結庫擴展名 「.DLL」 附加至模組名稱。 若要防止函式將 「.DLL」 附加至模組名稱,請在模組名稱字串中包含尾端點字元 (.) 。

傳回值

如果函式成功,則傳回值是模組的句柄。

如果函式失敗,傳回值為NULL。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

備註

若要在 DLL 載入期間啟用或停用載入器所顯示的錯誤訊息,請使用 SetErrorMode 函式。

LoadLibrary 可用來將連結庫模組載入進程的地址空間,並傳回可用於 GetProcAddress 的句柄,以取得 DLL 函式的位址。 LoadLibrary 也可以用來載入其他可執行的模組。 例如,函式可以指定 .exe 檔案,以取得可在 FindResourceLoadResource 中使用的句柄。 不過,請勿使用 LoadLibrary 來執行 .exe 檔案。 請改用 CreateProcess 函式。

如果指定的模組是尚未載入呼叫進程的 DLL,則系統會使用 DLL_PROCESS_ATTACH 值呼叫 DLL 的 DllMain 函式。 如果 DllMain 傳回 TRUE,LoadLibrary 會傳回模組的句柄。 如果 DllMain 傳回 FALSE,系統會從進程地址空間卸除 DLL,而 LoadLibrary 會傳回 NULL。 從 DllMain 呼叫 LoadLibrary 並不安全。 如需詳細資訊,請參閱 DllMain 中的一節。

模組句柄不是全域或可繼承的。 一個進程的 LoadLibrary 呼叫不會產生另一個進程可以使用的句柄,例如,在呼叫 GetProcAddress 時。 另一個進程必須先對模組進行自己的 LoadLibrary 呼叫,才能呼叫 GetProcAddress

如果 lpFileName 不包含路徑,而且有多個載入的模組具有相同基底名稱和延伸模組,則函式會傳回第一次載入之模組的句柄。

如果未在 lpFileName 參數中指定擴展名,則會附加預設連結庫擴展名 .dll。 不過,檔名字符串可以包含尾端點字元 (.) ,以指出模組名稱沒有擴展名。 未指定路徑時,函式會搜尋基底名稱符合要載入之模組基底名稱的已載入模組。 如果名稱相符,載入就會成功。 否則,函式會搜尋檔案。

搜尋的第一個目錄是包含用來建立呼叫進程 (映射檔的目錄,如需詳細資訊,請參閱 CreateProcess 函式) 。 這樣做可讓私人動態連結庫 (DLL) 與進程相關聯的檔案找到,而不需將進程的已安裝目錄新增至PATH環境變數。 如果指定相對路徑,則會將整個相對路徑附加至 DLL 搜尋路徑清單中的每個標記。 若要從相對路徑載入模組而不搜尋任何其他路徑,請使用 GetFullPathName 取得非關係路徑,並使用非關係路徑呼叫 LoadLibrary 。 如需 DLL 搜尋順序的詳細資訊,請參閱 動態連結庫搜尋順序

您可以使用 SetDllDirectory 函式來改變搜尋路徑。 建議使用此解決方案,而不是使用 SetCurrentDirectory 或硬式編碼 DLL 的完整路徑。

如果指定路徑,而且應用程式有重新導向檔案,則函式會搜尋應用程式目錄中的模組。 如果模組存在於應用程式的目錄中, LoadLibrary 會忽略指定的路徑,並從應用程式的目錄載入模組。 如果模組不存在於應用程式的目錄中, LoadLibrary 會從指定的目錄載入模組。 如需詳細資訊,請參閱 動態連結庫重新導向

如果您以沒有路徑規格的元件名稱呼叫 LoadLibrary ,而且元件列在系統相容指令清單中,則會自動將呼叫重新導向至並存元件。

系統會在所有載入的模組上維護每個進程參考計數。 呼叫 LoadLibrary 會遞增參考計數。 呼叫 FreeLibraryFreeLibraryAndExitThread 函式會遞減參考計數。 當模組的參考計數達到零或進程終止 (時,不論參考計數) 為何,系統都會卸除模組。

Windows Server 2003 和 Windows XP: Visual C++ 編譯程式支援可讓您宣告線程局部變數的語法: _declspec (线程) 。 如果您在 DLL 中使用這個語法,您將無法在 Windows Vista 之前的 Windows 版本上明確地使用 LoadLibrary 載入 DLL。 如果您的 DLL 會明確載入,您必須使用線程本機記憶體函式,而不是 _declspec (线程) 。 如需範例,請參閱 在動態連結庫中使用線程本機記憶體

安全性備註

請勿使用 SearchPath 函式來擷取後續 LoadLibrary 呼叫之 DLL 的路徑。 SearchPath 函式會使用與 LoadLibrary 不同的搜尋順序,而且除非透過呼叫 SetSearchPathModeBASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE 明確啟用此搜尋模式,否則不會使用安全進程搜尋模式。 因此, SearchPath 可能先搜尋使用者目前的工作目錄以尋找指定的 DLL。 如果攻擊者已將惡意版本的 DLL 複製到目前的工作目錄中, SearchPath 所擷取的路徑會指向 載入載 的惡意 DLL。

請勿根據搜尋 DLL 的 LoadLibrary 呼叫來假設操作系統版本。 如果應用程式在 DLL 合法不存在但 DLL 惡意版本位於搜尋路徑的環境中執行,可能會載入 DLL 的惡意版本。 請改用 取得系統版本中所述的建議技術。

範例

如需範例,請參閱 使用 Run-Time 動態連結

注意

libloaderapi.h 標頭會將 LoadLibrary 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例

規格需求

需求
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限桌面應用程式]
目標平台 Windows
標頭 libloaderapi.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

DllMain

動態連結庫函式

FindResource

FreeLibrary

GetProcAddress

GetSystemDirectory

GetWindowsDirectory

LoadLibraryEx

LoadResource

運行時間動態連結

SetDllDirectory

SetErrorMode