CreateFileA 関数 (fileapi.h)

ファイルまたは I/O デバイスを作成または開きます。 最も一般的に使用される I/O デバイスは、ファイル、ファイル ストリーム、ディレクトリ、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、通信リソース、メールスロット、パイプです。 関数は、ファイルまたはデバイス、および指定されたフラグと属性に応じて、さまざまな種類の I/O のファイルまたはデバイスにアクセスするために使用できるハンドルを返します。

この操作をトランザクション操作として実行し、トランザクション I/O に使用できるハンドルを作成するには、 CreateFileTransacted 関数を使用します。

構文

HANDLE CreateFileA(
  [in]           LPCSTR                lpFileName,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwCreationDisposition,
  [in]           DWORD                 dwFlagsAndAttributes,
  [in, optional] HANDLE                hTemplateFile
);

パラメーター

[in] lpFileName

作成または開くファイルまたはデバイスの名前。 この名前にはスラッシュ (/) または円記号 (\) を使用できます。

既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前もって指定しなくても、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 名前付けファイル、パス、および名前空間 」の「パスの最大長制限」セクションを参照してください。

特殊なデバイス名については、「 MS-DOS デバイス名の定義」を参照してください。

ファイル ストリームを作成するには、ファイルの名前、コロン、ストリームの名前を指定します。 詳細については、「 ファイル ストリーム」を参照してください。

[in] dwDesiredAccess

ファイルまたはデバイスへの要求されたアクセス。読み取り、書き込み、両方または 0 として要約してどちらも示すことができます)。

最も一般的に使用される値は、 GENERIC_READ、 GENERIC_WRITE、またはその両方 (GENERIC_READ | GENERIC_WRITE) です。 詳細については、「汎用アクセス権」、「ファイル セキュリティとアクセス権」、「ファイル アクセス権定数」、「ACCESS_MASK」を参照してください。

このパラメーターが 0 の場合、アプリケーションはファイル、ディレクトリ、デバイスの属性などの特定のメタデータに対してクエリを実行できますが、そのファイルやデバイスにアクセスしなくても、 GENERIC_READ アクセスは拒否されます。

既に開いているハンドルを持つオープン要求の dwShareMode パラメーターで指定された共有モードと競合するアクセス モードを要求することはできません。

詳細については、このトピックの「備考」および「 ファイルの作成と開く」を参照してください。

[in] dwShareMode

ファイルまたはデバイスの要求された共有モード。読み取り、書き込み、両方、削除、これらすべて、またはなし (次の表を参照)。 属性または拡張属性に対するアクセス要求は、このフラグの影響を受けません。

このパラメーターが 0 で 、CreateFile が成功した場合、ファイルまたはデバイスを共有できず、ファイルまたはデバイスへのハンドルが閉じられるまで、もう一度開くことができません。 詳細については、「解説」を参照してください。

開いているハンドルを持つ既存の要求で指定されているアクセス モードと競合する共有モードを要求することはできません。 CreateFile は失敗し、 GetLastError 関数は ERROR_SHARING_VIOLATIONを返します。

別のプロセスがファイルまたはデバイスを開いている間にプロセスでファイルまたはデバイスを共有できるようにするには、次の値の 1 つ以上の互換性のある組み合わせを使用します。 このパラメーターと dwDesiredAccess パラメーターの有効な組み合わせの詳細については、「 Creating and Opening Files」を参照してください。

メモ 開いている各ハンドルの共有オプションは、プロセス コンテキストに関係なく、そのハンドルが閉じられるまで有効です。

 

値	意味
0 0x00000000	他のプロセスが削除、読み取り、または書き込みアクセスを要求した場合に、他のプロセスがファイルまたはデバイスを開かないようにします。
FILE_SHARE_DELETE 0x00000004	ファイルまたはデバイスに対する後続のオープン操作を有効にして、削除アクセスを要求します。 それ以外の場合、削除アクセスを要求した場合、他のプロセスはファイルまたはデバイスを開くことができません。 このフラグが指定されていないが、ファイルまたはデバイスが削除アクセス用に開かれている場合、関数は失敗します。 メモ 削除アクセスでは、削除操作と名前変更操作の両方が許可されます。
FILE_SHARE_READ 0x00000001	ファイルまたはデバイスで後続のオープン操作を有効にして、読み取りアクセスを要求します。 それ以外の場合、他のプロセスは、読み取りアクセスを要求した場合、ファイルまたはデバイスを開くことができません。 このフラグが指定されていないが、ファイルまたはデバイスが読み取りアクセスのために開かれている場合、関数は失敗します。
FILE_SHARE_WRITE 0x00000002	ファイルまたはデバイスで後続のオープン操作を有効にして、書き込みアクセスを要求します。 それ以外の場合、他のプロセスは、書き込みアクセスを要求した場合、ファイルまたはデバイスを開くことができません。 このフラグが指定されていないが、ファイルまたはデバイスが書き込みアクセス用に開かれているか、書き込みアクセス権を持つファイル マッピングを持っている場合、関数は失敗します。

[in, optional] lpSecurityAttributes

2 つの独立した関連データ メンバーを含む SECURITY_ATTRIBUTES 構造体へのポインター。省略可能なセキュリティ記述子と、返されたハンドルを子プロセスによって継承できるかどうかを決定するブール値。

このパラメーターは、NULL でもかまいません。

このパラメーターが NULL の場合、 CreateFile によって返されるハンドルは、アプリケーションが作成できる子プロセスによって継承できず、返されるハンドルに関連付けられているファイルまたはデバイスは既定のセキュリティ記述子を取得します。

構造体の lpSecurityDescriptor メンバーは、ファイルまたはデバイスの SECURITY_DESCRIPTOR を指定します。 このメンバーが NULL の場合、返されるハンドルに関連付けられているファイルまたはデバイスには、既定のセキュリティ記述子が割り当てられます。

CreateFile は 、既存のファイルまたはデバイスを開くときに lpSecurityDescriptor メンバーを無視しますが、引き続き bInheritHandle メンバーを使用します。

構造体の bInheritHandle メンバーは、返されたハンドルを継承できるかどうかを指定します。

詳細については、「解説」を参照してください。

[in] dwCreationDisposition

存在するか存在しないファイルまたはデバイスに対して実行するアクション。

ファイル以外のデバイスの場合、通常、このパラメーターは OPEN_EXISTING に設定されます。

詳細については、「解説」を参照してください。

このパラメーターは、次のいずれかの値である必要があります。この値を組み合わせることはできません。

値	意味
CREATE_ALWAYS 2	常に新しいファイルを作成します。 指定したファイルが存在し、書き込み可能な場合、関数はファイルを切り捨て、関数は成功し、最後のエラー コードは ERROR_ALREADY_EXISTS (183) に設定されます。 指定したファイルが存在せず、有効なパスである場合は、新しいファイルが作成され、関数が成功し、最後のエラー コードが 0 に設定されます。 詳細については、このトピックの「解説」セクションを参照してください。
CREATE_NEW 1	まだ存在しない場合にのみ、新しいファイルを作成します。 指定したファイルが存在する場合、関数は失敗し、最後のエラー コードは ERROR_FILE_EXISTS (80) に設定されます。 指定したファイルが存在せず、書き込み可能な場所への有効なパスである場合は、新しいファイルが作成されます。
OPEN_ALWAYS 4	常にファイルを開きます。 指定したファイルが存在する場合、関数は成功し、最後のエラー コードは ERROR_ALREADY_EXISTS (183) に設定されます。 指定したファイルが存在せず、書き込み可能な場所への有効なパスである場合、関数はファイルを作成し、最後のエラー コードを 0 に設定します。
OPEN_EXISTING 3	ファイルまたはデバイスが存在する場合にのみ開きます。 指定したファイルまたはデバイスが存在しない場合、関数は失敗し、最後のエラー コードは ERROR_FILE_NOT_FOUND (2) に設定されます。 デバイスの詳細については、「解説」セクションを参照してください。
TRUNCATE_EXISTING 5	ファイルを開き、サイズが 0 バイトになるように切り捨てます(存在する場合のみ)。 指定したファイルが存在しない場合、関数は失敗し、最後のエラー コードは ERROR_FILE_NOT_FOUND (2) に設定されます。 呼び出し元のプロセスでは、dwDesiredAccess パラメーターの一部としてGENERIC_WRITE ビットが設定されたファイルを開く必要があります。

[in] dwFlagsAndAttributes

ファイルまたはデバイスの属性とフラグ FILE_ATTRIBUTE_NORMAL 、ファイルの最も一般的な既定値です。

このパラメーターには、使用可能なファイル属性 (FILE_ATTRIBUTE_*) の任意の組み合わせを含めることができます。 その他のすべてのファイル属性は、 FILE_ATTRIBUTE_NORMALをオーバーライドします。

このパラメーターには、ファイルまたはデバイスのキャッシュ動作、アクセス モード、およびその他の特殊な目的のフラグを制御するためのフラグ (FILE_FLAG_*) の組み合わせを含めることもできます。 これらは 、任意のFILE_ATTRIBUTE_* 値と組み合わされます。

このパラメーターには、 SECURITY_SQOS_PRESENT フラグを指定することで、サービス品質 (SQOS) 情報を含めることもできます。 その他の SQOS 関連のフラグ情報は、属性テーブルとフラグ テーブルの後の表に示されています。

メモCreateFile で既存のファイルが開かれると、通常、ファイル フラグと既存のファイルのファイル属性が結合され、dwFlagsAndAttributes の一部として指定されたファイル属性は無視されます。 特殊なケースについては、「 ファイルの作成と開き方」を参照してください。

 

次のファイル属性とフラグの一部は、ファイルにのみ適用される場合があり、 CreateFile で開くことができる他のすべての種類のデバイスとは限りません。 詳細については、このトピックの「解説」セクションおよび「 ファイルの作成と開く」を参照してください。

ファイル属性への高度なアクセスについては、「 SetFileAttributes」を参照してください。 値と説明を含むすべてのファイル属性の完全な一覧については、「 ファイル属性定数」を参照してください。

属性	説明
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	ファイルをアーカイブする必要があります。 アプリケーションでは、この属性を使用して、バックアップまたは削除の対象にファイルをマークします。
FILE_ATTRIBUTE_ENCRYPTED 16384 (0x4000)	ファイルまたはディレクトリは暗号化されています。 ファイルの場合は、ファイルのすべてのデータが暗号化されています。 ディレクトリの場合、新しく作成されたファイルとサブディレクトリの既定値は暗号化であることを意味します。 詳細については、「 ファイルの暗号化」を参照してください。 FILE_ATTRIBUTE_SYSTEMも指定されている場合、このフラグは無効です。 このフラグは、Windows の Home、Home Premium、Starter、または ARM エディションではサポートされていません。
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	ファイルが非表示になっています。 通常のディレクトリ一覧には含めないでください。
FILE_ATTRIBUTE_NORMAL 128 (0x80)	ファイルには他の属性が設定されていません。 この属性は、単独で使用された場合にのみ有効です。
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	ファイルのデータはすぐには使用できません。 この属性は、ファイル データが物理的にオフライン ストレージに移動されることを示します。 この属性は、階層型ストレージ管理ソフトウェアであるリモート ストレージによって使用されます。 アプリケーションはこの属性を任意に変更しないでください。
FILE_ATTRIBUTE_READONLY 1 (0x1)	ファイルは読み取り専用です。 アプリケーションはファイルを読み取ることができますが、書き込んだり削除したりすることはできません。
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	ファイルは、オペレーティング システムの一部であるか、オペレーティング システムによって排他的に使用されます。
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	ファイルは一時ストレージに使用されています。 詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。

 

フラグ	説明
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	バックアップまたは復元操作のためにファイルが開かれているか作成されています。 システムは、プロセスに SE_BACKUP_NAME と SE_RESTORE_NAME の特権がある場合に、呼び出し元のプロセスがファイル セキュリティ チェックをオーバーライドすることを保証します。 詳細については、「 トークンでの特権の変更」を参照してください。 ディレクトリへのハンドルを取得するには、このフラグを設定する必要があります。 ディレクトリ ハンドルは、ファイル ハンドルではなく一部の関数に渡すことができます。 詳細については、「解説」を参照してください。
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	そのハンドルがすべて閉じられた直後にファイルは削除されることになります。このハンドルには、指定されたハンドルと、他の開いているハンドルまたは重複した他のハンドルが含まれます。 ファイルに対して開いているハンドルが存在する場合、 FILE_SHARE_DELETE 共有モードですべて開かなければ、呼び出しは失敗します。 FILE_SHARE_DELETE 共有モードが指定されていない限り、ファイルに対する後続のオープン要求は失敗します。
FILE_FLAG_NO_BUFFERING 0x20000000	ファイルまたはデバイスは、データの読み取りと書き込みのシステム キャッシュなしで開かれています。 このフラグは、ハード ディスクキャッシュやメモリマップファイルには影響しません。 FILE_FLAG_NO_BUFFERING フラグを使用して CreateFile で開かれたファイルを正常に操作するには、厳密な要件があります。詳細については、「ファイル バッファリング」を参照してください。
FILE_FLAG_OPEN_NO_RECALL 0x00100000	ファイル データは要求されますが、引き続きリモート ストレージに配置する必要があります。 ローカル ストレージに転送しないでください。 このフラグは、リモート・ストレージ・システムで使用されます。
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	通常 の再解析ポイント 処理は行われません。 CreateFile は再解析ポイントを開こうとします。 ファイルを開くと、再解析ポイントを制御するフィルターが動作可能かどうかに関係なく、ファイル ハンドルが返されます。 このフラグは 、CREATE_ALWAYS フラグでは使用できません。 ファイルが再解析ポイントでない場合、このフラグは無視されます。 詳細については、「解説」を参照してください。
FILE_FLAG_OVERLAPPED 0x40000000	ファイルまたはデバイスは、非同期 I/O 用に開かれているか作成されています。 このハンドルで後続の I/O 操作が完了すると、 OVERLAPPED 構造体で指定されたイベントがシグナル状態に設定されます。 このフラグを指定すると、読み取りと書き込みの同時操作にファイルを使用できます。 このフラグが指定されていない場合、読み取りおよび書き込み関数の呼び出しで OVERLAPPED 構造体が指定されている場合でも、I/O 操作はシリアル化されます。 このフラグで作成されたファイル ハンドルを使用する場合の考慮事項については、このトピックの 「同期および非同期 I/O ハンドル」 セクションを参照してください。
FILE_FLAG_POSIX_SEMANTICS 0x01000000	アクセスは POSIX ルールに従って行われます。 これには、その名前付けをサポートするファイル システムに対して、名前が異なる複数のファイルを許可することが含まれます。 MS-DOS または 16 ビット Windows 用に作成されたアプリケーションでは、このフラグで作成されたファイルにアクセスできない可能性があるため、このオプションを使用する場合は注意が必要です。
FILE_FLAG_RANDOM_ACCESS 0x10000000	アクセスはランダムであることを意図しています。 システムはこれをヒントとしてファイルのキャッシュを最適化します。 ファイル・システムがキャッシュ入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。 詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。
FILE_FLAG_SESSION_AWARE 0x00800000	ファイルまたはデバイスがセッション認識で開かれています。 このフラグが指定されていない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。 このフラグは、セッション 0 にない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。 Windows Server 2008 R2 と Windows Server 2008: このフラグは、Windows Server 2012する前にはサポートされていません。
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	Access は、最初から最後まで順番に行われるよう意図されています。 システムはこれをヒントとしてファイルのキャッシュを最適化します。 このフラグは、読み取り分離 (つまり逆引きスキャン) を使用する場合は使用しないでください。 ファイル・システムがキャッシュされた入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。 詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。
FILE_FLAG_WRITE_THROUGH 0x80000000	書き込み操作は中間キャッシュを通過せず、ディスクに直接移動します。 詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。

 

dwFlagsAndAttributes パラメーターでは、SQOS 情報を指定することもできます。 詳細については、「 偽装レベル」を参照してください。 呼び出し元のアプリケーションが dwFlagsAndAttributes の一部としてSECURITY_SQOS_PRESENT フラグを指定する場合は、次の値の 1 つ以上を含めることもできます。

セキュリティ フラグ	意味
SECURITY_ANONYMOUS	匿名偽装レベルでクライアントを偽装します。
SECURITY_CONTEXT_TRACKING	セキュリティ追跡モードは動的です。 このフラグが指定されていない場合、セキュリティ追跡モードは静的です。
SECURITY_DELEGATION	委任の偽装レベルでクライアントを偽装します。
SECURITY_EFFECTIVE_ONLY	サーバーで使用できるのは、クライアントのセキュリティ コンテキストの有効な側面のみです。 このフラグを指定しない場合は、クライアントのセキュリティ コンテキストのすべての側面を使用できます。 これにより、クライアントは、クライアントの偽装中にサーバーが使用できるグループと特権を制限できます。
SECURITY_IDENTIFICATION	Id 偽装レベルでクライアントを偽装します。
SECURITY_IMPERSONATION	偽装レベルでクライアントを偽装する。 これは、 SECURITY_SQOS_PRESENT フラグと共に他のフラグが指定されていない場合の既定の動作です。

[in, optional] hTemplateFile

GENERIC_READアクセス権を持つテンプレート ファイルへの有効なハンドル。 テンプレート ファイルは、作成するファイルにファイル属性と拡張属性を提供します。

このパラメーターは、NULL でもかまいません。

既存のファイルを開くと、 CreateFile はこのパラメーターを無視します。

新しい暗号化されたファイルを開くと、ファイルは親ディレクトリから随意アクセス制御リストを継承します。 詳細については、「 ファイルの暗号化」を参照してください。

戻り値

関数が成功した場合、戻り値は、指定されたファイル、デバイス、名前付きパイプ、またはメール スロットへの開いているハンドルです。

失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

CreateFile は、最初はファイル操作専用に開発されましたが、それ以降は拡張され、他のほとんどの種類の I/O デバイスと Windows 開発者が使用できるメカニズムが含まれるよう拡張されています。 このセクションでは、開発者がさまざまなコンテキストで CreateFile を使用し、I/O の種類が異なる場合に発生する可能性があるさまざまな問題について説明します。 テキストは、ファイル システム上の実際の ファイル に格納されているデータを特に参照している場合にのみ、word ファイルの使用を試みます。 ただし、ファイルの一部の使用は、 ファイル のようなメカニズムをサポートする I/O オブジェクトをより一般的に参照している可能性があります。 この用語 ファイル のリベラルな使用は、前述の歴史的な理由から、定数名とパラメーター名で特に一般的です。

CreateFile によって返されるオブジェクト ハンドルを使用してアプリケーションが終了したら、CloseHandle 関数を使用してハンドルを閉じます。 これにより、システム リソースが解放されるだけでなく、ファイルやデバイスの共有やディスクへのデータのコミットなどに大きな影響を与える可能性があります。 詳細については、必要に応じてこのトピック内で説明します。

Windows Server 2003 および Windows XP: 共有違反は、 dwDesiredAccess パラメーターの値が DELETE アクセス フラグ (0x00010000) OR'ed で他のアクセス フラグが設定されていて、リモート ファイルまたはディレクトリが FILE_SHARE_DELETE で開かれていない場合に、リモート コンピューターでファイルまたはディレクトリを開こうとした場合に発生します。 このシナリオで共有違反を回避するには、 DELETE アクセス権のみを持つリモート ファイルまたはディレクトリを開くか、削除のために最初にファイルまたはディレクトリを開かずに DeleteFile を呼び出します。

NTFS ファイル システムなどの一部のファイル システムでは、個々のファイルとディレクトリの圧縮または暗号化がサポートされています。 このサポートを使用してマウントされたファイル システムがあるボリュームでは、新しいファイルは、そのディレクトリの圧縮属性と暗号化属性を継承します。

CreateFile を使用して、ファイルまたはディレクトリの圧縮、圧縮解除、または復号化を制御することはできません。 詳細については、「 ファイルの作成と開き方」、「 ファイルの圧縮と圧縮解除」、「 ファイル暗号化」を参照してください。

Windows Server 2003 および Windows XP: 下位互換性のため、lpSecurityAttributes でセキュリティ記述子を指定した場合、CreateFile は継承規則を適用しません。 継承をサポートするために、後でこのファイルのセキュリティ記述子に対してクエリを実行する関数は、継承が有効であることをヒューリスティックに判断して報告する場合があります。 詳細については、「 継承可能 ACE の自動伝達」を参照してください。

前述のように、 lpSecurityAttributes パラメーターが NULL の場合、 CreateFile によって返されるハンドルは、アプリケーションで作成できる子プロセスによって継承できません。 このパラメーターに関する次の情報も適用されます。

• bInheritHandle メンバー変数が FALSE (0 以外の値) でない場合は、ハンドルを継承できます。 したがって、ハンドルを継承可能にする予定がない場合は、この構造体メンバーを FALSE に適切に初期化することが重要です。
• ファイルまたはディレクトリの既定のセキュリティ記述子のアクセス制御リスト (ACL) は、親ディレクトリから継承されます。
• ターゲット ファイル システムは、 lpSecurityDescriptor メンバーがそれらに影響を及ぼすため、ファイルとディレクトリのセキュリティをサポートする必要があります。これは、 GetVolumeInformation を使用して決定できます。

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

テクノロジ	サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル	はい
SMB 3.0 Transparent Failover (TFO)	備考を参照してください
スケールアウト ファイル共有 (SO) を使う SMB 3.0	備考を参照してください
クラスターの共有ボリューム ファイル システム (CsvFS)	はい
Resilient File System (ReFS)	はい

 

既に開いている代替データ ストリームがあるファイルに対して実行した場合、置き換え処理を含む CreateFile は失敗します。

シンボリック リンクの動作

この関数の呼び出しによってファイルが作成された場合、動作に変更はありません。 また、 FILE_FLAG_OPEN_REPARSE_POINTに関する次の情報も考慮してください。

• FILE_FLAG_OPEN_REPARSE_POINTが指定されている場合:
  • 既存のファイルが開かれ、それがシンボリック リンクである場合、返されるハンドルはシンボリック リンクへのハンドルです。
  • TRUNCATE_EXISTINGまたはFILE_FLAG_DELETE_ON_CLOSEが指定されている場合、影響を受けるファイルはシンボリック リンクです。
• FILE_FLAG_OPEN_REPARSE_POINTが指定されていない場合:
  • 既存のファイルが開かれ、それがシンボリック リンクである場合、返されるハンドルはターゲットへのハンドルです。
  • CREATE_ALWAYS、TRUNCATE_EXISTING、または FILE_FLAG_DELETE_ON_CLOSE が指定されている場合、影響を受けるファイルはターゲットです。

キャッシュの動作

dwFlagsAndAttributes パラメーターに指定できる値の一部は、CreateFile によって使用され、ハンドルに関連付けられているデータがシステムによってキャッシュされる方法を制御または影響します。 これらは次のとおりです。

• FILE_FLAG_NO_BUFFERING
• FILE_FLAG_RANDOM_ACCESS
• FILE_FLAG_SEQUENTIAL_SCAN
• FILE_FLAG_WRITE_THROUGH
• FILE_ATTRIBUTE_TEMPORARY

これらのフラグが指定されていない場合、システムは既定の汎用キャッシュ スキームを使用します。 それ以外の場合、システム キャッシュはフラグごとに指定されたとおりに動作します。

これらのフラグの一部を組み合わせてはいけません。 たとえば、 FILE_FLAG_RANDOM_ACCESS と FILE_FLAG_SEQUENTIAL_SCAN を組み合わせることは自負です。

FILE_FLAG_SEQUENTIAL_SCAN フラグを指定すると、シーケンシャル アクセスを使用して大きなファイルを読み取るアプリケーションのパフォーマンスが向上する可能性があります。 大きなファイルを主に順番に読み取るアプリケーションでは、パフォーマンスの向上がさらに顕著になる可能性がありますが、場合によっては、小さなバイト範囲をスキップします。 アプリケーションがランダム アクセスのためにファイル ポインターを移動した場合、最適なキャッシュ パフォーマンスは発生しない可能性が高くなります。 ただし、正しい操作は引き続き保証されます。

フラグ FILE_FLAG_WRITE_THROUGH と FILE_FLAG_NO_BUFFERING は独立しており、組み合わせることができます。

FILE_FLAG_WRITE_THROUGHを使用してもFILE_FLAG_NO_BUFFERINGも指定されていないため、システム キャッシュが有効になっている場合、データはシステム キャッシュに書き込まれますが、ディスクに遅延なくフラッシュされます。

システム キャッシュが有効でないように、FILE_FLAG_WRITE_THROUGHとFILE_FLAG_NO_BUFFERINGの両方が指定されている場合、データは Windows システム キャッシュを経由せずにすぐにディスクにフラッシュされます。 また、オペレーティング システムは、ハード ディスクのローカル ハードウェア キャッシュの書き込みスルーを永続メディアに要求します。

メモ すべてのハード ディスク ハードウェアがこの書き込みスルー機能をサポートしているわけではありません。

 

FILE_FLAG_NO_BUFFERING フラグを適切に使用するには、アプリケーションに関する特別な考慮事項が必要です。 詳細については、「 ファイル バッファリング」を参照してください。

また、FILE_FLAG_WRITE_THROUGHを介した書き込み要求により、NTFS は、要求の処理に起因するメタデータの変更 (タイム スタンプの更新や名前変更操作など) をフラッシュします。 このため、FILE_FLAG_WRITE_THROUGH フラグは、各書き込み後に FlushFileBuffers 関数を呼び出すための代わりに、FILE_FLAG_NO_BUFFERING フラグと共に使用されることが多いため、不要なパフォーマンスが低下する可能性があります。 これらのフラグを一緒に使用すると、これらのペナルティを回避できます。 ファイルとメタデータのキャッシュに関する一般的な情報については、「 ファイル キャッシュ」を参照してください。

FILE_FLAG_NO_BUFFERINGをFILE_FLAG_OVERLAPPED と組み合わせると、I/O はメモリ マネージャーの同期操作に依存しないため、フラグによって最大の非同期パフォーマンスが得られます。 ただし、データがキャッシュに保持されていないため、一部の I/O 操作には時間がかかります。 また、ファイル メタデータはキャッシュされたままになることがあります (たとえば、空のファイルを作成する場合)。 メタデータがディスクにフラッシュされるようにするには、 FlushFileBuffers 関数を使用します。

FILE_ATTRIBUTE_TEMPORARY属性を指定すると、ハンドルが閉じられた後にアプリケーションによって一時ファイルが削除されるため、十分なキャッシュ メモリが使用可能な場合、ファイル システムは大容量ストレージへのデータの書き戻しを回避します。 その場合、システムはデータの書き込みを完全に回避できます。 前述のフラグと同じ方法でデータ キャッシュを直接制御することはありませんが、 FILE_ATTRIBUTE_TEMPORARY 属性は、書き込みを行わずにシステム キャッシュにできるだけ多くを保持するようにシステムに指示するため、特定のアプリケーションにとって問題になる可能性があります。

ファイル

ファイルの名前を変更または削除した後すぐに復元すると、システムはキャッシュで復元するファイル情報を検索します。 キャッシュされた情報には、短い名前と長い名前のペアと作成時間が含まれます。

DeleteFile の前回の呼び出しの結果として削除が保留中のファイルに対して CreateFile を呼び出すと、関数は失敗します。 オペレーティング システムは、ファイルに対するすべてのハンドルが閉じられるまでファイルの削除を遅延します。 GetLastError はERROR_ACCESS_DENIEDを返します。

dwDesiredAccess パラメーターは 0 にすることができ、アプリケーションが適切なセキュリティ設定で実行されている場合、アプリケーションはファイルにアクセスせずにファイル属性のクエリを実行できます。 これは、読み取りアクセスや書き込みアクセスのためにファイルを開かずにファイルの存在をテストしたり、ファイルまたはディレクトリに関するその他の統計情報を取得したりするのに役立ちます。 「ファイル情報の取得と設定」および「GetFileInformationByHandle」を参照してください。

CREATE_ALWAYSとFILE_ATTRIBUTE_NORMALが指定されている場合、CreateFile は失敗し、ファイルが存在し、FILE_ATTRIBUTE_HIDDEN属性または FILE_ATTRIBUTE_SYSTEM 属性がある場合は、最後のエラーをERROR_ACCESS_DENIEDに設定します。 このエラーを回避するには、既存のファイルと同じ属性を指定します。

アプリケーションがネットワーク経由でファイルを作成する場合は、GENERIC_WRITEのみを使用 GENERIC_READ | GENERIC_WRITE するよりも dwDesiredAccess に使用することをお 勧 めします。 リダイレクターはキャッシュ マネージャーを使用し、より多くのデータを含むより少ない SMB を送信できるため、結果のコードは高速になります。 この組み合わせにより、ネットワーク経由でファイルに書き込む際にERROR_ACCESS_DENIEDが返される場合がある問題も回避 できます。

詳細については、「ファイルの作成とオープン」を参照してください。

同期および非同期 I/O ハンドル

CreateFile では、同期または非同期のファイルまたはデバイス ハンドルを作成できます。 同期ハンドルは、そのハンドルを使用した I/O 関数呼び出しが完了するまでブロックされるように動作しますが、非同期ファイル ハンドルを使用すると、システムが I/O 操作を完了したかどうかにかかわらず、I/O 関数呼び出しからすぐに戻すことができます。 前述のように、この同期動作と非同期動作は、dwFlagsAndAttributes パラメーター内でFILE_FLAG_OVERLAPPEDを指定することによって決定されます。 非同期 I/O を使用する場合、いくつかの複雑さと潜在的な落とし穴があります。詳細については、「 同期 I/O と非同期 I/O」を参照してください。

ファイル ストリーム

NTFS ファイル システムでは、 CreateFile を 使用して、ファイル内に個別のストリームを作成できます。 詳細については、「 ファイル ストリーム」を参照してください。

ディレクトリ

アプリケーションでは CreateFile を使用してディレクトリを作成できないため、このユース ケースでは dwCreationDisposition に対して有効なOPEN_EXISTING値のみです。 ディレクトリを作成するには、アプリケーションで CreateDirectory または CreateDirectoryEx を呼び出す必要があります。

CreateFile を使用してディレクトリを開くには、dwFlagsAndAttributes の一部として FILE_FLAG_BACKUP_SEMANTICS フラグを指定します。 このフラグが SE_BACKUP_NAME および SE_RESTORE_NAME 特権なしで使用されている場合は、適切なセキュリティ チェックが引き続き適用されます。

FAT または FAT32 ファイル システム ボリュームの最適化中に CreateFile を 使用してディレクトリを開く場合は、 MAXIMUM_ALLOWED アクセス権を指定しないでください。 これが行われた場合、ディレクトリへのアクセスは拒否されます。 代わりに 、GENERIC_READ アクセス権を指定します。

詳細については、「 ディレクトリ管理について」を参照してください。

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

ディスクまたはボリュームへの直接アクセスは制限されています。

Windows Server 2003 および Windows XP: この方法では、ディスクまたはボリュームへの直接アクセスは制限されません。

CreateFile 関数を使用すると、物理ディスク ドライブまたはボリュームを開くことができます。このボリュームは、DeviceIoControl 関数で使用できる直接アクセス 記憶装置 (DASD) ハンドルを返します。 これにより、パーティション テーブルなどのディスク メタデータなど、ディスクまたはボリュームに直接アクセスできます。 ただし、この種類のアクセスでは、ディスク ドライブまたはボリュームのデータ損失の可能性も公開されます。これは、このメカニズムを使用したディスクへの書き込みが正しくないと、その内容がオペレーティング システムからアクセスできなくなる可能性があるためです。 データの整合性を確保するには、 DeviceIoControl と、ファイル システム ハンドルではなく、直接アクセス ハンドルを使用して他の API の動作が異なる方法を理解していることを確認してください。

このような呼び出しを成功させるには、次の要件を満たす必要があります。

• 呼び出し元には管理特権が必要です。 詳細については、「特別な特権を使用して実行する」を参照してください。
• dwCreationDisposition パラメーターには、OPEN_EXISTING フラグが必要です。
• ボリュームまたはフロッピー ディスクを開く場合は、 dwShareMode パラメーターに FILE_SHARE_WRITE フラグが必要です。

メモdwDesiredAccess パラメーターは 0 にすることができ、アプリケーションはデバイスにアクセスせずにデバイス属性のクエリを実行できます。 これは、たとえば、フロッピー ディスク ドライブのサイズと、それがサポートする形式を、ドライブにフロッピー ディスクを必要とせずに判断するアプリケーションに役立ちます。 また、より高いレベルのデータの読み取り/書き込みアクセス許可を必要とせずに統計を読み取る場合にも使用できます。

 

物理ドライブ x: を開くとき、 lpFileName 文字列は "\\.\PhysicalDriveX" という形式にする必要があります。 ハード ディスク番号は 0 から始まります。 次の表に、物理ドライブ文字列の例をいくつか示します。

String	説明
"\\.\PhysicalDrive0"	最初の物理ドライブを開きます。
"\\.\PhysicalDrive2"	3 番目の物理ドライブを開きます。

 

ボリュームの物理ドライブ識別子を取得するには、ボリュームのハンドルを開き、IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTSを使用して DeviceIoControl 関数を呼び出します。 この制御コードは、ボリュームの 1 つ以上のエクステントごとにディスク番号とオフセットを返します。ボリュームは複数の物理ディスクにまたがることができます。

物理ドライブを開く例については、「 DeviceIoControl の呼び出し」を参照してください。

ボリュームまたはリムーバブル メディア ドライブ (フロッピー ディスク ドライブやフラッシュ メモリサム ドライブなど) を開く場合、 lpFileName 文字列は "\.\X:" の形式にする必要があります。 ドライブのルート ディレクトリを示す末尾の円記号 (\) は使用しないでください。 次の表に、ドライブ文字列の例をいくつか示します。

String	説明
"\\.\A:"	フロッピー ディスク ドライブ A を開きます。
"\\.\C:"	C: ボリュームを開きます。
"\\.\C:\"	C: ボリュームのファイル システムを開きます。

 

ボリューム名を参照してボリュームを開くこともできます。 詳細については、「 ボリュームの名前付け」を参照してください。

ボリュームには、1 つ以上のマウントされたファイル システムが含まれています。 ボリューム ハンドルは、 CreateFile で noncached オプションが指定されていない場合でも、特定のファイル システムの裁量で非キャッシュとして開くことができます。 すべての Microsoft ファイル システムがボリューム ハンドルを非キャッシュとして開くと想定する必要があります。 ファイルのキャッシュされていない I/O に対する制限もボリュームに適用されます。

データがキャッシュされていない場合でも、ファイル システムでバッファーの配置が必要になる場合と必要ない場合があります。 ただし、ボリュームを開くときに noncached オプションを指定すると、ボリューム上のファイル システムに関係なくバッファーアラインメントが適用されます。 ボリューム ハンドルを非キャッシュとして開き、キャッシュされていない I/O 制限に従うすべてのファイル システムで推奨されます。

メモ ボリュームの最後のいくつかのセクターに対する読み取りまたは書き込みを行うには、 DeviceIoControl を呼び出し、 FSCTL_ALLOW_EXTENDED_DASD_IOを指定する必要があります。 これにより、パーティションの読み取りまたは書き込みの呼び出しで I/O 境界チェックを実行しないようにファイル システム ドライバーに通知されます。 代わりに、境界チェックはデバイス ドライバーによって実行されます。

 

Changer デバイス

DeviceIoControl のIOCTL_CHANGER_* コントロール コードは、changer デバイスへのハンドルを受け入れます。 changer デバイスを開くには、"\\.\Changerx" という形式のファイル名を使用します。 ここで x は、開くデバイスを示す数値で、0 から始まります。 C または C++ で記述されたアプリケーションで changer デバイス 0 を開くには、"\\.\Changer0" というファイル名を使用します。

テープ ドライブ

テープ ドライブを開くには、"\\.\TAPEx" という形式のファイル名を使用します。 ここで、x は開くドライブを示す番号で、テープ ドライブは 0 から始まります。 C または C++ で記述されたアプリケーションでテープ ドライブ 0 を開くには、"\\.\TAPE0" というファイル名を使用します。

詳細については、「 バックアップ」を参照してください。

通信リソース

CreateFile 関数は、シリアル ポート COM1 などの通信リソースへのハンドルを作成できます。 通信リソースの場合、 dwCreationDisposition パラメーターは OPEN_EXISTINGする必要があります。 dwShareMode パラメーターは 0 (排他アクセス)、 hTemplateFile パラメーターは NULL である必要があります。 読み取り、書き込み、または読み取り/書き込みアクセスを指定でき、重複する I/O に対してハンドルを開くことができます。

9 より大きい COM ポート番号を指定するには、"\\.\COM10" という構文を使用します。 この構文は、COM ポート番号を指定できるすべてのポート番号とハードウェアに対して機能します。

通信の詳細については、「 通信」を参照してください。

コンソール

CreateFile 関数は、コンソール入力 (CONIN$) へのハンドルを作成できます。 継承または重複の結果としてプロセスに開いているハンドルがある場合は、アクティブな画面バッファー (CONOUT$) へのハンドルを作成することもできます。 呼び出し元のプロセスは、継承されたコンソールにアタッチするか、 AllocConsole 関数によって割り当てられている必要があります。 コンソール ハンドルの場合は、 CreateFile パラメーターを次のように設定します。

パラメーター	値
lpFileName	コンソール入力を指定するには、CONIN$ 値を使用します。 コンソール出力を指定するには、CONOUT$ 値を使用します。 CONIN$ は、 SetStdHandle 関数が標準入力ハンドルをリダイレクトした場合でも、コンソール入力バッファーへのハンドルを取得します。 標準入力ハンドルを取得するには、 GetStdHandle 関数を使用します。 CONOUT$ は、 SetStdHandle が標準出力ハンドルをリダイレクトした場合でも、アクティブな画面バッファーへのハンドルを取得します。 標準の出力ハンドルを取得するには、 GetStdHandle を使用します。
dwDesiredAccess	GENERIC_READ | GENERIC_WRITE が推奨されますが、どちらか一方がアクセスを制限できます。
dwShareMode	CONIN$ を開くときは、 FILE_SHARE_READを指定します。 CONOUT$ を開くときは、 FILE_SHARE_WRITEを指定します。 呼び出し元のプロセスがコンソールを継承する場合、または子プロセスがコンソールにアクセスできる必要がある場合、このパラメーターは である FILE_SHARE_READ | FILE_SHARE_WRITE必要があります。
lpSecurityAttributes	コンソールを継承する場合は、SECURITY_ATTRIBUTES構造体の bInheritHandle メンバーが TRUE である必要があります。
dwCreationDisposition	CreateFile を使用してコンソールを開く場合は、OPEN_EXISTINGを指定する必要があります。
dwFlagsAndAttributes	無視されます。
hTemplateFile	無視されます。

 

次の表は、 dwDesiredAccess と lpFileName のさまざまな設定を示しています。

lpFileName	dwDesiredAccess	結果
"CON"	GENERIC_READ	入力用のコンソールを開きます。
"CON"	GENERIC_WRITE	出力用のコンソールを開きます。
"CON"	GENERIC_READ | GENERIC_WRITE	CreateFile が失敗します。GetLastError はERROR_FILE_NOT_FOUNDを返します。

 

Mailslots

CreateFile が mailslot のクライアント側を開いた場合、mailslot サーバーが CreateMailSlot 関数を使用して作成する前に、mailslot クライアントがローカル mailslot を開こうとした場合、この関数はINVALID_HANDLE_VALUEを返します。

詳細については、「 Mailslots」を参照してください。

パイプ

CreateFile が名前付きパイプのクライアント側を開いた場合、関数はリッスン状態の名前付きパイプのインスタンスを使用します。 開始プロセスは、必要な回数だけハンドルを複製できますが、開いた後、名前付きパイプ インスタンスを別のクライアントで開くことはできません。 パイプを開いたときに指定されるアクセスは、CreateNamedPipe 関数の dwOpenMode パラメーターで指定されたアクセスと互換性がある必要があります。

この操作の前 に CreateNamedPipe 関数がサーバーで正常に呼び出されなかった場合、パイプは存在せず、 CreateFile は ERROR_FILE_NOT_FOUNDで失敗します。

アクティブなパイプ インスタンスが少なくとも 1 つあり、サーバー上に使用可能なリスナー パイプがない場合(つまり、すべてのパイプ インスタンスが現在接続されていることを意味します)、 CreateFile は ERROR_PIPE_BUSYで失敗します。

詳細については、「 パイプ」を参照してください。

例

ファイル操作の例を次のトピックに示します。

• 1 つのファイルを別のファイルに追加する
• 保留中の I/O 操作のキャンセル
• リダイレクトされた入出力を使用した子プロセスの作成
• 一時ファイルの作成と使用
• FSCTL_RECALL_FILE
• GetFinalPathNameByHandle
• ファイル内のバイト範囲のロックとロック解除
• ファイル ハンドルからファイル名を取得する
• ファイル システム認識情報の取得
• 読み取りまたは書き込みのためにファイルを開く
• Last-Write 時刻の取得
• SetFileInformationByHandle
• ファイルの末尾のテスト
• ファイバーの使用
• ストリームの使用
• 変更ジャーナル レコードのバッファーの探索
• Wow64DisableWow64FsRedirection
• Wow64EnableWow64FsRedirection

物理デバイス I/O については、次のトピックで説明します。

• DeviceIoControl の呼び出し
• 通信リソースの構成
• 通信イベントの監視
• デバイスを削除するための要求の処理

名前付きパイプを使用する例は、 名前付きパイプ クライアントにあります。

mailslot の操作については、「 Mailslot への書き込み」を参照してください。

テープ バックアップ コード スニペットは、 バックアップ アプリケーションの作成に関するページを参照してください。

注意

fileapi.h ヘッダーは、CreateFile をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

サポートされている最小のクライアント	Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー	Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム	Windows
ヘッダー	fileapi.h (Windows.h を含む)
Library	Kernel32.lib
[DLL]	Kernel32.dll

関連項目

ディレクトリ管理の概要

ボリューム管理について

Backup

CloseHandle

通信

CreateDirectory

CreateDirectoryEx

CreateFileTransacted

CreateMailSlot

CreateNamedPipe

ファイルの作成、削除、保守

DeleteFile

デバイスの入出力制御 (IOCTL)

DeviceIoControl

ファイルの圧縮と圧縮解除

ファイルの暗号化

ファイル管理の関数

ファイルのセキュリティとアクセス権

ファイル ストリーム

関数

GetLastError

I/O 完了ポート

I/O の概念

Mailslots

ファイル情報の取得と設定

概要トピック

パイプ

ReadFile

ReadFileEx

特別な特権を使用した実行

SetFileAttributes

WriteFile

WriteFileEx