CreateFileMapping(A)

指定されたファイルに対するファイルマッピングオブジェクトを作成またはオープンします。

HANDLE CreateFileMappingA(
    HANDLE  hFile,            // file handle
    PSECURITY_ATTRIBUTES psa, // security attributes
    DWORD   fdwProtect,       // protect attributes
    DWORD   dwMaxSizeHigh,    // size (high DWORD)
    DWORD   dwMaxSizeLow,     // size (low DWORD)
    PCTSTR  pszName           // object name
);

KERNEL32.DLL

引数

hFile

マッピングオブジェクトを作成するためのファイルのハンドルを指定します。これはCreateFile関数などによって取得されるものです。このファイルハンドルは、fdwProtectで指定される保護属性と矛盾しないアクセス権を持っていなければいけません。マッピングするファイルが排他アクセスでオープンされていることが推奨されます(必須ではありません)。

-1 (INVALID_HANDLE_VALUE) を指定すると、ファイルシステム上で名前の付けられたファイルではなくオペレーティングシステムのページングファイルによって支持された、指定サイズのファイルマッピングオブジェクトを作成します。この場合には、dwMaxSizeHighおよびdwMaxSizeLowパラメータにオブジェクトサイズを指定しなければいけません。マッピングオブジェクトは複製や継承や名前を介して共有することができます。ファイルマッピングオブジェクト内のページの内容は初期状態でゼロになっています。

psa

返されるハンドルを子プロセスへ継承するかどうかを決定するSECURITY_ATTRIBUTES構造体へのポインタを指定します。psaパラメータに0 (NULL) を指定するとハンドルは継承されません。

SECURITY_ATTRIBUTES構造体のlpSecurityDescriptorメンバは、新しいファイルマッピングオブジェクトに対するセキュリティ記述子を指定します。psaパラメータに0 (NULL) を指定すると、ファイルマッピングオブジェクトはデフォルトのセキュリティ記述子が取得します。

fdwProtect

ファイルがマッピングされたときにファイルビューに要求する保護を指定します。以下の値のいずれかを指定することができます。

0x00000002 (PAGE_READONLY)

コミットされたページ領域への読み取り専用アクセスを与えます。コミット領域への書き込みもしくはコード実行を行おうとするとアクセス違反が発生します。hFileパラメータで指定されたファイルはGENERIC_READアクセス権を持っていなければいけません。

0x00000004 (PAGE_READWRITE)

コミットされたページ領域への読み取り・書き込みアクセスを取得します。hFileパラメータで指定されたファイルはGENERIC_READおよびGENERIC_WRITEアクセス権を持っていなければいけません。

0x00000008 (PAGE_WRITECOPY)

コミットされたページ領域へのコピーオンライトアクセスを与えます。hFileパラメータで指定されたファイルはGENERIC_READおよびGENERIC_WRITEアクセス権を持っていなければいけません。

さらに、上記のページ保護属性に加えて、以下のセクション属性値を組み合わせて指定することができます。

0x1000000 (SEC_IMAGE)

セクションのファイルマッピングに対して指定されたファイルは実行可能イメージファイルです。マッピング情報およびファイル保護属性はイメージファイルから取得されるため、他の属性をSEC_IMAGEとともに指定することはできません。

Windows 95/98/Me: このフラグはサポートされません。

0x4000000 (SEC_RESERVE)

セクションの全ページを予約します。物理ストレージの確保は行いません。予約されたページ領域は、その領域が解放されるまで、他のメモリ確保操作によって使用されることはありません。後でVirtualAlloc関数を呼び出して予約ページをコミットすることができます。この属性は、hFileパラメータがINVALID_HANDLE_VALUEである場合にのみ有効です。

0x8000000 (SEC_COMMIT)

セクションの全ページに対して、メモリ内もしくはディスク上ページングファイル内の物理ストレージを確保します。これはデフォルトの設定です。

0x10000000 (SEC_NOCACHE)

セクションの全ページをキャッシュ不可に設定します。この属性は、種々のロック構造体がメモリ内に置かれるようにし、プロセッサ内のキャッシュメモリに置かれないようにするために用いられます。80x86マシンおよびMIPSマシン上では、これらの構造体に対してキャッシュを使用しても、ハードウェアがキャッシュの一貫性を保持しようとする際におけるパフォーマンス低下しか引き起こしません。いくつかのデバイスドライバはプログラムが物理メモリにしっかりと書き込まれるように非キャッシュのデータを要求します。SEC_NOCACHEを指定するには、SEC_RESERVEまたはSEC_COMMITのいずれかをともに指定する必要があります。

Windows 95/98/Me: このフラグはサポートされません。

dwMaxSizeHigh

ファイルマッピングオブジェクトの最大サイズの上位32ビットを指定します。

Windows 95/98/Me: このパラメータは無視されます。

dwMaxSizeLow

ファイルマッピングオブジェクトの最大サイズの下位32ビットを指定します。

dwMaxSizeHighパラメータおよびdwMaxSizeLowパラメータにともに0を指定すると、ファイルマッピングオブジェクトの最大サイズはhFileパラメータで指定されたファイルの現在のサイズと同じになります。

この方法でサイズがゼロのファイルをマッピングしようとすると、関数は失敗して拡張エラーコード1006 (ERROR_FILE_INVALID) を返します。アプリケーションはサイズがゼロのファイルをチェックして、そのようなファイルを除外するべきです。

pszName

ファイルマッピングオブジェクトの名前を示す文字列へのポインタを指定します。

指定された名前が既存の名前つきマッピングオブジェクトの名前と一致すると、関数はマッピングオブジェクトへのアクセスをfdwProtectで指定される保護属性で要求します。

このパラメータに0 (NULL) を指定すると、名前を持たないマッピングオブジェクトが作成されます。

指定された名前が既存のイベント、セマフォ、ミューテックス、ウェイタブルタイマー、ジョブオブジェクトの名前と一致すると、関数は失敗して拡張エラーコード6 (ERROR_INVALID_HANDLE) を返します。これは、これらのオブジェクトが同じ名前空間を共有しているために起こります。

ターミナルサービス: 名前は“Global\”または“Local\”プレフィックスを付けて、明示的にグローバル名前空間またはセッション名前空間にオブジェクトを作成することができます。名前の残りの部分には、バックスラッシュ文字(\)以外のすべての文字を使用することができます。

Windows XP: 高速なユーザー切り替えがターミナルサービスセッションにより提供されています。最初のログオンユーザーがセッション0を使用し、次のユーザーがセッション1を使用し、…となっています。アプリケーションが複数ユーザーをサポートすることができるように、カーネルオブジェクトの名前はターミナルサービスに関して記述されているガイドラインに従わなくてはいけません。

Windows 2000: ターミナルサービスが実行されていない場合、“Global\”および“Local\”プレフィックスは無視されます。名前の残りの部分には、バックスラッシュ文字(\)以外のすべての文字を使用することができます。

Windows 95/98/Me: 名前にはバックスラッシュ文字(\)以外のすべての文字を使用することができます。空文字列(“”)も有効なオブジェクト名として扱われます。

戻り値

成功すると、作成されたマッピングオブジェクトのハンドルが返ります。すでに存在するオブジェクトのハンドルが返された場合、関数は既存のオブジェクトのハンドルを返し、直後に呼び出されたGetLastError関数は183 (ERROR_ALREADY_EXISTS) を返します。このとき、ファイルマッピングオブジェクトのサイズは指定されたものにはならずに、既存のオブジェクトのサイズのままになります。

失敗すると0 (NULL) が返ります。拡張エラー情報を取得するには、GetLastError関数を使います。

解説

ファイルマッピングオブジェクトを作成した後で、ファイルサイズをファイルマッピングオブジェクトのサイズ以上に拡張してはいけません。サイズ拡張を行うと、ファイルの内容全体を共有に利用することができなくなります。

ディスク上のファイルそのもののサイズよりも大きいサイズをファイルマッピングオブジェクトに対して指定すると、ディスク上のファイルが指定されたファイルマッピングオブジェクトのサイズと一致するように拡張されます。ファイルサイズを拡張させることができない場合には、ファイルマッピングオブジェクトの作成は失敗し、拡張エラーコード112 (ERROR_DISK_FULL)を返します。

CreateFileMapping関数が返したハンドルは、新しいファイルマッピングオブジェクトに対する全アクセス権を持ちます。このハンドルは、ファイルマッピングオブジェクトのハンドルを必要とする関数で使用することができます。プロセスの作成、ハンドルの複製、あるいはオブジェクトの名前を介して、ファイルマッピングオブジェクトを共有することができます。

Windows Me/98/95: ファイルマッピングオブジェクトを作成するのに使用されたファイルハンドルを、ReadFile関数やWriteFile関数などのファイルI/O関数の呼び出しで使用してはいけません。一般に、CreateFileMapping関数の呼び出しで使用されたファイルハンドルは、ファイルマッピングオブジェクトがクローズされるまで使用してはいけません。

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

単一のファイルマッピングオブジェクトから生成されたファイルビューは、任意の時点での整合性を持ちます。すなわち、それらのビューの内容がある時点で同一であることが保証されます。複数のプロセスが同じファイルマッピングオブジェクトに対するハンドルを持っている場合、それらのプロセスは、ファイルビューをマッピングしたときに整合性のあるビューを参照することができます。

ただし、リモートファイルに関しては例外です。CreateFileMapping関数をリモートファイルに対して使用することはできますが、その整合性は保たれません。例えば、2つのコンピュータが同じファイルを書き込み可能でマッピングし、両方が同時に同じページを書き換えると、それぞれのコンピュータからは、自身が書き換えたページ内容しか参照されません。データがディスク上で更新される際にこれらは統合されません。

マッピングされたファイルと、ReadFile関数やWriteFile関数などのファイルI/O関数によりアクセスされるファイルとの間には、整合性が保証されません。

オブジェクトを完全にクローズするには、UnmapViewOfFile関数を呼び出してファイルマッピングオブジェクトのすべてのマッピングされているビューをマッピング解除し、CloseHandle関数を呼び出してオブジェクトのハンドルをクローズしなければいけません。これらの関数を呼び出す順序は重視されません。ファイルマッピングオブジェクトのビューは内部でオープンされたオブジェクトハンドルを保持しており、オープンされているすべてのハンドルがクローズされない限りファイルマッピングオブジェクトはクローズされないため、UnmapViewOfFile関数の呼び出しは必須です。

ターミナルサービスのセッションは、共有メモリブロックを使用して、それらのセッションで生成されたプロセス間でデータを転送することができます。この場合には、以下の条件が同時に存在するような状況下では共有メモリを使用することができないということに留意しておく必要があります。

アクセス違反を防ぐには、構造化例外処理を使用してメモリマッピングされたビューへの書き込みや読み取りをしているコードを保護します。

対応情報

Windows 95 以降 / Windows NT 3.1 以降