LoadLibraryA 函式 (libloaderapi.h)

發行項
08/24/2023

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

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

語法

HMODULE LoadLibraryA(
  [in] LPCSTR lpLibFileName
);

參數

[in] lpLibFileName

模組的名稱。這可以是程式庫模組 (.dll 檔案) 或可執行檔模組 (.exe 檔案) 。如果指定的模組是可執行檔模組，則不會載入靜態匯入;而是使用旗標載入 LoadLibraryExDONT_RESOLVE_DLL_REFERENCES ，就像是載入模組一樣。

指定的名稱是模組的檔案名，與儲存在程式庫模組本身的名稱無關，如 module-definition (.def) 檔案中的 LIBRARY 關鍵字所指定。

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

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

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

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

傳回值

如果函式成功，則傳回值是模組的控制碼。

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

備註

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

LoadLibrary 可用來將程式庫模組載入進程的位址空間，並傳回可在 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。另一個進程必須在呼叫GetProcAddress之前，先對模組進行自己的LoadLibrary呼叫。

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

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

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

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

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

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

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

Windows Server 2003 和 Windows XP： Visual C++ 編譯器支援可讓您宣告執行緒區域變數的語法： _declspec (執行緒) 。如果您在 DLL 中使用此語法，您將無法在 Windows Vista 之前的 Windows 版本上明確地使用 LoadLibrary 載入 DLL。如果您的 DLL 會明確載入，您必須使用執行緒本機儲存體函式，而不是 _declspec (執行緒) 。如需範例，請參閱在動態連結程式庫中使用執行緒本機儲存體。

安全性備註

請勿使用 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 [僅限傳統型應用程式]
目標平台	Windows
標頭	libloaderapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll