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 パラメーターが指定する保護フラグと互換性のあるアクセス権を持つファイルを開く必要があります。 必須ではありませんが、マップする予定のファイルを排他的アクセス用に開くことをお勧めします。 詳細については、「 ファイルのセキュリティとアクセス権」を参照してください。

hFileINVALID_HANDLE_VALUEの場合、呼び出し元プロセスでは、dwMaximumSizeHigh パラメーターと dwMaximumSizeLow パラメーターでファイル マッピング オブジェクトのサイズも指定する必要があります。 このシナリオでは、 CreateFileMapping によって、指定したサイズのファイル マッピング オブジェクトが作成されます。このオブジェクトは、ファイル システム内のファイルではなく、システム ページング ファイルによってサポートされます。

SecurityAttributes

種類: _In_opt_ SECURITY_ATTRIBUTES*

返された ハンドルを子 プロセスによって継承できるかどうかを決定するSECURITY_ATTRIBUTES構造体へのポインター。 SECURITY_ATTRIBUTES構造体の lpSecurityDescriptor メンバーは、新しいファイル マッピング オブジェクトのセキュリティ記述子を指定します。

lpAttributesNULL の場合、ハンドルを継承できず、ファイル マッピング オブジェクトは既定のセキュリティ記述子を取得します。 ファイル マッピング オブジェクトの既定のセキュリティ記述子のアクセス制御リスト (ACL) は、作成者のプライマリ トークンまたは偽装トークンから取得されます。 詳細については、「 ファイル マッピングのセキュリティとアクセス権」を参照してください。

DesiredAccess

型: _In_ ULONG

返されるファイル マッピング ハンドルに必要なアクセス マスク。 アクセス権の一覧については、「 ファイル マッピングのセキュリティとアクセス権」を参照してください。

PageProtection

型: _In_ ULONG

ファイル マッピング オブジェクトのページ保護を指定します。 オブジェクトのすべてのマップされたビューは、この保護と互換性がある必要があります。

このパラメーターには、次の値のいずれかを指定できます。

説明
PAGE_EXECUTE_READ
0x20
読み取り専用、書き込み時のコピー、または実行アクセスに対してビューをマップできるようにします。

hFile パラメーターで指定されたファイル ハンドルは、GENERIC_READとGENERIC_EXECUTEアクセス権を使用して作成する必要があります。

Windows Server 2003 および Windows XP: この値は、WINDOWS XP と SP2、Windows Server 2003 SP1 まで使用できません。

PAGE_EXECUTE_READWRITE
0x40
読み取り専用、書き込み時のコピー、読み取り/書き込み、または実行アクセスに対してビューをマップできるようにします。

hFile パラメーターが指定するファイル ハンドルは、GENERIC_READ、GENERIC_WRITEGENERIC_EXECUTEアクセス権を使用して作成する必要があります。

Windows Server 2003 および Windows XP: この値は、WINDOWS XP と SP2、Windows Server 2003 SP1 まで使用できません。

PAGE_EXECUTE_WRITECOPY
0x80
読み取り専用、書き込み時のコピー、または実行アクセスに対してビューをマップできるようにします。 この値は 、PAGE_EXECUTE_READと同じです。

hFile パラメーターが指定するファイル ハンドルは、GENERIC_READGENERIC_EXECUTEアクセス権を使用して作成する必要があります。

Windows Vista: この値は、Windows Vista と SP1 の間は使用できません。

Windows Server 2003 および Windows XP: この値はサポートされていません。

PAGE_READONLY
0x02
読み取り専用または書き込み時のコピー アクセス用にビューをマップできるようにします。 特定のリージョンに書き込もうとすると、アクセス違反が発生します。

hFile パラメーターが指定するファイル ハンドルは、GENERIC_READアクセス権を使用して作成する必要があります。

PAGE_READWRITE
0x04
読み取り専用、書き込み時のコピー、または読み取り/書き込みアクセスに対してビューをマップできるようにします。

hFile パラメーターが指定するファイル ハンドルは、GENERIC_READGENERIC_WRITEアクセス権を使用して作成する必要があります。

PAGE_WRITECOPY
0x08
読み取り専用または書き込み時のコピー アクセス用にビューをマップできるようにします。 この値は 、PAGE_READONLYと同じです。

hFile パラメーターが指定するファイル ハンドルは、GENERIC_READアクセス権を使用して作成する必要があります。

AllocationAttributes

型: _In_ ULONG

ファイル マッピング オブジェクトには、次の属性のうち 1 つ以上を指定できます。 PageProtection パラメーターも参照してください。

説明
SEC_COMMIT
0x8000000
ファイル マッピング オブジェクトがオペレーティング システムのページング ファイルによってサポートされている場合 ( hfile パラメーターが INVALID_HANDLE_VALUE)、ファイルのビューがプロセス アドレス空間にマップされるときに、ページの範囲全体が予約ではなくコミットされることを指定します。 システムには、マッピング全体を保持するのに十分なコミット可能なページが必要です。 それ以外の場合、 CreateFileMapping は失敗します。

この属性は、実行可能イメージ ファイルまたはデータ ファイルによってサポートされるファイル マッピング オブジェクトには影響しません ( hfile パラメーターはファイルへのハンドルです)。

SEC_COMMITSEC_RESERVEと組み合わせることはできません。

属性が指定されていない場合は、 SEC_COMMIT が想定されます。

SEC_IMAGE
0x1000000
hFile パラメーターが指定するファイルが実行可能イメージ ファイルであることを指定します。

SEC_IMAGE属性は、PAGE_READONLYなどのページ保護値と組み合わせる必要があります。 ただし、このページ保護値は、実行可能イメージ ファイルのビューには影響しません。 実行可能イメージ ファイルのビューのページ保護は、実行可能ファイル自体によって決まります。

その他の属性は 、SEC_IMAGEで有効ではありません。

SEC_IMAGE_NO_EXECUTE
0x11000000
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 より前ではサポートされていません。

SEC_LARGE_PAGES
0x80000000
オペレーティング システムのページング ファイルによってサポートされるファイル マッピング オブジェクトに大きなページを使用できるようにします ( 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
0x10000000
すべてのページをキャッシュ不可に設定します。

アプリケーションでは、デバイスに明示的に必要な場合を除き、この属性を使用しないでください。 SEC_NOCACHEにマップされたメモリでインターロックされた関数 使用すると、 EXCEPTION_ILLEGAL_INSTRUCTION 例外が発生する可能性があります。

SEC_NOCACHE には、 SEC_RESERVE または SEC_COMMIT 属性を設定する必要があります。

SEC_RESERVE
0x4000000
ファイル マッピング オブジェクトがオペレーティング システムのページング ファイルによってサポートされている場合 ( hfile パラメーターが INVALID_HANDLE_VALUE)、ファイルのビューがプロセス アドレス空間にマップされるときに、ページの範囲全体がコミットされるのではなく、後でプロセスで使用するために予約されることを指定します。

予約済みページは、 VirtualAlloc 関数の後続の呼び出しでコミットできます。 ページをコミットした後は、 VirtualFree 関数を使用してページを解放したり、コミットを解除したりすることはできません。

この属性は、実行可能イメージ ファイルまたはデータ ファイルによってサポートされるファイル マッピング オブジェクトには影響しません ( hfile パラメーターはファイルへのハンドルです)。

SEC_RESERVESEC_COMMITと組み合わせることはできません。

SEC_WRITECOMBINE
0x40000000
すべてのページを書き込み結合するように設定します。

アプリケーションでは、デバイスに明示的に必要な場合を除き、この属性を使用しないでください。 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

関連項目

CloseHandle

CreateFileMappingNuma

ファイル マッピング オブジェクトの作成

DuplicateHandle

MapViewOfFile

MapViewOfFileEx

メモリ管理機能

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile