CreateFileMapping2 関数 (memoryapi.h)
指定したファイルの名前付きまたは名前のないファイル マッピング オブジェクトを作成または開きます。 物理メモリの優先 NUMA ノードを拡張パラメーターとして指定できます。 ExtendedParameters パラメーターを 参照してください。
構文
HANDLE CreateFileMapping2(
HANDLE File,
SECURITY_ATTRIBUTES *SecurityAttributes,
ULONG DesiredAccess,
ULONG PageProtection,
ULONG AllocationAttributes,
ULONG64 MaximumSize,
PCWSTR Name,
MEM_EXTENDED_PARAMETER *ExtendedParameters,
ULONG ParameterCount
);
パラメーター
File
型: _In_ HANDLE
ファイル マッピング オブジェクトの作成元となるファイルへのハンドル。
flProtect パラメーターが指定する保護フラグと互換性のあるアクセス権を持つファイルを開く必要があります。 必須ではありませんが、マップする予定のファイルを排他的アクセス用に開くことをお勧めします。 詳細については、「 ファイルのセキュリティとアクセス権」を参照してください。
hFile がINVALID_HANDLE_VALUEの場合、呼び出し元プロセスでは、dwMaximumSizeHigh パラメーターと dwMaximumSizeLow パラメーターでファイル マッピング オブジェクトのサイズも指定する必要があります。 このシナリオでは、 CreateFileMapping によって、指定したサイズのファイル マッピング オブジェクトが作成されます。このオブジェクトは、ファイル システム内のファイルではなく、システム ページング ファイルによってサポートされます。
SecurityAttributes
種類: _In_opt_ SECURITY_ATTRIBUTES*
返された ハンドルを子 プロセスによって継承できるかどうかを決定するSECURITY_ATTRIBUTES構造体へのポインター。 SECURITY_ATTRIBUTES構造体の lpSecurityDescriptor メンバーは、新しいファイル マッピング オブジェクトのセキュリティ記述子を指定します。
lpAttributes が NULL の場合、ハンドルを継承できず、ファイル マッピング オブジェクトは既定のセキュリティ記述子を取得します。 ファイル マッピング オブジェクトの既定のセキュリティ記述子のアクセス制御リスト (ACL) は、作成者のプライマリ トークンまたは偽装トークンから取得されます。 詳細については、「 ファイル マッピングのセキュリティとアクセス権」を参照してください。
DesiredAccess
型: _In_ ULONG
返されるファイル マッピング ハンドルに必要なアクセス マスク。 アクセス権の一覧については、「 ファイル マッピングのセキュリティとアクセス権」を参照してください。
PageProtection
型: _In_ ULONG
ファイル マッピング オブジェクトのページ保護を指定します。 オブジェクトのすべてのマップされたビューは、この保護と互換性がある必要があります。
このパラメーターには、次の値のいずれかを指定できます。
AllocationAttributes
型: _In_ ULONG
ファイル マッピング オブジェクトには、次の属性のうち 1 つ以上を指定できます。 PageProtection パラメーターも参照してください。
| 値 | 説明 |
|---|---|
|
ファイル マッピング オブジェクトがオペレーティング システムのページング ファイルによってサポートされている場合 ( hfile パラメーターが INVALID_HANDLE_VALUE)、ファイルのビューがプロセス アドレス空間にマップされるときに、ページの範囲全体が予約ではなくコミットされることを指定します。 システムには、マッピング全体を保持するのに十分なコミット可能なページが必要です。 それ以外の場合、 CreateFileMapping は失敗します。
この属性は、実行可能イメージ ファイルまたはデータ ファイルによってサポートされるファイル マッピング オブジェクトには影響しません ( hfile パラメーターはファイルへのハンドルです)。 SEC_COMMIT を SEC_RESERVEと組み合わせることはできません。 属性が指定されていない場合は、 SEC_COMMIT が想定されます。 |
|
hFile パラメーターが指定するファイルが実行可能イメージ ファイルであることを指定します。
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 2003、Windows XP: この値は、Windows Server 2012 および Windows 8 より前ではサポートされていません。 |
|
オペレーティング システムのページング ファイルによってサポートされるファイル マッピング オブジェクトに大きなページを使用できるようにします ( hfile パラメーターは INVALID_HANDLE_VALUE)。 この属性は、実行可能イメージ ファイルまたはデータ ファイルによってサポートされるファイル マッピング オブジェクトではサポートされていません ( hFile パラメーターは実行可能イメージまたはデータ ファイルへのハンドルです)。
ファイル マッピング オブジェクトの最大サイズは、 GetLargePageMinimum 関数によって返される大きなページの最小サイズの倍数である必要があります。 そうでない場合、 CreateFileMapping は失敗します。 SEC_LARGE_PAGESを使用して作成されたファイル マッピング オブジェクトのビューをマッピングする場合、ベース アドレスとビュー サイズも、最小大きなページ サイズの倍数である必要があります。 SEC_LARGE_PAGES は、呼び出し元のトークンで SeLockMemoryPrivilege 特権を有効にする必要があります。 SEC_LARGE_PAGESを指定する場合は、SEC_COMMITも指定する必要があります。 Windows Server 2003: この値は、Windows Server 2003 SP1 までサポートされていません。 Windows XP: この値はサポートされていません。 |
|
すべてのページをキャッシュ不可に設定します。
アプリケーションでは、デバイスに明示的に必要な場合を除き、この属性を使用しないでください。 SEC_NOCACHEにマップされたメモリでインターロックされた関数 を 使用すると、 EXCEPTION_ILLEGAL_INSTRUCTION 例外が発生する可能性があります。 SEC_NOCACHE には、 SEC_RESERVE または SEC_COMMIT 属性を設定する必要があります。 |
|
ファイル マッピング オブジェクトがオペレーティング システムのページング ファイルによってサポートされている場合 ( hfile パラメーターが INVALID_HANDLE_VALUE)、ファイルのビューがプロセス アドレス空間にマップされるときに、ページの範囲全体がコミットされるのではなく、後でプロセスで使用するために予約されることを指定します。
予約済みページは、 VirtualAlloc 関数の後続の呼び出しでコミットできます。 ページをコミットした後は、 VirtualFree 関数を使用してページを解放したり、コミットを解除したりすることはできません。 この属性は、実行可能イメージ ファイルまたはデータ ファイルによってサポートされるファイル マッピング オブジェクトには影響しません ( hfile パラメーターはファイルへのハンドルです)。 SEC_RESERVE を SEC_COMMITと組み合わせることはできません。 |
|
すべてのページを書き込み結合するように設定します。
アプリケーションでは、デバイスに明示的に必要な場合を除き、この属性を使用しないでください。 SEC_WRITECOMBINEにマップされたメモリでインターロックされた関数 を 使用すると、 EXCEPTION_ILLEGAL_INSTRUCTION 例外が発生する可能性があります。 SEC_WRITECOMBINE には、 SEC_RESERVE または SEC_COMMIT 属性を設定する必要があります。 Windows Server 2003 および Windows XP: このフラグは、Windows Vista までサポートされていません。 |
MaximumSize
型: _In_ ULONG64
ファイル マッピング オブジェクトの最大サイズ。
このパラメーターが 0 (ゼロ) の場合、ファイル マッピング オブジェクトの最大サイズは 、hFile が識別するファイルの現在のサイズと同じです。
長さが 0 (ゼロ) のファイルをマップしようとすると、エラー コード ERROR_FILE_INVALIDで失敗します。 長さが 0 (ゼロ) のファイルをテストし、それらのファイルを拒否する必要があります。
Name
種類: _IN_OPT_ PCWSTR
ファイル マッピング オブジェクトの名前。
このパラメーターが既存のマッピング オブジェクトの名前と一致する場合、関数は flProtect が指定する保護を使用して オブジェクトへのアクセスを要求します。
このパラメーターが NULL の場合、ファイル マッピング オブジェクトは名前なしで作成されます。
lpName が既存のイベント、セマフォ、ミューテックス、待機可能タイマー、またはジョブ オブジェクトの名前と一致する場合、関数は失敗し、GetLastError 関数はERROR_INVALID_HANDLEを返します。 これは、これらのオブジェクトが同じ名前空間を共有しているために発生します。
名前には、グローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global" または "Local" プレフィックスを付けることができます。 名前の残りの部分には、円記号 (\) を除く任意の文字を含めることができます。 セッション 0 以外のセッションからグローバル名前空間にファイル マッピング オブジェクトを作成するには、 SeCreateGlobalPrivilege 特権が必要です。 詳細については、「 カーネル オブジェクトの名前空間」を参照してください。
高速ユーザー切り替えは、ターミナル サービス セッションを使用して実装されます。 ログオンする最初のユーザーはセッション 0 (ゼロ) を使用し、次にログオンするユーザーはセッション 1 (1) を使用します。 カーネル オブジェクト名は、アプリケーションが複数のユーザーをサポートできるように、ターミナル サービスに関して概説されているガイドラインに従う必要があります。
ExtendedParameters
型: _Inout_updates_opt_(ParameterCount) MEM_EXTENDED_PARAMETER*
MEM_EXTENDED_PARAMETER型の 1 つ以上の拡張パラメーターへの省略可能なポインター。 これらの拡張パラメーター値はそれぞれ、MemExtendedParameterAddressRequirements または MemExtendedParameterNumaNode のいずれかの Type フィールドを持つことができます。 MemExtendedParameterNumaNode 拡張パラメーターが指定されていない場合、動作は VirtualAlloc/MapViewOfFile 関数と同じです (つまり、物理ページに推奨される NUMA ノードは、最初にメモリにアクセスするスレッドの理想的なプロセッサに基づいて決定されます)。
ParameterCount
インチ ULONG ParameterCount
ExtendedParameters が指す拡張パラメーターの数。
戻り値
関数が成功した場合、戻り値は新しく作成されたファイル マッピング オブジェクトへのハンドルです。
関数呼び出しの前に オブジェクトが存在する場合、関数は既存のオブジェクト (指定したサイズではなく現在のサイズ) へのハンドルを返し、GetLastError はERROR_ALREADY_EXISTSを返します。
関数が失敗した場合は、返される値は NULL です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
「CreateFileMapping の解説」を参照してください。
例
例については、「 名前付き共有メモリの作成」または「 大きなページを使用したファイル マッピングの作成」を参照してください。
要件
| サポートされている最小のクライアント | Windows 10 ビルド 20348 |
| サポートされている最小のサーバー | Windows 10 ビルド 20348 |
| 対象プラットフォーム | Windows |
| ヘッダー | memoryapi.h (Windows.h、Memoryapi.h を含む) |
| Library | onecore.lib |
| [DLL] | Kernel32.dll |