MapViewOfFileEx 関数 (memoryapi.h)
ファイル マッピングのビューを呼び出し元プロセスのアドレス空間にマップします。 呼び出し元は、必要に応じてビューの推奨ベース メモリ アドレスを指定できます。
物理メモリの NUMA ノードを指定するには、「 MapViewOfFileExNuma」を参照してください。
構文
LPVOID MapViewOfFileEx(
[in] HANDLE hFileMappingObject,
[in] DWORD dwDesiredAccess,
[in] DWORD dwFileOffsetHigh,
[in] DWORD dwFileOffsetLow,
[in] SIZE_T dwNumberOfBytesToMap,
[in, optional] LPVOID lpBaseAddress
);
パラメーター
[in] hFileMappingObject
ファイル マッピング オブジェクトへのハンドル。 CreateFileMapping 関数と OpenFileMapping 関数は、このハンドルを返します。
[in] dwDesiredAccess
ページのページ保護を決定するファイル マッピング オブジェクトへのアクセスの種類。 このパラメーターには、次の値のいずれか、または必要に応じて複数の値のビットごとの OR の組み合わせを指定できます。
ビットごとの OR を使用すると、上記の値とこれらの値を組み合わせることができます。
| 値 | 意味 |
|---|---|
|
ファイルの書き込み時のコピー ビューがマップされます。 ファイル マッピング オブジェクトは、 PAGE_READONLY、 PAGE_READ_EXECUTE、PAGE_WRITECOPY、 PAGE_EXECUTE_WRITECOPY、 PAGE_READWRITE、または PAGE_EXECUTE_READWRITE保護を使用 して 作成されている必要があります。
プロセスが書き込み時のコピー ページに書き込むと、システムは元のページをプロセスにプライベートな新しいページにコピーします。 新しいページはページング ファイルによってサポートされます。 新しいページの保護は、書き込み時のコピーから読み取り/書き込みに変わります。 書き込み時のコピー アクセスを指定すると、呼び出し元のプロセスがビュー内のすべてのページに書き込み、すべてのページをプライベートにできるため、システムとプロセスのコミット料金はビュー全体に対するものです。 新しいページの内容は元のファイルに書き戻されることはなく、ビューがマップ解除されると失われます。 |
|
バージョン 1703 Windows 10以降、このフラグは、大きなページ サポートを使用してビューをマップする必要があることを指定します。 ビューのサイズは 、GetLargePageMinimum 関数によって報告される大きなページのサイズの倍数である必要があり、ファイル マッピング オブジェクトは SEC_LARGE_PAGES オプションを使用して作成されている必要があります。 lpBaseAddress に null 以外の値を指定する場合、値は GetLargePageMinimum の倍数である必要があります。 |
|
ファイルの実行可能ビューがマップされます (マップされたメモリはコードとして実行できます)。 ファイル マッピング オブジェクトは、 PAGE_EXECUTE_READ、PAGE_EXECUTE_WRITECOPY、または PAGE_EXECUTE_READWRITE保護を使用 して 作成されている必要があります。
Windows Server 2003 および Windows XP: この値は、SP2 と Windows Server 2003 SP1 の Windows XP 以降で使用できます。 |
|
マップされたファイル内のすべての場所を、制御フロー ガード (CFG) の無効なターゲットとして設定します。 このフラグは 、PAGE_TARGETS_INVALIDに似ています。 このフラグは、実行アクセス権FILE_MAP_EXECUTEと組み合わせて使用 します。 これらのページ内の場所に対する間接呼び出しは CFG チェックに失敗し、プロセスは終了します。 割り当てられた実行可能ページの既定の動作は、CFG の有効な呼び出しターゲットとしてマークされます。 |
SEC_IMAGE 属性を使用して作成されたファイル マッピング オブジェクトの場合、dwDesiredAccess パラメーターは無効であり、FILE_MAP_READなどの有効な値に設定する必要があります。
ファイル マッピング オブジェクトへのアクセスの詳細については、「 ファイル マッピング のセキュリティとアクセス権」を参照してください。
[in] dwFileOffsetHigh
ビューを開始するファイル オフセットの高次 DWORD 。
[in] dwFileOffsetLow
ビューを開始するファイル オフセットの下位 DWORD 。 高オフセットと低オフセットの組み合わせは、ファイル マッピング内のオフセットを指定する必要があります。 また、システムのメモリ割り当て粒度と一致する必要もあります。 つまり、オフセットは割り当て粒度の倍数である必要があります。 システムのメモリ割り当て粒度を取得するには、 GetSystemInfo 関数を使用します。この関数は、 SYSTEM_INFO 構造体のメンバーを格納します。
[in] dwNumberOfBytesToMap
ビューにマップするファイル マッピングのバイト数。 すべてのバイトは、 CreateFileMapping で指定された最大サイズ内にある必要があります。 このパラメーターが 0 (ゼロ) の場合、マッピングは指定されたオフセットからファイル マッピングの末尾まで拡張されます。
[in, optional] lpBaseAddress
マッピングが開始される呼び出しプロセス アドレス空間内のメモリ アドレスへのポインター。 これは、システムのメモリ割り当て粒度の倍数である必要があります。または、関数が失敗します。 システムのメモリ割り当ての細分性を確認するには、 GetSystemInfo 関数を使用します。 指定したアドレスに十分なアドレス空間がない場合、関数は失敗します。
lpBaseAddress が NULL の場合、オペレーティング システムはマッピング アドレスを選択します。 このシナリオでは、この関数は MapViewOfFile 関数と同じです。
現在は安全なアドレス (オペレーティング システムでは使用されません) を指定することは可能ですが、アドレスが時間の経過と同時に安全な状態を保つ保証はありません。 そのため、オペレーティング システムでアドレスを選択することをお勧めします。 この場合は、メモリ マップされたファイルにポインターを格納せず、ファイル マッピングのベースからのオフセットを格納して、マッピングを任意のアドレスで使用できるようにします。
戻り値
関数が成功した場合、戻り値はマップされたビューの開始アドレスです。
関数が失敗した場合は、返される値は NULL です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
ファイルをマッピングすると、ファイルの指定された部分が呼び出し元プロセスのアドレス空間に表示されます。
アドレス空間より大きいファイルの場合、ファイル データのごく一部のみを一度にマップできます。 最初のビューが完了したら、マップを解除して新しいビューをマップします。
ビューのサイズを取得するには、 VirtualQueryEx 関数を使用します。
ページ ファイルによってサポートされるファイル マッピング オブジェクト内のページの初期内容は 0 (ゼロ) です。
通常、推奨されるアドレスは、ファイルを複数のプロセスで同じアドレスにマップするように指定するために使用されます。 これには、関連するすべてのプロセスでアドレス空間の領域を使用できる必要があります。 マッピングに使用されるリージョンでは、VirtualAlloc 関数や VirtualAllocEx 関数を使用してメモリを予約するなど、他のメモリ割り当ては行われません。
lpBaseAddress パラメーターでベース オフセットが指定されている場合、指定したメモリ領域が呼び出し元のプロセスでまだ使用されていない場合、関数は成功します。 システムは、他の 32 ビット・プロセスのメモリー・マップ・ファイルに対して同じメモリー領域が使用可能であることを保証しません。
ファイルの複数のビュー (またはファイル マッピング オブジェクトとそのマップされたファイル) は、指定された時刻に同じデータが含まれている場合に 一貫性 があります。 これは、ファイル ビューが同じファイル マッピング オブジェクトから派生した場合に発生します。 プロセスでは、 DuplicateHandle 関数を使用してファイル マッピング オブジェクト ハンドルを別のプロセスに複製するか、別のプロセスで OpenFileMapping 関数を使用してファイル マッピング オブジェクトを名前で開くことができます。
1 つの重要な例外では、同じファイルによってサポートされるファイル マッピング オブジェクトから派生したファイル ビューは、特定の時点で一貫性または同一です。 一貫性は、プロセス内のビューと、異なるプロセスによってマップされるビューに対して保証されます。
例外はリモート ファイルに関連しています。 MapViewOfFileEx はリモート ファイルで動作しますが、一貫性を保つことはありません。 たとえば、2 台のコンピューターが両方ともファイルを書き込み可能としてマップし、両方が同じページを変更した場合、各コンピューターはページへの独自の書き込みのみを表示します。 データがディスク上で更新されると、マージされません。
ファイルのマップされたビューは、 ReadFile 関数または WriteFile 関数によってアクセスされるファイルと一貫性が保証されません。
EXCEPTION_IN_PAGE_ERROR例外から保護するには、構造化例外処理を使用して、ページ ファイル以外のファイルのメモリ マップ ビューに対して書き込みまたは読み取りを行うコードを保護します。 詳細については、「 ファイル ビューからの読み取りと書き込み」を参照してください。
マップされたビューを使用してファイルを変更する場合、最後の変更タイムスタンプが自動的に更新されない場合があります。 必要に応じて、呼び出し元は SetFileTime を使用してタイムスタンプを設定する必要があります。
実行可能なアクセス許可を持つファイルを使用するには、アプリケーションで CreateFileMapping をPAGE_EXECUTE_READWRITEまたはPAGE_EXECUTE_READで呼び出し、FILE_MAP_EXECUTE FILE_MAP_WRITEまたはFILE_MAP_EXECUTE | FILE_MAP_READを使用して | MapViewOfFileEx を呼び出す必要があります。
Windows Server 2012では、この関数は次のテクノロジでサポートされています。
| テクノロジ | サポートされています |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 Transparent Failover (TFO) | はい |
| スケールアウト ファイル共有 (SO) を使う SMB 3.0 | はい |
| クラスターの共有ボリューム ファイル システム (CsvFS) | はい |
| Resilient File System (ReFS) | はい |
必要条件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
| サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
| 対象プラットフォーム | Windows |
| ヘッダー | memoryapi.h (Windows.h、Memoryapi.h を含む) |
| Library | onecore.lib |
| [DLL] | Kernel32.dll |