MapViewOfFileEx 関数 (memoryapi.h)

[アーティクル]
11/12/2024

ファイルマッピングのビューを呼び出し元プロセスのアドレス空間にマップします。呼び出し元は、必要に応じて、ビューの推奨ベースメモリアドレスを指定できます。

物理メモリの 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 の組み合わせを指定できます。

価値	意味
FILE_MAP_ALL_ACCESS	ファイルの読み取り/書き込みビューがマップされます。ファイルマッピングオブジェクトは、PAGE_READWRITE または PAGE_EXECUTE_READWRITE 保護を使用して作成されている必要があります。 MapViewOfFileEx 関数と共に使用する場合、FILE_MAP_ALL_ACCESS は FILE_MAP_WRITEと同じです。
FILE_MAP_READ	ファイルの読み取り専用ビューがマップされます。ファイルビューに書き込もうとすると、アクセス違反が発生します。ファイルマッピングオブジェクトは、PAGE_READONLY、PAGE_READWRITE、PAGE_EXECUTE_READ、または PAGE_EXECUTE_READWRITE 保護を使用して作成されている必要があります。
FILE_MAP_WRITE	ファイルの読み取り/書き込みビューがマップされます。ファイルマッピングオブジェクトは、PAGE_READWRITE または PAGE_EXECUTE_READWRITE 保護を使用して作成されている必要があります。 MapViewOfFileEx、(FILE_MAP_WRITE \| FILE_MAP_READ) と FILE_MAP_ALL_ACCESS で使用する場合は、FILE_MAP_WRITEと同じです。

ビットごとの OR を使用すると、上記の値とこれらの値を組み合わせることができます。

価値	意味
FILE_MAP_COPY	ファイルの書き込み時のコピービューがマップされます。ファイルマッピングオブジェクトは、PAGE_READONLY、PAGE_EXECUTE_READ、PAGE_WRITECOPY、PAGE_EXECUTE_WRITECOPY、PAGE_READWRITE、または PAGE_EXECUTE_READWRITE 保護を使用して作成されている必要があります。プロセスが書き込み時のコピーページに書き込むと、システムは元のページを、プロセスに対してプライベートな新しいページにコピーします。新しいページはページングファイルによってサポートされます。新しいページの保護は、書き込み時のコピーから読み取り/書き込みに変わります。書き込み時のコピーアクセスを指定すると、呼び出し元のプロセスがビュー内のすべてのページに書き込み、すべてのページをプライベートにする可能性があるため、システムとプロセスのコミット料金はビュー全体に対して行われます。新しいページの内容は元のファイルに書き戻されることはなく、ビューがマップ解除されると失われます。
FILE_MAP_LARGE_PAGES	Windows 10 バージョン 1703 以降では、このフラグは、をサポートする大きなページ使用してビューをマップする必要があることを指定します。ビューのサイズは、GetLargePageMinimum 関数によって報告される大きなページのサイズの倍数である必要があり、ファイルマッピングオブジェクトは SEC_LARGE_PAGES オプションを使用して作成されている必要があります。 lpBaseAddressに null 以外の値を指定する場合、値は GetLargePageMinimumの倍数必要があります。
FILE_MAP_EXECUTE	ファイルの実行可能ビューがマップされます (マップされたメモリはコードとして実行できます)。ファイルマッピングオブジェクトは、PAGE_EXECUTE_READ、PAGE_EXECUTE_WRITECOPY、または PAGE_EXECUTE_READWRITE 保護を使用して作成されている必要があります。 Windows Server 2003 および Windows XP: この値は、Windows XP SP2 以降、Windows Server 2003 SP1 以降で使用できます。
FILE_MAP_TARGETS_INVALID	マップされたファイル内のすべての場所を、制御フローガード (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 を使用してタイムスタンプを設定する必要があります。

実行可能なアクセス許可を持つファイルを持つアプリケーションは、PAGE_EXECUTE_READWRITE または PAGE_EXECUTE_READCreateFileMapping を呼び出し、FILE_MAP_EXECUTE | FILE_MAP_WRITE または FILE_MAP_EXECUTE | FILE_MAP_READMapViewOfFileEx を呼び出す必要があります。

Windows Server 2012 では、この関数は次のテクノロジでサポートされています。

テクノロジー	サポート
サーバーメッセージブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 透過的フェールオーバー (TFO)	はい
SMB 3.0 とスケールアウトファイル共有 (SO)	はい
クラスター共有ボリュームファイルシステム (CsvFS)	はい
回復性のあるファイルシステム (ReFS)	はい

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリのみ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	memoryapi.h (Windows.h、Memoryapi.h を含む)
ライブラリ	onecore.lib
DLL	Kernel32.dll

次の方法で共有

MapViewOfFileEx 関数 (memoryapi.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース