CreateFile(A)

ファイル、ディレクトリ、物理ディスク、ボリューム、コンソールバッファ、テープドライブ、通信リソース、メールスロット、パイプのいずれかのオブジェクトを作成またはオープンし、そのオブジェクトにアクセスするために必要となるオブジェクトハンドルを返します。

Windows 95/98/Me： この関数を使用してディレクトリ、物理ディスク、ボリュームをオープンすることはできません。

HANDLE CreateFileA(
    PCTSTR pszFileName,          // ファイル名
    DWORD  dwAccess,             // アクセス指定
    DWORD  dwShare,              // 共有方法
    PSECURITY_ATTRIBUTES psa,    // セキュリティ属性
    DWORD  dwCreateDisposition,  // 動作指定
    DWORD  dwFlagsAndAttributes, // フラグと属性
    HANDLE hTemplate             // テンプレートファイル
);

KERNEL32.DLL

引数

pszFileName

作成またはオープンするオブジェクトの名前を表す文字列のアドレスを指定します。

パス名を指定する場合は、最大文字数は260 (MAX_PATH) 文字です。

ANSI版の関数では、この文字列は最大260 (MAX_PATH) 文字に制限されます。Unicode版関数（CreateFileW関数）を使用し、パス名の前に "\\?\" プレフィックスを付けることで、最大32,767文字の長い文字列を指定することができます。

Windows 95/98/Me： この文字列は最大260 (MAX_PATH) 文字でなければいけません。

dwAccess

オブジェクトへのアクセス権の種類を指定します。以下の値の組み合わせで指定します。

0x00000000

デバイスへのアクセスを行なうことなく、デバイスの属性を問い合わせます。例えば、フロッピーディクスドライブのサイズやサポートされるフォーマットの決定を、ドライブの中のフロッピーディクスにアクセスすることなく決定することができます。また、ファイルやディレクトリが存在するかどうかを確認することにも使用できます。

0x40000000 (GENERIC_WRITE)

書き込みアクセスです。データの書き込みとファイルポインタの移動ができます。読み書きアクセスをするには、GENERIC_READと組み合わせて指定します。

0x80000000 (GENERIC_READ)

読み取りアクセスです。データの読み取りとファイルポインタの移動ができます。

dwShare

オブジェクトの共有モードを指定します。すでにオープンされているハンドルで指定されたアクセス共有モードと競合する共有モードを要求することはできません。

以下の値のいずれか、または組み合わせで指定します。これらの共有オプションの効果は、返されたハンドルがクローズされるまで持続します。

0x00000000

他の値が指定されない場合は、オブジェクトは共有されません。ハンドルをクローズしない限り、これ以降のこのオブジェクトへのオープン操作は失敗します。

0x00000001 (FILE_SHARE_READ)

後続のオープン操作で読み取りアクセスが要求された場合、そのオープンを許可します。

すでに読み取りアクセス要求とともにオープンされているオブジェクトをオープン場合には、このフラグが含まれないとオープン操作は失敗します。

0x00000002 (FILE_SHARE_WRITE)

後続のオープン操作で書き込みアクセスが要求された場合、そのオープンを許可します。

すでに書き込みアクセス要求とともにオープンされているオブジェクトをオープン場合には、このフラグが含まれないとオープン操作は失敗します。

0x00000004 (FILE_SHARE_DELETE)

後続のオープン操作で削除アクセスが要求された場合、そのオープンを許可します。

すでに削除アクセス要求とともにオープンされているオブジェクトをオープン場合には、このフラグが含まれないとオープン操作は失敗します。

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

psa

取得したハンドルの子プロセスへの継承を許可するかどうかを決めるSECURITY_ATTRIBUTES構造体へのポインタを指定します。0 (NULL) を指定すると、ハンドルは継承されません。

この構造体のlpSecurityDescriptorメンバでセキュリティ記述子を設定します。このメンバに0 (NULL) を指定するとデフォルトのセキュリティ記述子が使用されます。ファイルやディレクトリに対するデフォルトのセキュリティ記述子のアクセスコントロールリスト (Access Control List; ACL) は、親ディレクトリから継承されます。このパラメータが効果を持つためには、対象のファイルシステムがファイル・ディレクトリのセキュリティをサポートしている必要があります。すでに存在するファイルに対しては、このセキュリティ記述子の指定は無視されます。

dwCreateDisposition

ファイルが存在するとき、または存在しないときのそれぞれの動作を指定します。次の値のいずれかを指定します。

1 (CREATE_NEW)

新しいファイルを作成します。指定ファイルがすでに存在している場合、関数は失敗します。

2 (CREATE_ALWAYS)

新しいファイルを作成します。指定ファイルがすでに存在している場合、そのファイルは上書きされます。このとき、既存の属性はクリアされ、指定されたファイル属性およびFILE_ATTRIBUTE_ARCHIVEが設定されますが、指定されたセキュリティ記述子は設定されません。

3 (OPEN_EXISTING)

ファイルをオープンします。指定ファイルが存在していない場合、関数は失敗します。

デバイス上 (コンソールも含む) でこの関数を使う場合は、このフラグを指定しなければなりません。

4 (OPEN_ALWAYS)

ファイルをオープンします。指定ファイルが存在していない場合、新しいファイルを作成します。

5 (TRUNCATE_EXISTING)

ファイルをオープンし、ファイルのサイズを0バイトにします。指定ファイルが存在していない場合、関数は失敗します。dwAccessパラメータで、少なくともGENERIC_WRITEアクセス権を指定しなければなりません。

dwFlagsAndAttributes

ファイルの属性およびフラグを組み合わせて指定します。

ファイルの属性を以下の値の組み合わせで指定します。これらのどの属性も指定されなかった場合は、FILE_ATTRIBUTE_NORMALで上書きされます。

0x00000001 (FILE_ATTRIBUTE_READONLY)

読み取り専用属性を持ちます。アプリケーションは、この属性を持つファイルを読み込むことができますが、書き込んだり削除したりすることはできません。この属性を持つディレクトリを削除することはできません。

0x00000002 (FILE_ATTRIBUTE_HIDDEN)

隠しファイル属性を持ちます。通常のディレクトリリスト出力には含まれないようになります。

0x00000004 (FILE_ATTRIBUTE_SYSTEM)

システム属性を持ちます。オペレーティングシステムの一部もしくはオペレーティングシステムにより使用されるファイルです。

0x00000020 (FILE_ATTRIBUTE_ARCHIVE)

アーカイブ属性を持ちます。アプリケーションは、バックアップや修復のためにファイルをマークするのにこの属性を用います。

0x00000080 (FILE_ATTRIBUTE_NORMAL)

ほかのどの属性も設定されていません。この属性フラグが単独で指定された場合のみ有効です。

0x00000100 (FILE_ATTRIBUTE_TEMPORARY)

一時ストレージ（一時記憶領域として利用されている領域）として使用されることを指定します。多くのアプリケーションはファイルハンドルをクローズした後すぐに一時ファイルを削除するので、キャッシュメモリが利用可能な場合は、キャッシュを利用します。

0x00001000 (FILE_ATTRIBUTE_OFFLINE)

ファイルのデータが直接に利用できるものではないことを示します。この属性は、ファイルデータがオフラインストレージへ物理的に移動されたものであることを示します。この属性はリモートストレージ（階層ストレージ管理ソフトウェア）によって利用されます。アプリケーションはこの属性を変更するべきではありません。

0x00002000 (FILE_ATTRIBUTE_NOT_CONTENT_INDEXED)

ファイルがコンテンツインデックスサービスによってインデックス付けられないことを示します。

0x00004000 (FILE_ATTRIBUTE_ENCRYPTED)

暗号化属性を持ちます。この属性を持つファイルはデータが暗号化されていることを示します。この属性を持つディレクトリは、このディレクトリの中に新しく作成されるファイルやサブディレクトリがデフォルトで暗号化属性を持つことを示します。

FILE_ATTRIBUTE_SYSTEMフラグがともに指定されている場合は、このフラグは無効になります。

以下のオプションフラグを組み合わせで指定することができます。

0x80000000 (FILE_FLAG_WRITE_THROUGH)

キャッシュに書き込まれたデータをそのまま直接ディスクに書き込むようにします。

FILE_FLAG_NO_BUFFERINGがともに指定されていない場合、システムキャッシュが有効となり、書き込まれたデータはシステムキャッシュに書き込まれ、直ちにディスクへフラッシュされます。

FILE_FLAG_NO_BUFFERINGがともに指定されている場合、システムキャッシュが無効となるため、書き込まれたデータはシステムキャッシュに書き込まれることなく、直ちにディスクへフラッシュされます。

0x40000000 (FILE_FLAG_OVERLAPPED)

時間のかかる処理に対してReadFile関数やWriteFile関数でERROR_IO_PENDING拡張エラーを返すようにします。処理が終了すると、イベントがシグナル状態に設定されます。

このフラグを指定したときは、ReadFile関数やWriteFile関数でOVERLAPPED構造体を指定しなければなりません。

このフラグが指定されると、ファイルポインタが保持されません。ファイル入出力関数を呼び出す際には、OVERLAPPED構造体にファイル位置を含めて渡さなければなりません。

このフラグにより、ファイルに対して複数の操作を同時に行うことが可能になります（例えば、読み取り・書き込み操作を同時に行うなど）。

0x20000000 (FILE_FLAG_NO_BUFFERING)

システムキャッシュを使用せずにファイルをオープンするように指定します。このフラグは、ハードディスクキャッシュには影響しません。FILE_FLAG_OVERLAPPEDフラグとともに指定されると、入出力がメモリマネージャの同期処理に依存しないので、最大の非同期のパフォーマンスが得られます。ただし、データがキャッシュに保管されないため、パフォーマンスが低下する入出力処理もあります。また、ファイルのメタデータはまだキャッシュされる可能性があります。メタデータをディスクにフラッシュされるには、FlushFileBuffers関数を使います。

このフラグを指定したときは、ファイルアクセスの開始オフセット、ファイルのアクセスのバイト数、読み書き操作用のバッファのアドレスを、ボリュームのセクタサイズの整数倍にしなければなりません。（ボリュームのセクタサイズを求めるにはGetDiskFreeSpace関数を使います。）

0x10000000 (FILE_FLAG_RANDOM_ACCESS)

ファイルにランダムアクセスすることをシステムに示します。システムは、ランダムアクセス用に最適化されたファイルキャッシングを行います。

0x08000000 (FILE_FLAG_SEQUENTIAL_SCAN)

ファイルにシーケンシャルアクセス（最初から終わりに向かって連続的にアクセス）することをシステムに示します。システムは、シーケンシャルアクセス用に最適化されたファイルキャッシングを行ないます。このフラグを指定しても、ランダムアクセスができなくなるわけではありません。

0x04000000 (FILE_FLAG_DELETE_ON_CLOSE)

そのファイルを指すすべてのファイルのハンドルがクローズされた時に、そのファイルを削除するように指定します。

指定されたファイルのオープンされているハンドルがすでに存在している場合は、それらすべてのハンドルがFILE_SHARE_DELETE共有モードでオープンされていない限り、関数呼び出しは失敗します。

以降の同じファイルに対するオープン要求は、FILE_SHARE_DELETE共有モードが指定されない限り失敗します。

0x02000000 (FILE_FLAG_BACKUP_SEMANTICS)

バックアップまたは復元操作のために、ファイルをオープンまたは作成します。SE_BACKUP_NAMEおよびSE_RESTORE_NAME特権を持っている場合に、呼び出しプロセスがファイルセキュリティチェックをオーバーライドすることを保証します。

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

0x01000000 (FILE_FLAG_POSIX_SEMANTICS)

POSIXの規則に従ってファイルにアクセスします。このフラグを使って作成したファイルには、MS-DOSおよび16ビットWindowsアプリケーションからはアクセスできません。

0x00200000 (FILE_FLAG_OPEN_REPARSE_POINT)

NTFSファイルシステムのリパースポイント機能の動作を禁止します。ファイルが開かれると、リパースポイントを制御するフィルタが使用可能かどうかに関わらず、ファイルハンドルが返ります。このフラグはCREATE_ALWAYSとともに指定することはできません。

0x00100000 (FILE_FLAG_OPEN_NO_RECALL)

ファイルが引き続きリモートストレージに留まるように指定します。これにより、ファイルがローカルストレージに移されないようにします。

名前付きパイプのクライアント側をオープンする場合は、セキュリティクォリティオブサービス (Security Quality of Service) 情報を指定できます。呼び出し側アプリケーションがこのパラメータに0x00100000 (SECURITY_SQOS_PRESENT) を同時に指定している場合、このパラメータには、次の値の組み合わせを指定できます。

0x00000000 (SECURITY_ANONYMOUS)

匿名 (Anonymous) 偽装レベルでクライアントを偽装します。

0x00010000 (SECURITY_IDENTIFICATION)

確認 (Identification) 偽装レベルでクライアントを偽装します。

0x00020000 (SECURITY_IMPERSONATION)

偽装 (Impersonation) 偽装レベルでクライアントを偽装します。

0x00030000 (SECURITY_DELEGATION)

代理 (Delegation) 偽装レベルでクライアントを偽装します。

0x00040000 (SECURITY_CONTEXT_TRACKING)

セキュリティトラッキングモードが動的であることを指定します。このフラグを指定しない場合、セキュリティトラッキングモードは静的です。

0x00080000 (SECURITY_EFFECTIVE_ONLY)

クライアントのセキュリティコンテキストのうち、有効になっている部分だけをサーバーで利用できるようにします。このフラグを指定しない場合は、すべての部分が利用できます。

hTemplate

テンプレートファイルへのGENERIC_READアクセスを持つハンドルを指定します。テンプレートファイルは、作成しているファイルに対して、ファイル属性と拡張属性を提供します。0 (NULL) を指定することができます。

既存のファイルをオープンする場合は、この指定は無視されます。

Windows 95/98/Me： 0 (NULL) を指定しなければいけません。ハンドルを指定すると、関数は失敗します。

戻り値

関数が成功すると指定したオブジェクトのハンドルが返ります。

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

dwCreateDispositionパラメータでCREATE_ALWAYSまたはOPEN_ALWAYSを指定しており、pszFileNameパラメータで指定したファイルがすでに存在している場合には、（関数が成功したときでも）GetLastError関数は183 (ERROR_ALREADY_EXISTS) を返します。存在していなければ0を返します。

解説

オブジェクトのハンドルが不要になったら、CloseHandle関数でハンドルをクローズしなければなりません。

Windows 2000/XP/Server 2003： リモートコンピュータ上のファイルやディレクトリを削除のためにオープンしようとするとき、dwDesiredAccessにDELETEフラグと別のアクセスフラグとを組み合わせて指定していて、かつ、そのリモートファイルやディレクトリがFILE_SHARE_DELETE共有モードでオープンされていない場合には、共有違反が発生します。このような共有違反を避けるには、そのファイルやディレクトリをオープンする際にDELETEアクセスのみを指定します。

NTFSなど、いくつかのファイルシステムでは、特定のファイルやディレクトリに対する圧縮や暗号化がサポートされています。そのようなファイルシステムでフォーマットされているボリューム上では、新しいファイルはその親ディレクトリの圧縮または暗号化属性を継承します。ただし、CreateFile関数を使用してファイルやディレクトリの圧縮を制御することはできません。

ファイル

フロッピーディスクが入っていないフロッピードライブ上、またはCDが入っていないCD-ROMドライブ上にファイルを作成またはオープンしようとすると、システムはメッセージボックスを表示して、ユーザーにディスクやCDを挿入するように求めます。メッセージボックスが表示されないようにするには、SetErrorMode関数でSEM_FAILCRITICALERRORSを指定します。

Windows 2000/XP/Server 2003： FILE_ATTRIBUTE_HIDDEN属性またはFILE_ATTRIBUTE_SYSTEM属性を持っている既存のファイルを、CREATE_ALWAYSおよびFILE_ATTRIBUTE_NORMALを指定してオープンすると、CreateFile関数は失敗し、GetLastError関数は5 (ERROR_ACCESS_DENIED) を返します。これを避けるには、既存のファイルと同じ属性を指定します。

ファイルを名前変更または削除し、その後すぐに元に戻す場合、システムはキャッシュから復元するためのファイル情報をたどります。キャッシュされている情報には、長いファイル名／短いファイル名および作成時刻が含まれています。

Windows 95/98/Me： この記述は適用されません。

同一のファイルを多重にオープンしようとすると、それぞれの呼び出しの共有モードおよびアクセスモードによっては、共有違反を起こす可能性があります。

以前のDeleteFile呼び出しによって削除されようとしているファイルに対してCreateFile関数を呼び出すと、関数は失敗し、GetLastError関数は5 (ERROR_ACCESS_DENIED) を返します。オペレーティングシステムは、すべてのハンドルがクローズされるまでファイル削除を遅らせます。

ディレクトリ

アプリケーションはCreateFile関数でディレクトリを作成することができません。ディレクトリの作成にはCreateDirectory関数またはCreateDirectoryEx関数を呼び出します。CreateFile関数によるディレクトリ操作ではFILE_FLAG_BACKUP_SEMANTICSフラグを指定する必要があります。

FATまたはFAT32ボリュームのデフラグを実行中にCreateFile関数を使ってディレクトリをオープンするとき、MAXIMUM_ALLOWEDアクセス権を指定してはいけません。指定した場合には、ディレクトリへのアクセスは拒否されます。代わりに、GENERIC_READアクセス権を指定します。

物理ディスク・ボリューム

CreateFile関数を使って物理ディスクまたはボリュームをオープンすることができます。この関数は、DeviceIoControl関数で使用することができるハンドルを返します。これにより、ディスクのパーティションテーブルにアクセスすることができます。パーティションテーブルへのアクセスを行う場合、不正な書き込みによって内容にアクセスできなくなる危険性が伴います。呼び出しを成功させるには、以下の条件が必要です。

番号xの物理ドライブをオープンするには、pszFileNameパラメータの文字列は“\\.\PHISICALDRIVEx”の形式で指定します。ハードディスク番号はゼロから始まります。以下の表は、物理デバイス文字列の例を示しています。

文字列 意味
\\.\PHYSICALDRIVE0 最初の物理ドライブをオープンします。
\\.\PHYSICALDRIVE2 3番目の物理ドライブをオープンします。

ドライブ名xのボリュームやフロッピードライブをオープンするには、pszFileNameパラメータの文字列は“\\.\x:”の形式で指定します。以下の表は、ドライブ文字列の例を示しています。

文字列 意味
\\.\A: ドライブA（フロッピードライブ）をオープンします。
\\.\C: ドライブC（ボリューム）をオープンします。

また、ボリュームをそのボリューム名で指定することもできます。

ファイルシステムによっては、キャッシュを無効化するオプションを指定しなくても、ボリュームハンドルが非キャッシュでオープンされる可能性があります。すべてのMicrosoftファイルシステムはボリュームハンドルを非キャッシュでオープンされると想定するべきです。ファイルに対しての非キャッシュI/Oの制約が、ボリュームに対しても適用されます。

ファイルシステムによっては、データが非キャッシュの場合でも、バッファのアライメントを要求されない可能性もあります。しかし、ボリュームオープン時にキャッシュを無効化するオプションを指定した場合には、ボリューム上のファイルシステムとは関係なく、バッファアライメントが強制されます。ボリュームハンドルを非キャッシュでオープンし、非キャッシュI/Oの制約を守ることが、すべてのファイルシステム上で推奨されます。

テープドライブ

CreateFile関数を使ってテープドライブをオープンすることができます。番号xのテープドライブをオープンするには、pszFileNameパラメータの文字列は“\\.\TAPEx”の形式で指定します。例えば、最初のテープドライブをオープンするには、文字列“\\.\TAPE0”を指定します。

Windows 95/98/Me： テープドライブのオープンはサポートされません。

通信リソース

CreateFile関数を使ってシリアルポートCOM1などのような通信リソースをオープンすることができます。通信リソースをオープンする場合には、dwCreateDispositionにOPEN_EXISTINGを、hTemplateには0 (NULL) をそれぞれ指定しなければなりません。読み取りアクセス、書き込みアクセス、および読み取り／書き込みアクセスを指定することができます。また、オーバーラップI/Oの目的でハンドルをオープンすることができます。

コンソール

CreateFile関数を使ってコンソール入力 (CONIN$) をオープンすることができます。また、ハンドルの継承または複製によって、プロセスがオープンされたコンソール入力のハンドルを持っている場合は、アクティブスクリーンバッファ (CONOUT$) のハンドルを作成することができます。呼び出しプロセスは、継承されたコンソールもしくはAllocConsole関数により割り当てられたコンソールに属していなければなりません。コンソールハンドル取得のためのパラメータは以下のようになります。

pszFileName

コンソール入力を指定する場合にはCONIN$値を、コンソール出力を指定する場合にはCONOUT$値を使います。

CONIN$値を指定すると、SetStdHandle関数で標準入力ハンドルのリダイレクションを行っている場合であっても、コンソール入力バッファのハンドルが取得されます。標準入力のハンドルを取得するにはSetStdHandle関数を使います。

CONOUT$値を指定すると、SetStdHandle関数で標準出力ハンドルのリダイレクションを行っている場合であっても、コンソール出力バッファのハンドルが取得されます。標準出力のハンドルを取得するにはSetStdHandle関数を使います。

dwAccess

0xC0000000 (GENERIC_READ|GENERIC_WRITE) を指定することが好ましいです。どちらか一方だけではアクセスが制限される可能性があります。

dwShare

CONIN$をオープンする場合には、0x00000001 (FILE_SHARE_READ) を指定しなければなりません。CONOUT$をオープンする場合には、0x00000002 (FILE_SHARE_WRITE) を指定しなければなりません。

呼び出しプロセスがコンソールを継承する場合、または、子プロセスがコンソールにアクセスできるようにする場合には、FILE_SHARE_READ|FILE_SHARE_WRITEを指定しなければなりません。

psa

コンソールを継承させる場合には、SECURITY_ATTRIBUTES構造体のbInheritHandleメンバに1 (TRUE) を指定します。

dwCreateDisposition

3 (OPEN_EXISTING) を指定しなければなりません。

dwFlagsAndAttributes

無視されます。

hTemplate

無視されます。

pszFileNameにCONを、dwAccessにGENERIC_READを指定すると、入力用にコンソールハンドルをオープンします。pszFileNameにCONを、dwAccessにGENERIC_WRITEを指定すると、出力用にコンソールハンドルをオープンします。pszFileNameにCONを、dwAccessにGENERIC_READ|GENERIC_WRITEを指定すると、関数は失敗します。

メールスロット

CreateFile関数を使ってメールスロットのクライアントエンドをオープンする際に、メールスロットサーバーがCreateMailSlot関数でローカルメールスロットを作成するより前にメールスロットクライアントがそのローカルメールスロットをオープンしようとした場合、関数は-1 (INVALID_HANDLE_VALUE) を返します。

パイプ

CreateFile関数を使って名前つきパイプのクライアントエンドをオープンする際に、関数はリスニング状態にある名前つきパイプのすべてのインスタンスを使用します。オープンしているプロセスは、要求と同じ数だけハンドルを複製することができますが、いったんオープンされると、別のクライアントがその名前つきパイプのインスタンスをオープンすることはできません。パイプがオープンされるときに指定されたアクセスは、CreateNamedPipe関数のdwOpenModeパラメータで指定されるアクセスと互換性があります。

対応情報

Windows 95 以降 / Windows NT 3.1 以降