LoadLibraryExA 関数 (libloaderapi.h)
指定したモジュールを呼び出し元プロセスのアドレス空間に読み込みます。 指定されたモジュールによって、他のモジュールが読み込まれる可能性があります。
構文
HMODULE LoadLibraryExA(
[in] LPCSTR lpLibFileName,
HANDLE hFile,
[in] DWORD dwFlags
);
パラメーター
[in] lpLibFileName
読み込むモジュールのファイル名を指定する文字列。 この名前は、モジュール定義 (.def) ファイルの LIBRARY キーワードで指定されているように、ライブラリ モジュール自体に格納されている名前とは関係ありません。
モジュールには、ライブラリ モジュール (.dll ファイル) または実行可能モジュール (.exe ファイル) を指定できます。 指定したモジュールが実行可能モジュールの場合、静的インポートは読み込まれません。代わりに、DONT_RESOLVE_DLL_REFERENCES が指定されたかのようにモジュールが読み込まれます。 詳細については、dwFlags パラメーターを参照してください。
文字列でパスのないモジュール名を指定し、ファイル名拡張子を省略すると、既定のライブラリ拡張機能 ".DLL" がモジュール名に追加されます。 関数がモジュール名に ".DLL" を追加しないようにするには、モジュール名の文字列に末尾のポイント文字 (.) を含めます。
文字列で完全修飾パスが指定されている場合、関数はそのパスのみを検索してモジュールを検索します。 パスを指定するときは、スラッシュ (/) ではなく円記号 (\) を使用してください。 パスの詳細については、「名前付けファイル、パス、および名前空間を参照してください。
文字列がパスのないモジュール名を指定し、読み込まれた複数のモジュールが同じベース名と拡張子を持つ場合、関数は最初に読み込まれたモジュールにハンドルを返します。
文字列でパスのないモジュール名を指定し、同じ名前のモジュールがまだ読み込まれていない場合、または文字列で相対パスを持つモジュール名を指定した場合、関数は指定されたモジュールを検索します。 この関数は、指定されたモジュールを読み込むと、システムが他の関連モジュール (つまり、モジュールに依存関係がある場合) を読み込む場合にも、モジュールを検索します。 検索されるディレクトリと検索順序は、指定されたパスと dwFlags パラメーターによって異なります。 詳細については、「解説」を参照してください。
関数がモジュールまたはその依存関係の 1 つを見つけられない場合、関数は失敗します。
hFile
このパラメーターは、将来使用するために予約されています。 これは NULL
[in] dwFlags
モジュールの読み込み時に実行するアクション。 フラグが指定されていない場合、この関数の動作は、LoadLibrary 関数の動作と同じです。 このパラメーターには、次のいずれかの値を指定できます。
| 価値 | 意味 |
|---|---|
|
この値が使用され、実行可能モジュールが DLL の場合、システムはプロセスとスレッドの初期化と終了のために dllMain
注 この値は使用しないでください。これは下位互換性のためにのみ提供されます。 DLL 内のデータまたはリソースにのみアクセスする場合は、LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE または LOAD_LIBRARY_AS_IMAGE_RESOURCE またはその両方を使用します。 それ以外の場合は、LoadLibrary 関数を使用して、ライブラリを DLL または実行可能モジュールとして読み込みます。
|
|
この値を使用した場合、システムは AppLocker 規則 Windows Server 2008 R2 および Windows 7: KB2532445がインストールされているシステムでは、呼び出し元が "LocalSystem" または "TrustedInstaller" として実行されている必要があります。それ以外の場合、システムはこのフラグを無視します。 詳細については、https://support.microsoft.com/kb/2532445のヘルプおよびサポート サポート サポート 技術情報の「Windows 7 または Windows Server 2008 R2 を実行しているコンピューターで Office マクロを使用して AppLocker ルールを回避できます」を参照してください。 Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: AppLocker は、Windows 7 および Windows Server 2008 R2 で導入されました。 |
|
この値を使用すると、システムは、データ ファイルであるかのように、呼び出し元プロセスの仮想アドレス空間にファイルをマップします。 マップされたファイルの実行または実行の準備は何も行われません。 そのため、 この値は、LOAD_LIBRARY_AS_IMAGE_RESOURCEと共に使用できます。 詳細については、「解説」を参照してください。 |
|
LOAD_LIBRARY_AS_DATAFILEと同様です。ただし、呼び出し元プロセスの排他的書き込みアクセス権で DLL ファイルが開かれている点が異なります。 他のプロセスでは、使用中に DLL ファイルを書き込みアクセス用に開くことができません。 ただし、DLL は引き続き他のプロセスによって開くことができます。
この値は、LOAD_LIBRARY_AS_IMAGE_RESOURCEと共に使用できます。 詳細については、「解説」を参照してください。 Windows Server 2003 および Windows XP: この値は、Windows Vista までサポートされていません。 |
|
この値を使用すると、システムはファイルをプロセスの仮想アドレス空間にイメージ ファイルとしてマップします。
ただし、ローダーは静的インポートを読み込んだり、他の通常の初期化手順を実行したりしません。 DLL を読み込んでメッセージまたはリソースを抽出する場合にのみ、このフラグを使用します。
アプリケーションがイメージのメモリ内レイアウトを持つファイルに依存しない限り、この値は LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE または LOAD_LIBRARY_AS_DATAFILEで使用する必要があります。 詳細については、「解説」セクションを参照してください。 Windows Server 2003 および Windows XP: この値は、Windows Vista までサポートされていません。 |
|
この値を使用すると、アプリケーションのインストール ディレクトリで DLL とその依存関係が検索されます。 標準の検索パス内のディレクトリは検索されません。 この値を LOAD_WITH_ALTERED_SEARCH_PATHと組み合わせることはできません。
Windows 7、Windows Server 2008 R2、Windows Vista および Windows Server 2008: この値をインストールするには、KB2533623 が必要です。 Windows Server 2003 および Windows XP: この値はサポートされていません。 |
|
この値は、LOAD_LIBRARY_SEARCH_APPLICATION_DIR、LOAD_LIBRARY_SEARCH_SYSTEM32、および LOAD_LIBRARY_SEARCH_USER_DIRSの組み合わせです。 標準の検索パス内のディレクトリは検索されません。 この値を LOAD_WITH_ALTERED_SEARCH_PATHと組み合わせることはできません。
この値は、アプリケーションが DLL 検索パスに含める必要があるディレクトリの推奨最大数を表します。 Windows 7、Windows Server 2008 R2、Windows Vista および Windows Server 2008: この値をインストールするには、KB2533623 が必要です。 Windows Server 2003 および Windows XP: この値はサポートされていません。 |
|
この値を使用すると、DLL を含むディレクトリが、DLL の依存関係を検索するディレクトリの一覧の先頭に一時的に追加されます。 標準の検索パス内のディレクトリは検索されません。
lpFileName パラメーターには、完全修飾パスを指定する必要があります。 この値を LOAD_WITH_ALTERED_SEARCH_PATHと組み合わせることはできません。 たとえば、Lib2.dll が C:\Dir1 でのみ C:\Dir1\Lib1.dll, loading Lib1.dll with this value causes the system to search for Lib2.dll の依存関係である場合です。 C:\Dir1 内の Lib2.dll と DLL 検索パス内のすべてのディレクトリを検索するには、この値を LOAD_LIBRARY_SEARCH_DEFAULT_DIRSと組み合わせます。 Windows 7、Windows Server 2008 R2、Windows Vista および Windows Server 2008: この値をインストールするには、KB2533623 が必要です。 Windows Server 2003 および Windows XP: この値はサポートされていません。 |
|
この値を使用すると、%windows%\system32 が DLL とその依存関係を検索します。
標準の検索パス内のディレクトリは検索されません。 この値を LOAD_WITH_ALTERED_SEARCH_PATHと組み合わせることはできません。
Windows 7、Windows Server 2008 R2、Windows Vista および Windows Server 2008: この値をインストールするには、KB2533623 が必要です。 Windows Server 2003 および Windows XP: この値はサポートされていません。 |
|
この値を使用すると、AddDllDirectory または SetDllDirectory 関数を使用して追加されたディレクトリが、DLL とその依存関係を検索します。 複数のディレクトリが追加されている場合、ディレクトリの検索順序は指定されません。 標準の検索パス内のディレクトリは検索されません。 この値を LOAD_WITH_ALTERED_SEARCH_PATHと組み合わせることはできません。
Windows 7、Windows Server 2008 R2、Windows Vista および Windows Server 2008: この値をインストールするには、KB2533623 が必要です。 Windows Server 2003 および Windows XP: この値はサポートされていません。 |
|
この値を使用し、lpFileName この値を使用しない場合、または lpFileName この値を LOAD_LIBRARY_SEARCH フラグと組み合わせることはできません。 |
|
読み込み時にバイナリ イメージのデジタル署名をチェックする必要があることを指定します。
この値には、Windows 8.1、Windows 10 以降が必要です。 |
|
この値を使用する場合、現在のディレクトリから実行する DLL の読み込みは、安全な読み込みリスト内のディレクトリの下にある場合にのみ許可されます。 |
戻り値
関数が成功した場合、戻り値は読み込まれたモジュールへのハンドルです。
関数が失敗した場合、戻り値は NULL
備考
LoadLibraryEx 関数は、LoadLibrary 関数とよく似ています。 違いは、LoadLibraryEx が提供
- LoadLibraryEx は、DLL の DllMain 関数を呼び出さずに DLL モジュールを読み込むことができます。
- LoadLibraryEx は、モジュールが実行されない場合に最適化された方法でモジュールを読み込み、データ ファイルであるかのようにモジュールを読み込むことができます。
- LoadLibraryEx では、2 つの検索方法のいずれかを使用してモジュールとそれに関連付けられているモジュールを検索できます。また、プロセス固有のディレクトリ セットを検索することもできます。
呼び出し元のプロセスでは、
DLL の読み込み中にローダーによって表示されるエラー メッセージを有効または無効にするには、SetErrorMode 関数を使用します。
Visual C++: Visual C++ コンパイラでは、スレッド ローカル変数 (_declspec(スレッド)を宣言できる構文がサポートされています。 DLL でこの構文を使用する場合、Windows Vista より前のバージョンの Windows LoadLibraryEx を使用して DLL を明示的に読み込むことができなくなります。 DLL が明示的に読み込まれる場合は、_declspec(スレッド)の代わりにスレッド ローカル ストレージ関数を使用する必要があります。 例については、「ダイナミック リンク ライブラリでのスレッド ローカル ストレージの使用の
データ ファイルまたはイメージ リソースとして DLL を読み込む
LOAD_LIBRARY_AS_DATAFILE、LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE、および LOAD_LIBRARY_AS_IMAGE_RESOURCE の値は、プロセスごとの参照カウントと、指定したモジュールの読み込みに影響します。 dwFlags パラメーターにこれらの値のいずれかが指定されている場合、ローダーは、モジュールが実行可能 DLL としてプロセスによって既に読み込まれているかどうかを確認します。 その場合は、モジュールが呼び出し元プロセスの仮想アドレス空間に既にマップされていることを意味します。 この場合、LoadLibraryExLoadLibraryEx が、LOAD_LIBRARY_AS_DATAFILE、LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE、または LOAD_LIBRARY_AS_IMAGE_RESOURCEを持つ同じファイルに対して 2 回呼び出されると、ファイルに対して 2 つの個別のマッピングが作成されます。
LOAD_LIBRARY_AS_IMAGE_RESOURCE 値を使用すると、ポータブル実行可能 (PE) セクション配置拡張を使用して、モジュールがイメージとして読み込まれます。 相対仮想アドレス (RVA) をディスク アドレスにマップする必要がないため、モジュールからリソースをより迅速に取得できます。 LOAD_LIBRARY_AS_IMAGE_RESOURCE を指定すると、モジュールの読み込み中に他のプロセスがモジュールを変更できなくなります。
アプリケーションが特定のイメージ マッピング特性に依存しない限り、LOAD_LIBRARY_AS_IMAGE_RESOURCE 値は LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE または LOAD_LIBRARY_AS_DATAFILEで使用する必要があります。 これにより、ローダーはモジュールをイメージ リソースとして読み込むかデータ ファイルとして読み込むかを選択し、システムがページをより効果的に共有できるようにするオプションを選択できます。 FindResource などのリソース関数では、どちらのマッピングも使用できます。
モジュールの読み込み方法を確認するには、次のいずれかのマクロを使用して、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))
次の表では、これらのマクロについて説明します。
| マクロ | 形容 |
|---|---|
| LDR_IS_DATAFILE(ハンドル) | このマクロが TRUE |
| LDR_IS_IMAGEMAPPING(ハンドル) | このマクロが TRUE |
| LDR_IS_RESOURCE(ハンドル) | このマクロが TRUE |
FreeLibrary 関数を使用して、読み込まれたモジュールを解放します。モジュールを読み込んだ場合に、その参照カウントがインクリメントされたかどうかに関係なく、 モジュールがデータまたはイメージ ファイルとして読み込まれた場合、マッピングは破棄されますが、参照カウントはデクリメントされません。 それ以外の場合は、DLL 参照カウントがデクリメントされます。 したがって、LoadLibraryExによって返されるハンドルを使用して、FreeLibrary を呼び出しても安全です。
DLL と依存関係の検索
検索パスは、DLL を検索するディレクトリのセットです。LoadLibraryEx 関数は、次の場合に標準の検索パスを使用します。
- ファイル名はパスなしで指定され、ベース ファイル名は読み込まれたモジュールのベース ファイル名と一致せず、LOAD_LIBRARY_SEARCH フラグは使用されません。
- パスは指定されていますが、LOAD_WITH_ALTERED_SEARCH_PATH は使用されません。
- アプリケーションで、setDefaultDllDirectoriesを使用するプロセスの既定の DLL 検索パス
指定されていません。
lpFileName
SetDllDirectory 関数を使用して、検索パスを変更できます。 このソリューションは、SetCurrentDirectory を使用するか、DLL への完全なパスをハードコーディングするよりも優れています。 ただし、SetDllDirectory を使用すると、指定したディレクトリが検索パスにあり、スレッド セーフではない間、安全な DLL 検索モードが効果的に無効になることに注意してください。 可能であれば、AddDllDirectory を使用して、既定のプロセス検索パスを変更することをお勧めします。 詳細については、「Dynamic-Link ライブラリの検索順序」を参照してください。
アプリケーションでは、LOAD_LIBRARY_SEARCH_* フラグを使用して、1 つの LoadLibraryEx 呼び出しを検索するディレクトリを指定できます。 複数の LOAD_LIBRARY_SEARCH フラグが指定されている場合、ディレクトリは次の順序で検索されます。
- DLL (LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR) を含むディレクトリ。 このディレクトリは、読み込まれる DLL の依存関係のみを検索します。
- アプリケーション ディレクトリ (LOAD_LIBRARY_SEARCH_APPLICATION_DIR)。
- AddDllDirectory 関数 (LOAD_LIBRARY_SEARCH_USER_DIRS) または SetDllDirectory 関数を使用して、アプリケーション検索パスに明示的に追加されたパス。 複数のパスが追加されている場合、パスの検索順序は指定されません。
- System32 ディレクトリ (LOAD_LIBRARY_SEARCH_SYSTEM32)。
Windows 7、Windows Server 2008 R2、Windows Vista および Windows Server 2008: KB2533623 がインストールされているシステムで LOAD_LIBRARY_SEARCH_ フラグを使用できます。 フラグが使用可能かどうかを判断するには、GetProcAddress
アプリケーションが SetDefaultDllDirectories 関数を使用してプロセスの DLL 検索パスを確立し、LOAD_LIBRARY_SEARCH_* フラグが使用されていない場合、LoadLibraryEx 関数は標準検索パスではなくプロセス DLL 検索パスを使用します。
パスが指定されていて、アプリケーションに関連付けられているリダイレクト ファイルがある場合、loadLibraryEx 関数
パス指定のないアセンブリの名前 LoadLibraryEx を呼び出し、アセンブリがシステム互換マニフェストに一覧表示されている場合、呼び出しはサイド バイ サイド アセンブリに自動的にリダイレクトされます。
セキュリティに関する備考
LOAD_LIBRARY_AS_DATAFILE は、他のプロセスがモジュールの読み込み中にモジュールを変更することを妨げません。 これにより、アプリケーションの安全性が低下する可能性があるため、LOAD_LIBRARY_AS_DATAFILEを特に使用する必要がない限り、モジュールをデータ ファイルとして読み込むときに LOAD_LIBRARY_AS_DATAFILE の代わりに LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE を使用する必要があります。 LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE を指定すると、他のプロセスがモジュールの読み込み中にモジュールを変更できなくなります。 同じ呼び出しで LOAD_LIBRARY_AS_DATAFILE と LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE を指定しないでください。DLL を検索する LoadLibraryEx 呼び出しに基づいて、オペレーティング システムのバージョンを想定しないでください。 DLL が正当に存在しないが、DLL の悪意のあるバージョンが検索パスにある環境でアプリケーションが実行されている場合は、悪意のあるバージョンの DLL が読み込まれる可能性があります。 代わりに、「システム バージョンのの取得
DLL のセキュリティに関する問題の一般的な説明については、「Dynamic-Link ライブラリ セキュリティ」を参照してください。
例
次のコード例は、LoadLibraryExAを
//Load the FMAPI DLL
hLib = ::LoadLibraryEx(L"fmapi.dll", NULL, NULL);
if ( !hLib )
{
wprintf(L"Could not load fmapi.dll, Error #%d.\n", GetLastError());
return;
}
その他の例については、「エラー コード番号のテキストの検索」を参照してください。
手記
libloaderapi.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして LoadLibraryEx を定義します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP [デスクトップ アプリのみ] |
| サポートされる最小サーバー | Windows Server 2003 [デスクトップ アプリのみ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | libloaderapi.h (Windows.h を含む) |
| ライブラリ | Kernel32.lib |
| DLL | Kernel32.dll |
関連項目
FindResource の
GetSystemDirectory の
GetWindowsDirectory の
LoadResource の
動的リンク の
SetErrorMode の