CreateFileMappingW

指定ファイルに対して名前付きまたは名前なしのファイルマッピングオブジェクトを作成または開く。(CreateFileMappingW)

CreateFileMappingW hFile, lpFileMappingAttributes, flProtect, dwMaximumSizeHigh, dwMaximumSizeLow, lpName

hFile : [intptr] ファイルマッピングオブジェクトを作成する元のファイルへのハンドル。ファイルは flProtect パラメータが指定する保護フラグと互換性のあるアクセス権で開かれている必要がある。必須ではないが、マップ対象のファイルは排他アクセスで開くことが推奨される。詳細は File Security and Access Rights を参照。hFile が INVALID_HANDLE_VALUE の場合、呼び出し側プロセスは dwMaximumSizeHigh と dwMaximumSizeLow パラメータでファイルマッピングオブジェクトのサイズも指定する必要がある。この場合、CreateFileMapping はファイルシステム上のファイルではなくシステムページングファイルがバックする、指定サイズのファイルマッピングオブジェクトを作成する。
lpFileMappingAttributes : [var] 返されるハンドルが子プロセスに継承可能かどうかを決定する SECURITY_ATTRIBUTES 構造体へのポインタ。SECURITY_ATTRIBUTES 構造体の lpSecurityDescriptor メンバーが新しいファイルマッピングオブジェクトのセキュリティ記述子を指定する。lpAttributes が NULL の場合、ハンドルは継承できず、ファイルマッピングオブジェクトは既定のセキュリティ記述子を取得する。ファイルマッピングオブジェクトの既定セキュリティ記述子の ACL は作成者のプライマリトークンまたは impersonation トークンから取得される。詳細は File Mapping Security and Access Rights を参照。
flProtect : [int] ファイルマッピングオブジェクトのページ保護を指定する。このオブジェクトのすべてのマップされたビューは、この保護と互換性がなければならない。
dwMaximumSizeHigh : [int] ファイルマッピングオブジェクトの最大サイズの上位 DWORD。
dwMaximumSizeLow : [int] ファイルマッピングオブジェクトの最大サイズの下位 DWORD。このパラメータと dwMaximumSizeHigh がともに 0 の場合、ファイルマッピングオブジェクトの最大サイズは hFile が示すファイルの現在のサイズに等しい。長さ 0 のファイルをマップしようとすると ERROR_FILE_INVALID エラーコードで失敗する。アプリケーションは長さ 0 のファイルを検査して拒否するべきである。
lpName : [wstr] ファイルマッピングオブジェクトの名前。このパラメータが既存のマッピングオブジェクトの名前と一致する場合、関数は flProtect が指定する保護でオブジェクトへのアクセスを要求する。NULL の場合、名前なしでファイルマッピングオブジェクトが作成される。lpName が既存のイベント、セマフォ、ミューテックス、待機可能タイマ、またはジョブオブジェクトの名前と一致する場合、関数は失敗し GetLastError 関数は ERROR_INVALID_HANDLE を返す。これはこれらのオブジェクトが同じ名前空間を共有するために起こる。名前にはグローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global\" または "Local\" プレフィックスを付けられる。名前の残りの部分はバックスラッシュ文字 (\\) を除く任意の文字を含められる。セッション 0 以外のセッションからグローバル名前空間にファイルマッピングオブジェクトを作成するには SeCreateGlobalPrivilege 特権が必要。詳細は Kernel Object Namespaces を参照。高速ユーザー切り替えはターミナルサービスセッションを使用して実装される。最初にログオンしたユーザーがセッション 0、次にログオンしたユーザーがセッション 1、以降同様。カーネルオブジェクト名はアプリケーションが複数ユーザーをサポートできるようターミナルサービスのガイドラインに従う必要がある。

(プラグイン / モジュール : kernel32.dll)

解説

指定ファイルに対して名前付きまたは名前なしのファイルマッピングオブジェクトを作成または開く。(CreateFileMappingW)

[戻り値]

関数が成功した場合、戻り値は新しく作成されたファイルマッピングオブジェクトへのハンドル。関数呼び出し前にオブジェクトが存在していた場合、関数は既存オブジェクトへのハンドル（指定サイズではなく現在のサイズ）を返し、GetLastError
は ERROR_ALREADY_EXISTS を返す。関数が失敗した場合、戻り値は NULL。拡張エラー情報を取得するには
GetLastError を呼ぶ。

[備考]

ファイルマッピングオブジェクトが作成された後、ファイルのサイズはファイルマッピングオブジェクトのサイズを超えてはならない。超えた場合、ファイル内容のすべてを共有できるとは限らない。アプリケーションがディスク上の実際の名前付きファイルのサイズよりも大きいファイルマッピングオブジェクトのサイズを指定し、かつページ保護が書き込みアクセスを許可する場合（すなわち
flProtect パラメータが PAGE_READWRITE または PAGE_EXECUTE_READWRITE
を指定する場合）、ディスク上のファイルは指定されたファイルマッピングオブジェクトのサイズに合うよう拡張される。ファイルが拡張された場合、古い終端と新しい終端の間の内容がゼロであることは保証されない。動作はファイルシステムによって定義される。ディスク上のファイルを拡張できない場合、CreateFileMapping
は失敗し GetLastError は ERROR_DISK_FULL を返す。OS
のページングファイルがバックするファイルマッピングオブジェクトのページの初期内容はゼロである。CreateFileMapping
が返すハンドルは新しいファイルマッピングオブジェクトへのフルアクセスを持ち、ファイルマッピングオブジェクトへのハンドルを必要とする任意の関数で使用できる。複数のプロセスは同じファイルをバックとする単一の共有ファイルマッピングオブジェクトを使うか、同じファイルをバックとする別々のファイルマッピングオブジェクトを作成して、同じファイルのビューを共有できる。単一のファイルマッピングオブジェクトは、プロセス作成時にハンドルを継承する、ハンドルを複製する、または名前でファイルマッピングオブジェクトを開くことで複数のプロセス間で共有できる。詳細は
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
から導入された。ファイルビューへの書き込みや読み込みを行うコードを保護するには構造化例外処理を使う。詳細は Reading and
Writing From a File View を参照。実行可能な権限を持つマッピングを作成するには、アプリケーションは
PAGE_EXECUTE_READWRITE または PAGE_EXECUTE_READ で CreateFileMapping
を呼び、その後 FILE_MAP_EXECUTE | FILE_MAP_WRITE または FILE_MAP_EXECUTE |
FILE_MAP_READ で MapViewOfFile を呼ぶ必要がある。Windows Server 2012
では、この関数は以下の技術でサポートされている。
（以下省略）

情報