CreateFileW 関数 (fileapi.h)
ファイルまたは I/O デバイスを作成または開きます。 最も一般的に使用される I/O デバイスは、ファイル、ファイル ストリーム、ディレクトリ、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、通信リソース、メールスロット、パイプです。 関数は、ファイルまたはデバイス、および指定されたフラグと属性に応じて、さまざまな種類の 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_READ、 GENERIC_WRITE、またはその両方 (GENERIC_READ | GENERIC_WRITE
) です。 詳細については、「 汎用アクセス権」、「 ファイル セキュリティとアクセス権」、「 ファイル アクセス権定数」、 および「ACCESS_MASK」を参照してください。
このパラメーターが 0 の場合、アプリケーションは、アクセスが拒否された場合でも、そのファイルまたはデバイスにアクセスせずに、ファイル、ディレクトリ、デバイスの属性などの特定 のメタデータに対してクエリGENERIC_READ 実行できます。
既に開いているハンドルを持つオープン要求の dwShareMode パラメーターで指定された共有モードと競合するアクセス・モードを要求することはできません。
詳細については、このトピックの「解説」セクションと「 ファイルの作成と開く」を参照してください。
[in] dwShareMode
ファイルまたはデバイスの要求された共有モード。読み取り、書き込み、両方、削除、これらすべて、またはなしを指定できます (次の表を参照)。 属性または拡張属性へのアクセス要求は、このフラグの影響を受けません。
このパラメーターが 0 で CreateFile が成功した場合、ファイルまたはデバイスは共有できず、ファイルまたはデバイスへのハンドルが閉じられるまでもう一度開くことはできません。 詳細については、「解説」を参照してください。
開いているハンドルを持つ既存の要求で指定されているアクセス モードと競合する共有モードを要求することはできません。 CreateFile は失敗し、 GetLastError 関数は ERROR_SHARING_VIOLATIONを返します。
別のプロセスがファイルまたはデバイスを開いている間にプロセスでファイルまたはデバイスを共有できるようにするには、次の値の 1 つ以上の互換性のある組み合わせを使用します。 このパラメーターと dwDesiredAccess パラメーターの有効な組み合わせの詳細については、「 ファイルの作成と開き方」を参照してください。
[in, optional] lpSecurityAttributes
2 つの個別の関連データ メンバーを含む SECURITY_ATTRIBUTES 構造体へのポインター。省略可能なセキュリティ記述子と、返されたハンドルを子プロセスで継承できるかどうかを決定するブール値。
このパラメーターは、NULL でもかまいません。
このパラメーターが NULL の場合、 CreateFile によって返されるハンドルは、アプリケーションが作成できる子プロセスによって継承できず、返されたハンドルに関連付けられているファイルまたはデバイスは既定のセキュリティ記述子を取得します。
構造体の lpSecurityDescriptor メンバーは、ファイルまたはデバイスの SECURITY_DESCRIPTOR を指定します。 このメンバーが NULL の場合、返されたハンドルに関連付けられているファイルまたはデバイスには、既定のセキュリティ記述子が割り当てられます。
CreateFile は 、既存のファイルまたはデバイスを開くときに lpSecurityDescriptor メンバーを無視しますが、引き続き bInheritHandle メンバーを使用します。
構造体の bInheritHandle メンバーは、返されたハンドルを継承できるかどうかを指定します。
詳細については、「解説」を参照してください。
[in] dwCreationDisposition
存在するか存在しないファイルまたはデバイスに対して実行するアクション。
ファイル以外のデバイスの場合、通常、このパラメーターは OPEN_EXISTING に設定されます。
詳細については、「解説」を参照してください。
このパラメーターは、組み合わせることができない次のいずれかの値である必要があります。
[in] dwFlagsAndAttributes
ファイルまたはデバイスの属性とフラグ FILE_ATTRIBUTE_NORMAL 、ファイルの最も一般的な既定値です。
このパラメーターには、使用可能なファイル属性 (FILE_ATTRIBUTE_*) の任意の組み合わせを含めることができます。 その他のすべてのファイル属性は、 FILE_ATTRIBUTE_NORMALをオーバーライドします。
このパラメーターには、ファイルまたはデバイスのキャッシュ動作、アクセス モード、およびその他の特殊な目的のフラグを制御するためのフラグ (FILE_FLAG_) の組み合わせを含めることもできます。 これらは、任意 のFILE_ATTRIBUTE_ 値と組み合わされます。
このパラメーターには、 SECURITY_SQOS_PRESENT フラグを指定することで、サービス品質 (SQOS) 情報を含めることもできます。 その他の SQOS 関連のフラグ情報は、属性テーブルとフラグ テーブルの後の表に示されています。
ファイル属性への高度なアクセスについては、「 SetFileAttributes」を参照してください。 値と説明を含むすべてのファイル属性の完全な一覧については、「 ファイル属性定数」を参照してください。
属性 | 説明 |
---|---|
|
ファイルをアーカイブする必要があります。 アプリケーションでは、この属性を使用して、バックアップまたは削除の対象にファイルをマークします。 |
|
ファイルまたはディレクトリは暗号化されています。 ファイルの場合は、ファイルのすべてのデータが暗号化されています。 ディレクトリの場合、新しく作成されたファイルとサブディレクトリの既定値は暗号化であることを意味します。 詳細については、「 ファイルの暗号化」を参照してください。
FILE_ATTRIBUTE_SYSTEMも指定されている場合、このフラグは無効です。 このフラグは、Windows の Home、Home Premium、Starter、または ARM エディションではサポートされていません。 |
|
ファイルが非表示になっています。 通常のディレクトリ一覧には含めないでください。 |
|
ファイルには他の属性が設定されていません。 この属性は、単独で使用された場合にのみ有効です。 |
|
ファイルのデータはすぐには使用できません。 この属性は、ファイル データが物理的にオフライン ストレージに移動されることを示します。 この属性は、階層型ストレージ管理ソフトウェアであるリモート ストレージによって使用されます。 アプリケーションはこの属性を任意に変更しないでください。 |
|
ファイルは読み取り専用です。 アプリケーションはファイルを読み取ることができますが、書き込んだり削除したりすることはできません。 |
|
ファイルは、オペレーティング システムの一部であるか、オペレーティング システムによって排他的に使用されます。 |
|
ファイルは一時ストレージに使用されています。
詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。 |
フラグ | 説明 |
---|---|
|
バックアップまたは復元操作のためにファイルが開かれているか作成されています。 システムは、プロセスに SE_BACKUP_NAME と SE_RESTORE_NAME の特権がある場合に、呼び出し元のプロセスがファイル セキュリティ チェックをオーバーライドすることを保証します。 詳細については、「 トークンでの特権の変更」を参照してください。
ディレクトリへのハンドルを取得するには、このフラグを設定する必要があります。 ディレクトリ ハンドルは、ファイル ハンドルではなく一部の関数に渡すことができます。 詳細については、「解説」を参照してください。 |
|
そのハンドルがすべて閉じられた直後にファイルは削除されることになります。このハンドルには、指定されたハンドルと、他の開いているハンドルまたは重複した他のハンドルが含まれます。
ファイルに対して開いているハンドルが存在する場合、 FILE_SHARE_DELETE 共有モードですべて開かなければ、呼び出しは失敗します。 FILE_SHARE_DELETE 共有モードが指定されていない限り、ファイルに対する後続のオープン要求は失敗します。 |
|
ファイルまたはデバイスは、データの読み取りと書き込みのシステム キャッシュなしで開かれています。 このフラグは、ハード ディスクキャッシュやメモリマップファイルには影響しません。
FILE_FLAG_NO_BUFFERING フラグを使用して CreateFile で開かれたファイルを正常に操作するには、厳密な要件があります。詳細については、「ファイル バッファリング」を参照してください。 |
|
ファイル データは要求されますが、引き続きリモート ストレージに配置する必要があります。 ローカル ストレージに転送しないでください。 このフラグは、リモート・ストレージ・システムで使用されます。 |
|
通常 の再解析ポイント 処理は行われません。 CreateFile は再解析ポイントを開こうとします。 ファイルを開くと、再解析ポイントを制御するフィルターが動作可能かどうかに関係なく、ファイル ハンドルが返されます。
このフラグは 、CREATE_ALWAYS フラグでは使用できません。 ファイルが再解析ポイントでない場合、このフラグは無視されます。 詳細については、「解説」を参照してください。 |
|
ファイルまたはデバイスは、非同期 I/O 用に開かれているか作成されています。
このハンドルで後続の I/O 操作が完了すると、 OVERLAPPED 構造体で指定されたイベントがシグナル状態に設定されます。 このフラグを指定すると、読み取りと書き込みの同時操作にファイルを使用できます。 このフラグが指定されていない場合、読み取りおよび書き込み関数の呼び出しで OVERLAPPED 構造体が指定されている場合でも、I/O 操作はシリアル化されます。 このフラグで作成されたファイル ハンドルを使用する場合の考慮事項については、このトピックの 「同期および非同期 I/O ハンドル」 セクションを参照してください。 |
|
アクセスは POSIX ルールに従って行われます。 これには、その名前付けをサポートするファイル システムに対して、名前が異なる複数のファイルを許可することが含まれます。 MS-DOS または 16 ビット Windows 用に作成されたアプリケーションでは、このフラグで作成されたファイルにアクセスできない可能性があるため、このオプションを使用する場合は注意が必要です。 |
|
アクセスはランダムであることを意図しています。 システムはこれをヒントとしてファイルのキャッシュを最適化します。
ファイル・システムがキャッシュ入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。 詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。 |
|
ファイルまたはデバイスがセッション認識で開かれています。 このフラグを指定しない場合、セッション 0 で実行されているプロセスによってセッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。
このフラグは、セッション 0 に含まれていない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。
Windows Server 2008 R2 と Windows Server 2008: このフラグは、Windows Server 2012する前にサポートされていません。 |
|
アクセスは、最初から最後まで順番に行われるよう意図されています。 システムはこれをヒントとしてファイルのキャッシュを最適化します。
このフラグは、読み取りビハインド (つまり、逆スキャン) を使用する場合は使用しないでください。 ファイル・システムがキャッシュ入出力および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。 詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。 |
|
書き込み操作は中間キャッシュを通過せず、ディスクに直接移動します。
詳細については、このトピックの 「キャッシュ動作 」セクションを参照してください。 |
dwFlagsAndAttributes パラメーターでは、SQOS 情報を指定することもできます。 詳細については、「 偽装レベル」を参照してください。 呼び出し元のアプリケーションが dwFlagsAndAttributes の一部として SECURITY_SQOS_PRESENT フラグを指定する場合は、次の値の 1 つ以上を含めることもできます。
[in, optional] hTemplateFile
GENERIC_READアクセス権を持つテンプレート ファイルへの有効なハンドル。 テンプレート ファイルは、作成するファイルにファイル属性と拡張属性を提供します。
このパラメーターは、NULL でもかまいません。
既存のファイルを開くとき、 CreateFile はこのパラメーターを無視します。
新しい暗号化されたファイルを開くと、ファイルは親ディレクトリから随意アクセス制御リストを継承します。 詳細については、「 ファイルの暗号化」を参照してください。
戻り値
関数が成功した場合、戻り値は、指定されたファイル、デバイス、名前付きパイプ、またはメール スロットへのオープン ハンドルです。
失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
CreateFile は、最初はファイル操作専用に開発されましたが、その後、Windows 開発者が使用できる他のほとんどの種類の I/O デバイスとメカニズムを含むように拡張および拡張されています。 このセクションでは、 CreateFile をさまざまなコンテキストで使用し、I/O の種類が異なる場合に開発者が経験する可能性があるさまざまな問題について説明します。 テキストは、ファイル システム上の実際の ファイル に格納されているデータを特に参照している場合にのみ、ファイルという単語の使用を試みます。 ただし、ファイルの一部の使用は、 ファイル のようなメカニズムをサポートする I/O オブジェクトをより一般的に参照している可能性があります。 この用語 ファイル の自由な使用は、前述の履歴上の理由から、定数名とパラメーター名で特に一般的です。
CreateFile によって返されるオブジェクト ハンドルを使用してアプリケーションが終了したら、CloseHandle 関数を使用してハンドルを閉じます。 これにより、システム リソースが解放されるだけでなく、ファイルやデバイスの共有やディスクへのデータのコミットなどに大きな影響を与える可能性があります。 詳細については、必要に応じてこのトピック内で説明します。
Windows Server 2003 および Windows XP: 共有違反は、 dwDesiredAccess パラメーターの値が DELETE アクセス フラグ (0x00010000) OR が他のアクセス フラグと共に 指定され、リモート ファイルまたはディレクトリが 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 を使用して決定できます。
テクノロジ | サポートされています |
---|---|
サーバー メッセージ ブロック (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_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に設定します。 このエラーを回避するには、既存のファイルと同じ属性を指定します。
アプリケーションがネットワーク経由でファイルを作成する場合は、dwDesiredAccess に対して、GENERIC_READ | GENERIC_WRITE
GENERIC_WRITE単独で使用するよりも使用することをお勧めします。 リダイレクターでキャッシュ マネージャーを使用し、より多くのデータを含む S MB を送信できるため、結果として得られるコードの方が高速になります。
この組み合わせにより、ネットワーク経由でファイルへの書き込みが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 特権なしで使用される場合は、適切なセキュリティ チェックが引き続き適用されます。
FAT または FAT32 ファイル システム ボリュームの最適化中に CreateFile を 使用してディレクトリを開く場合は、 MAXIMUM_ALLOWED アクセス権を指定しないでください。 この操作を行うと、ディレクトリへのアクセスは拒否されます。 代わりに 、GENERIC_READ アクセス権を指定します。
詳細については、「 ディレクトリ管理について」を参照してください。
物理ディスクとボリューム
ディスクまたはボリュームへの直接アクセスが制限されています。Windows Server 2003 および Windows XP: ディスクまたはボリュームへの直接アクセスは、この方法では制限されません。
CreateFile 関数を使用すると、物理ディスク ドライブまたはボリュームを開くことができます。これにより、DeviceIoControl 関数で使用できる直接アクセス ストレージ デバイス (DASD) ハンドルが返されます。 これにより、パーティション テーブルなどのディスク メタデータなど、ディスクまたはボリュームに直接アクセスできます。 ただし、この種類のアクセスでは、ディスク ドライブまたはボリュームのデータ損失の可能性もあります。このメカニズムを使用したディスクへの書き込みが正しくないと、その内容がオペレーティング システムにアクセスできなくなる可能性があるためです。 データの整合性を確保するには、 DeviceIoControl と、ファイル システム ハンドルではなく、直接アクセス ハンドルで他の API の動作が異なる方法を理解していることを確認してください。
このような呼び出しを成功させるには、次の要件を満たす必要があります。
- 呼び出し元には管理特権が必要です。 詳細については、「特別な特権を使用して実行する」を参照してください。
- dwCreationDisposition パラメーターには、OPEN_EXISTING フラグが必要です。
- ボリュームまたはフロッピー ディスクを開くときは、 dwShareMode パラメーターに FILE_SHARE_WRITE フラグが必要です。
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 制限に従うすべてのファイル システムで推奨されます。
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を指定します。
呼び出し元のプロセスがコンソールを継承する場合、または子プロセスがコンソールにアクセスできる必要がある場合、このパラメーターは である |
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
mailslot の操作については、「 Mailslot への書き込み」を参照してください。
テープ バックアップ コード スニペットは、「 バックアップ アプリケーションの作成」で確認できます。
注意
fileapi.h ヘッダーは、CreateFile をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
要件 | 値 |
---|---|
サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
サポートされている最小のサーバー | Windows Server 2003 (デスクトップ アプリのみ) |
対象プラットフォーム | Windows |
ヘッダー | fileapi.h (Windows.h を含む) |
Library | Kernel32.lib |
[DLL] | Kernel32.dll |
関連項目
関数
概要トピック
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示