CreateFileMappingNumaA 関数 (winbase.h)
指定したファイルの名前付きまたは名前のないファイル マッピング オブジェクトを作成または開き、物理メモリの NUMA ノードを指定します。
構文
HANDLE CreateFileMappingNumaA(
[in] HANDLE hFile,
[in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
[in] DWORD flProtect,
[in] DWORD dwMaximumSizeHigh,
[in] DWORD dwMaximumSizeLow,
[in, optional] LPCSTR lpName,
[in] DWORD nndPreferred
);
パラメーター
[in] hFile
ファイル マッピング オブジェクトの作成元となるファイルへのハンドル。
ファイルは、flProtect パラメーターが指定する保護フラグと互換性のあるアクセス権で開く必要があります。 必須ではありませんが、マップする予定のファイルを排他的アクセス用に開くことをお勧めします。 詳細については、「ファイルのセキュリティとアクセス権の」を参照してください。
hFile が
[in, optional] lpFileMappingAttributes
返されたハンドルを子プロセスによって継承できるかどうかを決定する SECURITY_ATTRIBUTES 構造体へのポインター。 の lpSecurityDescriptor メンバー
SECURITY_ATTRIBUTES 構造体は、新しいファイル マッピング オブジェクトのセキュリティ記述子を指定します。
lpFileMappingAttributes
[in] flProtect
ファイル マッピング オブジェクトのページ保護を指定します。 オブジェクトのすべてのマップされたビューは、この保護と互換性がある必要があります。
このパラメーターには、次のいずれかの値を指定できます。
アプリケーションは、ファイル マッピング オブジェクトに対して、上記のページ保護値のいずれかと組み合わせることにより、次の属性の 1 つ以上を指定できます。
| 価値 | 意味 |
|---|---|
|
すべてのページのメモリまたはページング ファイルに物理ストレージを割り当てます。
これが既定の設定です。 |
|
実行可能イメージ ファイルとして指定されたファイルを設定します。
SEC_IMAGE 属性は、PAGE_READONLYなどのページ保護値と組み合わせる必要があります。 ただし、このページ保護値は、実行可能イメージ ファイルのビューには影響しません。 実行可能イメージ ファイルのビューのページ保護は、実行可能ファイル自体によって決まります。 SEC_IMAGEで有効なその他の属性はありません。 |
|
hFile パラメーターが指定するファイルが実行されない実行可能イメージ ファイルであり、読み込まれたイメージ ファイルで強制整合性チェックが実行されないことを指定します。
さらに、SEC_IMAGE_NO_EXECUTE 属性で作成されたファイル マッピング オブジェクトのビューをマッピングしても、PsSetLoadImageNotifyRoutine カーネル API を使用して登録されたドライバー コールバックは呼び出されません。
SEC_IMAGE_NO_EXECUTE 属性は、PAGE_READONLY ページ保護の値と組み合わせる必要があります。 SEC_IMAGE_NO_EXECUTEで有効なその他の属性はありません。 Windows Server 2008 R2、Windows 7、Windows Server 2008、および Windows Vista: この値は、Windows Server 2012 および Windows 8 より前ではサポートされていません。 |
|
イメージのマッピング時やページ ファイルからのバッキング時には大きなページを使用できますが、通常のファイルのデータのマッピングでは使用できません。 GetLargePageMinimum 関数によって報告される大きなページの最小サイズとして、ファイル マッピング オブジェクトの最大サイズを指定し、SeLockMemoryPrivilege 特権を有効にしてください。 |
|
すべてのページを非対応に設定します。
アプリケーションでは、デバイスに明示的に必要な場合を除き、このフラグを使用しないでください。 SEC_NOCACHE でマップされたメモリでインターロックされた関数を使用すると、EXCEPTION_ILLEGAL_INSTRUCTION 例外が発生する可能性があります。 SEC_NOCACHE には、SEC_RESERVE または SEC_COMMIT を設定する必要があります。 |
|
物理記憶域を割り当てずにすべてのページを予約します。
ページの予約範囲は、ページの範囲が解放されるまで、他の割り当て操作では使用できません。 予約済みページは、VirtualAllocExNuma 関数への後続の呼び出しで識別できます。 この属性は、hFile パラメーターが INVALID_HANDLE_VALUE されている場合にのみ有効です (つまり、システム ページング ファイルによってサポートされるファイル マッピング オブジェクト)。 |
|
すべてのページを書き込み結合に設定します。
アプリケーションでは、デバイスに明示的に必要な場合を除き、この属性を使用しないでください。 SEC_WRITECOMBINE にマップされたメモリでインターロックされた関数を使用すると、EXCEPTION_ILLEGAL_INSTRUCTION 例外が発生する可能性があります。 SEC_WRITECOMBINE には、SEC_RESERVE または SEC_COMMIT 属性を設定する必要があります。 |
[in] dwMaximumSizeHigh
ファイル マッピング オブジェクトの最大サイズの高次 DWORD。
[in] dwMaximumSizeLow
ファイル マッピング オブジェクトの最大サイズの下位 DWORD。
このパラメーターと dwMaximumSizeHigh パラメーターが 0 (ゼロ) の場合、ファイル マッピング オブジェクトの最大サイズは、hFile パラメーターが識別するファイルの現在のサイズと等しくなります。
長さが 0 (ゼロ) のファイルをマップしようとすると、エラー コード ERROR_FILE_INVALIDで失敗します。 アプリケーションでは、長さが 0 (ゼロ) のファイルをテストし、それらのファイルを拒否する必要があります。
[in, optional] lpName
ファイル マッピング オブジェクトの名前。
このパラメーターが既存のファイル マッピング オブジェクトの名前と一致する場合、関数は、flProtect パラメーターが指定する保護を使用してオブジェクトへのアクセスを要求します。
このパラメーターが NULL
lpName パラメーターが既存のイベント、セマフォ、ミューテックス、待機可能タイマー、またはジョブ オブジェクトの名前と一致する場合、関数は失敗し、GetLastError 関数は ERROR_INVALID_HANDLEを返します。 これは、これらのオブジェクトが同じ名前空間を共有しているために発生します。
名前には、グローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global" または "Local" プレフィックスを付けることができます。 名前の残りの部分には、円記号 (\) を除く任意の文字を含めることができます。 グローバル名前空間でファイル マッピング オブジェクトを作成するには、SeCreateGlobalPrivilege 特権が必要です。 詳細については、「カーネル オブジェクト名前空間
高速ユーザー切り替えは、ターミナル サービス セッションを使用して実装されます。 ログオンする最初のユーザーはセッション 0 (ゼロ) を使用し、次にログオンするユーザーはセッション 1 (1) を使用します。 カーネル オブジェクト名は、アプリケーションが複数のユーザーをサポートできるように、ガイドラインに従う必要があります。
[in] nndPreferred
物理メモリが存在する NUMA ノード。
| 価値 | 意味 |
|---|---|
|
NUMA ノードは推奨されません。 これは、CreateFileMapping 関数を呼び出すのと同じです。 |
戻り値
関数が成功した場合、戻り値はファイル マッピング オブジェクトへのハンドルです。
関数呼び出しの前にオブジェクトが存在する場合、関数は既存のオブジェクト (指定したサイズではなく現在のサイズ) にハンドルを返し、GetLastError 関数は ERROR_ALREADY_EXISTSを返します。
関数が失敗した場合、戻り値は NULL
備考
ファイル マッピング オブジェクトが作成された後、ファイルのサイズがファイル マッピング オブジェクトのサイズを超えないようにする必要があります。存在する場合は、すべてのファイル コンテンツを共有できるわけではありません。
ファイル マッピング オブジェクトは、重複、継承、または名前で共有できます。 ページ ファイルによってサポートされるファイル マッピング オブジェクト内のページの初期コンテンツは 0 (ゼロ) です。
アプリケーションで、ディスク上の実際の名前付きファイルのサイズよりも大きいファイル マッピング オブジェクトのサイズを指定し、ページ保護で書き込みアクセスが許可されている場合 (つまり、flProtect パラメーターで PAGE_READWRITE または PAGE_EXECUTE_READWRITEを指定した場合)、ディスク上のファイルは、ファイル マッピング オブジェクトの指定されたサイズに合わせて増やされます。 ファイルが拡張されている場合、ファイルの古い終わりとファイルの新しい終わりの間のファイルの内容がゼロになることは保証されません。動作はファイル システムによって定義されます。
ファイルを増やすことができない場合、結果はファイル マッピング オブジェクトの作成に失敗し、GetLastError 関数は ERROR_DISK_FULLを返します。
CreateFileMappingNuma 関数が返すハンドルは、新しいファイル マッピング オブジェクトへのフル アクセス権を持ち、ファイル マッピング オブジェクトへのハンドルを必要とする任意の関数で使用できます。 ファイル マッピング オブジェクトは、プロセスの作成、重複処理、または名前によって共有できます。 詳細については、
ファイル マッピング オブジェクトを作成すると、ファイルのビューをマッピングできますが、ビューはマップされません。 MapViewOfFileExNuma 関数は、ファイルのビューをプロセス アドレス空間にマップします。
1 つの重要な例外では、1 つのファイル マッピング オブジェクトから派生したファイル ビューは、特定の時点でコヒーレントまたは同一です。 複数のプロセスに同じファイル マッピング オブジェクトのハンドルがある場合、ファイルのビューをマップすると、データのコヒーレント ビューが表示されます。
例外はリモート ファイルに関連しています。 CreateFileMappingNuma 関数はリモート ファイルで動作しますが、一貫性を保つことはありません。 たとえば、2 台のコンピューターがファイルを書き込み可能としてマップし、両方とも同じページを変更した場合、各コンピューターにはページへの独自の書き込みのみが表示されます。 ディスク上のデータが更新されると、ページはマージされません。
入出力 (I/O) 関数 (
ファイル マッピング オブジェクトを完全に閉じるには、UnmapViewOfFile 関数を呼び出して、ファイル マッピング オブジェクトのすべてのマップされたビューのマップを解除してから、CloseHandle 関数を呼び出してファイル マッピング オブジェクト ハンドルを閉じる必要があります。
これらの関数は、任意の順序で呼び出すことができます。 UnmapViewOfFile 関数の呼び出しは、ファイル マッピング オブジェクトのマップされたビューがオブジェクトに対して内部で開いているハンドルを維持し、開いているすべてのハンドルが閉じられるまでファイル マッピング オブジェクトが閉じないために必要です。
マップされたビューを使用してファイルを変更する場合、最後の変更タイムスタンプが自動的に更新されない場合があります。 必要に応じて、呼び出し元 SetFileTime を使用してタイムスタンプを設定する必要があります。
セッション 0 以外のセッションからファイル マッピング オブジェクトを作成するには、SeCreateGlobalPrivilege 特権が必要です。 この特権チェックは、ファイル マッピング オブジェクトの作成に限定され、既存のオブジェクトを開く場合には適用されないことに注意してください。 たとえば、サービスまたはシステムがファイル マッピング オブジェクトを作成する場合、呼び出し元が必要なアクセス権を持っている場合、任意のセッションで実行されているプロセスは、そのファイル マッピング オブジェクトにアクセスできます。
構造化例外処理を使用して、メモリ マップビューへの書き込みまたはメモリ マップビューからの読み取りを行うコードを保護します。 詳細については、「ファイル ビューからの読み取りと書き込みの
実行可能なアクセス許可を持つマッピングを行うには、アプリケーションで
Windows Server 2012 では、この関数は次のテクノロジでサポートされています。
| テクノロジー | サポート |
|---|---|
| サーバー メッセージ ブロック (SMB) 3.0 プロトコル | はい |
| SMB 3.0 透過的フェールオーバー (TFO) | はい |
| SMB 3.0 とスケールアウト ファイル共有 (SO) | はい |
| クラスター共有ボリューム ファイル システム (CsvFS) | はい |
| 回復性のあるファイル システム (ReFS) | はい |
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされる最小サーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | winbase.h (Windows.h、Memoryapi.h を含む) |
| ライブラリ | Kernel32.lib |
| DLL | Kernel32.dll |
関連項目
CloseHandle の
CreateFileMapping の
DuplicateHandle の
ReadFile の
unmapViewOfFile の
WriteFile の