CreateFileMappingW 関数 (memoryapi.h)

指定したファイルの名前付きまたは名前のないファイル マッピング オブジェクトを作成または開きます。

物理メモリの NUMA ノードを指定するには、「 CreateFileMappingNuma」を参照してください。

構文

HANDLE CreateFileMappingW(
  [in]           HANDLE                hFile,
  [in, optional] LPSECURITY_ATTRIBUTES lpFileMappingAttributes,
  [in]           DWORD                 flProtect,
  [in]           DWORD                 dwMaximumSizeHigh,
  [in]           DWORD                 dwMaximumSizeLow,
  [in, optional] LPCWSTR               lpName
);

パラメーター

[in] hFile

ファイル マッピング オブジェクトの作成元となるファイルへのハンドル。

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

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

[in, optional] lpFileMappingAttributes

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

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

[in] flProtect

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

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

アプリケーションでは、ファイル マッピング オブジェクトに対して次の属性のうち 1 つ以上を指定できます。これらの属性は、上記のページ保護値のいずれかと組み合わせることによって指定できます。

[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" プレフィックスを付けることができます。 名前の残りの部分には、円記号 (\) を除く任意の文字を含めることができます。 セッション 0 以外のセッションからグローバル名前空間にファイル マッピング オブジェクトを作成するには、 SeCreateGlobalPrivilege 特権が 必要です。 詳細については、「 カーネル オブジェクトの名前空間」を参照してください。

高速ユーザー切り替えは、ターミナル サービス セッションを使用して実装されます。 ログオンする最初のユーザーはセッション 0 (ゼロ) を使用し、次にログオンするユーザーはセッション 1 (1) を使用します。 カーネル オブジェクト名は、アプリケーションが複数のユーザーをサポートできるように、ターミナル サービスに関して概説されているガイドラインに従う必要があります。

戻り値

関数が成功した場合、戻り値は新しく作成されたファイル マッピング オブジェクトへのハンドルです。

関数呼び出しの前にオブジェクトが存在する場合、関数は既存のオブジェクト (指定したサイズではなく現在のサイズ) にハンドルを返し、GetLastError はERROR_ALREADY_EXISTSを返します。

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

解説

ファイル マッピング オブジェクトが作成された後、ファイルのサイズがファイル マッピング オブジェクトのサイズを超えてはなりません。共有されている場合は、すべてのファイル コンテンツを共有できるわけではありません。

アプリケーションで、ディスク上の実際の名前付きファイルのサイズよりも大きいファイル マッピング オブジェクトのサイズを指定し、ページ保護で書き込みアクセスが許可されている場合 (つまり、 flProtect パラメーターで PAGE_READWRITE または PAGE_EXECUTE_READWRITEを指定)、ディスク上のファイルは、ファイル マッピング オブジェクトの指定されたサイズに合わせて増やされます。 ファイルが拡張されている場合、ファイルの古い終わりからファイルの新しい終わりまでの間のファイルの内容がゼロになることは保証されません。動作はファイル システムによって定義されます。 ディスク上のファイルを増やすことができない場合、CreateFileMapping は失敗し、GetLastError はERROR_DISK_FULLを返します。

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

CreateFileMapping が返すハンドルは、新しいファイル マッピング オブジェクトへのフル アクセス権を持ち、ファイル マッピング オブジェクトへのハンドルを必要とする任意の関数で使用できます。

複数のプロセスで同じファイルのビューを共有するには、1 つの共有ファイル マッピング オブジェクトを使用するか、同じファイルでバックアップされた個別のファイル マッピング オブジェクトを作成します。 1 つのファイル マッピング オブジェクトは、プロセスの作成時にハンドルを継承するか、ハンドルを複製するか、ファイル マッピング オブジェクトを名前で開いて、複数のプロセスで共有できます。 詳細については、 CreateProcess、 DuplicateHandle 、 および OpenFileMapping 関数を 参照してください。

ファイル マッピング オブジェクトを作成しても、実際にはビューはプロセス アドレス空間にマップされません。 MapViewOfFile 関数と MapViewOfFileEx 関数は、ファイルのビューをプロセス アドレス空間にマップします。

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

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

入出力 (I/O) 関数 (ReadFile および WriteFile) を使用してアクセスされるマップされたファイルとファイルは、必ずしも一貫性があるとは限りません。

ファイル マッピング オブジェクトのマップされたビューは、オブジェクトへの内部参照を保持し、ファイル マッピング オブジェクトは、そのオブジェクトへのすべての参照が解放されるまで閉じません。 したがって、ファイル マッピング オブジェクトを完全に閉じるには、 UnmapViewOfFile を呼び出してファイル マッピング オブジェクトのすべてのマップされたビューのマップを解除し、 CloseHandle を呼び出してファイル マッピング オブジェクト ハンドルを閉じる必要があります。 これらの関数は、任意の順序で呼び出すことができます。

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

セッション 0 以外のセッションからグローバル名前空間にファイル マッピング オブジェクトを作成するには、 SeCreateGlobalPrivilege 特権が 必要です。 この特権チェックは、ファイル マッピング オブジェクトの作成に限定され、既存のオブジェクトを開く場合には適用されないことに注意してください。 たとえば、サービスまたはシステムがグローバル名前空間にファイル マッピング オブジェクトを作成する場合、呼び出し元が必要なアクセス権を持っている場合、任意のセッションで実行されているプロセスは、そのファイル マッピング オブジェクトにアクセスできます。

Windows XP: 前の段落で説明した要件は、Windows Server 2003 と Windows XP SP2 で導入されました

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

実行可能なアクセス許可を持つマッピングを行うには、アプリケーションで PAGE_EXECUTE_READWRITE または PAGE_EXECUTE_READ を使用して CreateFileMapping を呼び出し、 または FILE_MAP_EXECUTE | FILE_MAP_READを使用して MapViewOfFileFILE_MAP_EXECUTE | FILE_MAP_WRITE を呼び出す必要があります。

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

例

例については、「 名前付き共有メモリの作成 」または「 大きなページを使用したファイル マッピングの作成」を参照してください。

要件

関連項目

CloseHandle

CreateFileMappingNuma

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

DuplicateHandle

ファイル マッピング関数

MapViewOfFile

MapViewOfFileEx

メモリ管理関数

OpenFileMapping

ReadFile

SECURITY_ATTRIBUTES

UnmapViewOfFile

VirtualAlloc

WriteFile