CreateFileW 関数 (fileapi.h)

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

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

構文

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

パラメーター

[in] lpFileName

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

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

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

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

先端

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

[in] dwDesiredAccess

ファイルまたはデバイスへの要求されたアクセス。読み取り、書き込み、両方、またはゼロとして要約できます)。

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

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

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

詳細については、このトピックの「解説」セクションと ファイルの作成と開くを参照してください。

[in] dwShareMode

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

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

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

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

開いている各ハンドルの共有オプションは、プロセス コンテキストに関係なく、そのハンドルが閉じられるまで有効です。
価値 意味
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 Encryption」を参照してください。

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
アクセスはランダムであることを意図しています。 システムは、ファイル キャッシュを最適化するためのヒントとしてこれを使用できます。

このフラグは、ファイル システムがキャッシュされた I/O と 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
アクセスは、最初から最後まで順番に行われます。 システムは、ファイル キャッシュを最適化するためのヒントとしてこれを使用できます。

このフラグは、読み取りビハインド (逆引きスキャン) を使用する場合は使用しないでください。

このフラグは、ファイル システムがキャッシュされた I/O と 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 はこのパラメーターを無視します。

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

戻り値

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

関数が失敗した場合、戻り値は INVALID_HANDLE_VALUE。 拡張エラー情報を取得するには、GetLastError呼び出します。

備考

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

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

Windows Server 2003 および Windows XP: dwDesiredAccess パラメーターの値が DELETE アクセス フラグ (0x00010000) または他のアクセス フラグで '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 透過的フェールオーバー (TFO) 解説を参照する
SMB 3.0 とスケールアウト ファイル共有 (SO) 解説を参照する
クラスター共有ボリューム ファイル システム (CsvFS) はい
回復性のあるファイル システム (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_ALWAYSTRUNCATE_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_ACCESSFILE_FLAG_SEQUENTIAL_SCAN を組み合わせることは自負です。

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

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

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

システム キャッシュが有効でないように、FILE_FLAG_WRITE_THROUGHFILE_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_BUFFERINGFILE_FLAG_OVERLAPPEDと組み合わせると、I/O はメモリ マネージャーの同期操作に依存しないため、フラグによって最大の非同期パフォーマンスが得られます。 ただし、データがキャッシュに保持されていないため、一部の I/O 操作には時間がかかります。 また、ファイル メタデータはキャッシュされる場合もあります (空のファイルを作成する場合など)。 メタデータがディスクにフラッシュされるようにするには、FlushFileBuffers 関数を使用します。

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

ファイル

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

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

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

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

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

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

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

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

ファイル ストリーム

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

ディレクトリ

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

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

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

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

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

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

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

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

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

  • 呼び出し元には管理者特権が必要です。 詳細については、「特別な特権を使用した実行 」を参照してください。
  • dwCreationDisposition パラメーターには、OPEN_EXISTING フラグが必要です。
  • ボリュームまたはフロッピー ディスクを開く場合は、dwShareMode パラメーターに FILE_SHARE_WRITE フラグが必要です。
メモdwDesiredAccess パラメーターは 0 にすることができ、アプリケーションはデバイスにアクセスせずにデバイス属性のクエリを実行できます。 これは、たとえば、フロッピー ディスク ドライブのサイズと、ドライブにフロッピー ディスクを必要とせずにサポートする形式を決定するアプリケーションに役立ちます。 また、上位レベルのデータの読み取り/書き込みアクセス許可を必要とせずに統計を読み取る場合にも使用できます。
x
: 物理ドライブを開く場合、lpFileName 文字列は "\\.\PhysicalDriveX" という形式にする必要があります。 ハード ディスク番号は 0 から始まります。 次の表に、物理ドライブ文字列の例をいくつか示します。
意味
"\\.\PhysicalDrive0" 最初の物理ドライブを開きます。
"\\.\PhysicalDrive2" 3 番目の物理ドライブを開きます。

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

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

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

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

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

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

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

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

チェンジャー デバイス

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

テープ ドライブ

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

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

通信リソース

CreateFile 関数は、シリアル ポート COM1 などの通信リソースへのハンドルを作成できます。 通信リソースの場合、dwCreationDisposition パラメーターは OPEN_EXISTINGdwShareMode パラメーターはゼロ (排他アクセス) である必要があり、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 失敗します。GetLastErrorERROR_FILE_NOT_FOUNDを返します。

Mailslots

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

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

パイプ

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

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

アクティブなパイプ インスタンスが少なくとも 1 つ存在するが、サーバー上に使用可能なリスナー パイプがない場合、つまり、すべてのパイプ インスタンスが現在接続されていることを意味 、CreateFileERROR_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 バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルまたは実行時エラーが発生する不一致につながる可能性があります。 詳細については、「関数プロトタイプの 規則」を参照してください。

必要条件

要件 価値
サポートされる最小クライアント Windows XP [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2003 [デスクトップ アプリのみ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー fileapi.h (Windows.h を含む)
ライブラリ Kernel32.lib
DLL Kernel32.dll

関連項目

ディレクトリ管理 について

ボリューム管理 の

バックアップ

CloseHandle の

通信

CreateDirectory の

CreateDirectoryEx の

CreateFileTransacted の

CreateMailSlot の

CreateNamedPipe の

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

DeleteFile の

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

DeviceIoControl の

ファイルの圧縮と展開の

ファイル暗号化

ファイル管理機能の

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

ファイル ストリーム

Functions

GetLastError の

I/O 完了ポートの

I/O の概念

Mailslots

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

の概要に関するトピック

パイプ

ReadFile の

ReadFileEx の

特別な特権を使用して実行する

SetFileAttributes の

WriteFile の

WriteFileEx の