LoadLibraryW 函式（libloaderapi.h）

發行項
11/20/2024

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

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

語法

HMODULE LoadLibraryW(
  [in] LPCWSTR lpLibFileName
);

參數

[in] lpLibFileName

模組的名稱。這可以是連結庫模組（.dll 檔案）或可執行檔模組（.exe 檔案）。如果指定的模組是可執行的模組，則不會載入靜態匯入;而是使用 DONT_RESOLVE_DLL_REFERENCES 旗標 LoadLibraryEx 載入模組。

指定的名稱是模組的檔名，與儲存在連結庫模組本身的名稱無關，如 module-definition （.def）檔案中的 LIBRARY 關鍵詞所指定。

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

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

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

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

傳回值

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

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

言論

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

LoadLibrary 可用來將連結庫模組載入進程地址空間，並傳回可用於 getProcAddress GetProcAddress 中的句柄，以取得 DLL 函式的位址。 LoadLibrary 也可以用來載入其他可執行的模組。例如，函式可以指定 .exe 檔案，以取得可在 FindResource 或 LoadResource中使用的句柄。不過，請勿使用 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 搜尋順序的詳細資訊，請參閱 Dynamic-Link 連結庫搜尋順序。

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

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

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

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

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

安全性備註

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

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

例子

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

注意

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

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	libloaderapi.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll