MapViewOfFileExNuma 関数 (winbase.h)

ファイル マッピングのビューを呼び出し元プロセスのアドレス空間にマップし、物理メモリの NUMA ノードを指定します。

構文

LPVOID MapViewOfFileExNuma(
  [in]           HANDLE hFileMappingObject,
  [in]           DWORD  dwDesiredAccess,
  [in]           DWORD  dwFileOffsetHigh,
  [in]           DWORD  dwFileOffsetLow,
  [in]           SIZE_T dwNumberOfBytesToMap,
  [in, optional] LPVOID lpBaseAddress,
  [in]           DWORD  nndPreferred
);

パラメーター

[in] hFileMappingObject

ファイル マッピング オブジェクトへのハンドル。 CreateFileMappingNuma 関数と OpenFileMapping 関数は、このハンドルを返します。

[in] dwDesiredAccess

ページのページ保護を決定するファイル マッピング オブジェクトへのアクセスの種類。 このパラメーターには、次の値のいずれか、または必要に応じて複数の値のビットごとの OR の組み合わせを指定できます。

意味
FILE_MAP_ALL_ACCESS
ファイルの読み取り/書き込みビューがマップされます。 ファイル マッピング オブジェクトは、 PAGE_READWRITE または PAGE_EXECUTE_READWRITE 保護を使用して作成されている必要があります。

MapViewOfFileExNuma と共に使用する場合、FILE_MAP_ALL_ACCESSFILE_MAP_WRITEと同じです。

FILE_MAP_READ
ファイルの読み取り専用ビューがマップされます。 ファイル ビューに書き込もうとすると、アクセス違反が発生します。

ファイル マッピング オブジェクトは、 PAGE_READONLY、PAGE_READWRITEPAGE_EXECUTE_READ、または PAGE_EXECUTE_READWRITE保護を使用 して 作成されている必要があります。

FILE_MAP_WRITE
ファイルの読み取り/書き込みビューがマップされます。 ファイル マッピング オブジェクトは、 PAGE_READWRITE または PAGE_EXECUTE_READWRITE 保護を使用して作成されている必要があります。

MapViewOfFileExNuma と共に使用する場合、 (FILE_MAP_WRITE | FILE_MAP_READ)FILE_MAP_WRITEと同じです。

 

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

意味
FILE_MAP_COPY
ファイルの書き込み時のコピー ビューがマップされます。 ファイル マッピング オブジェクトは、 PAGE_READONLYPAGE_READ_EXECUTE、PAGE_WRITECOPYPAGE_EXECUTE_WRITECOPYPAGE_READWRITE、または PAGE_EXECUTE_READWRITE保護を使用 して 作成されている必要があります。

プロセスが書き込み時のコピー ページに書き込むと、システムは元のページをプロセスにプライベートな新しいページにコピーします。 新しいページはページング ファイルによってサポートされます。 新しいページの保護は、書き込み時のコピーから読み取り/書き込みに変わります。

書き込み時のコピー アクセスを指定すると、呼び出し元のプロセスがビュー内のすべてのページに書き込み、すべてのページをプライベートにできるため、システムとプロセスのコミット料金はビュー全体に対するものです。 新しいページの内容は元のファイルに書き戻されることはなく、ビューがマップ解除されると失われます。

FILE_MAP_EXECUTE
ファイルの実行可能ビューがマップされます (マップされたメモリはコードとして実行できます)。 ファイル マッピング オブジェクトは、 PAGE_EXECUTE_READ、PAGE_EXECUTE_WRITECOPY、または PAGE_EXECUTE_READWRITE保護を使用 して 作成されている必要があります。
FILE_MAP_LARGE_PAGES
バージョン 1703 Windows 10以降、このフラグは、大きなページ サポートを使用してビューをマップする必要があることを指定します。 ビューのサイズは 、GetLargePageMinimum 関数によって報告される大きなページのサイズの倍数である必要があり、ファイル マッピング オブジェクトは SEC_LARGE_PAGES オプションを使用して作成されている必要があります。 lpBaseAddress に null 以外の値を指定する場合、値は GetLargePageMinimum の倍数である必要があります。
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 の場合、オペレーティング システムはマッピング アドレスを選択します。

現在は安全なアドレス (オペレーティング システムでは使用されません) を指定することは可能ですが、アドレスが時間の経過と同時に安全な状態を保つ保証はありません。 そのため、オペレーティング システムでアドレスを選択することをお勧めします。 この場合は、メモリ マップファイルにポインターを格納しません。マッピングを任意のアドレスで使用できるように、ファイル マッピングのベースからのオフセットを格納します。

[in] nndPreferred

物理メモリが存在する必要がある NUMA ノード。

意味
NUMA_NO_PREFERRED_NODE
0xffffffff
NUMA ノードは推奨されません。 これは、 MapViewOfFileEx 関数の呼び出しと同じです。

戻り値

関数が成功した場合、戻り値はマップされたビューの開始アドレスです。

関数が失敗した場合は、返される値は NULL です。 エラーの詳細情報を得るには、GetLastError 関数を呼び出します。

注釈

ファイルをマッピングすると、ファイルの指定された部分が呼び出し元プロセスのアドレス空間に表示されます。

アドレス空間より大きいファイルの場合は、ファイル データのごく一部のみを一度にマップできます。 最初のビューが完了したら、マップを解除して新しいビューをマップします。

ビューのサイズを取得するには、 VirtualQueryEx 関数を使用します。

ページ ファイルによってサポートされるファイル マッピング オブジェクト内のページの初期内容は 0 (ゼロ) です。

推奨されるマッピング アドレスが指定されている場合、指定したアドレスに十分なアドレス空間がある場合、ファイルは指定されたアドレス (最も近い 64 KB 境界に切り捨てられたもの) にマップされます。 アドレス空間が不足している場合、関数は失敗します。

通常、推奨されるアドレスは、ファイルを複数のプロセスで同じアドレスにマップするように指定するために使用されます。 これには、関連するすべてのプロセスでアドレス空間の領域を使用できる必要があります。 マッピングに使用されるリージョンでは、 VirtualAllocExNuma 関数を使用してメモリを予約するなど、他のメモリ割り当ては実行できません。

lpBaseAddress パラメーターでベース オフセットが指定されている場合、指定したメモリ領域が呼び出し元のプロセスでまだ使用されていない場合、関数は成功します。 システムは、他の 32 ビット・プロセスのメモリー・マップ・ファイルに対して同じメモリー領域が使用可能であることを保証しません。

ファイルの複数のビュー (またはファイル マッピング オブジェクトとそのマップされたファイル) は、指定された時刻に同じデータが含まれている場合に 一貫性 があります。 これは、ファイル ビューが同じファイル マッピング オブジェクトから派生した場合に発生します。 プロセスでは、 DuplicateHandle 関数を使用してファイル マッピング オブジェクト ハンドルを別のプロセスに複製するか、別のプロセスで OpenFileMapping 関数を使用してファイル マッピング オブジェクトを名前で開くことができます。

1 つの重要な例外では、同じファイルによってサポートされるファイル マッピング オブジェクトから派生したファイル ビューは、特定の時点で一貫性または同一です。 一貫性は、プロセス内のビューと、異なるプロセスによってマップされるビューに対して保証されます。

例外はリモート ファイルに関連しています。 MapViewOfFileExNuma はリモート ファイルで動作しますが、一貫性を保つことはありません。 たとえば、2 台のコンピューターが両方ともファイルを書き込み可能としてマップし、両方が同じページを変更した場合、各コンピューターはページへの独自の書き込みのみを表示します。 ディスク上のデータが更新されると、マージされません。

ファイルのマップされたビューは、 ReadFile 関数または WriteFile 関数によってアクセスされるファイルと一貫性が保証されません。

EXCEPTION_IN_PAGE_ERROR例外から保護するには、構造化例外処理を使用して、ページ ファイル以外のファイルのメモリ マップ ビューに対して書き込みまたは読み取りを行うコードを保護します。 詳細については、「 ファイル ビューからの読み取りと書き込み」を参照してください。

マップされたビューを使用してファイルを変更する場合、最後の変更タイムスタンプが自動的に更新されない場合があります。 必要に応じて、呼び出し元は SetFileTime を使用してタイムスタンプを設定する必要があります。

実行可能なアクセス許可を持つファイルを作成するには、アプリケーションで PAGE_EXECUTE_READWRITE または PAGE_EXECUTE_READ を使用して CreateFileMappingNuma 関数を呼び出し、FILE_MAP_EXECUTE FILE_MAP_WRITEまたはFILE_MAP_EXECUTE | FILE_MAP_READを使用して | MapViewOfFileExNuma 関数を呼び出す必要があります。

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

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル はい
SMB 3.0 Transparent Failover (TFO) はい
スケールアウト ファイル共有 (SO) を使う SMB 3.0 はい
クラスターの共有ボリューム ファイル システム (CsvFS) はい
Resilient File System (ReFS) はい

必要条件

要件
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

CreateFileMappingNuma

DuplicateHandle

ファイル マッピング関数

GetSystemInfo

MapViewOfFileEx

NUMA サポート

OpenFileMapping

ReadFile

SYSTEM_INFO

UnmapViewOfFile

VirtualAlloc

WriteFile