CreateFileA 関数 (fileapi.h)
ファイルまたは I/O デバイスを作成または開きます。 最も一般的に使用される I/O デバイスは、ファイル、ファイル ストリーム、ディレクトリ、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、通信リソース、mailslot、パイプです。 この関数は、ファイルまたはデバイス、および指定されたフラグと属性に応じて、さまざまな種類の 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
作成または開くファイルまたはデバイスの名前。 この名前にはスラッシュ (/) または円記号 (\) を使用できます。
この関数の ANSI バージョンでは、名前は MAX_PATH 文字に制限されています。 この制限を 32,767 文字まで拡張するには、Unicode バージョンの関数を呼び出し、パスに "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。
特殊なデバイス名については、「 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 パラメーターの有効な組み合わせの詳細については、「 ファイルの作成と開き方」を参照してください。
[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 用に作成されたアプリケーションでは、このフラグで作成されたファイルにアクセスできない可能性があるため、このオプションを使用する場合は注意が必要です。 |
|
アクセスはランダムであることを意図しています。 システムはこれをヒントとしてファイルのキャッシュを最適化します。
ファイル システムがキャッシュされた I/O および FILE_FLAG_NO_BUFFERINGをサポートしていない場合、このフラグは無効です。 詳細については、このトピックの 「キャッシュ動作」セクションを 参照してください。 |
|
ファイルまたはデバイスは、セッション認識を使用して開かれています。 このフラグを指定しない場合、セッション 0 で実行されているプロセスでは、セッションごとのデバイス (RemoteFX USB リダイレクトを使用するデバイスなど) を開くことができません。
このフラグは、セッション 0 に含まれていない呼び出し元には影響しません。 このフラグは、Windows のサーバー エディションでのみサポートされます。
Windows Server 2008 R2 および Windows Server 2008: このフラグは、Windows Server 2012する前にサポートされていません。 |
|
アクセスは、最初から最後まで順番に行われるよう意図されています。 システムはこれをヒントとしてファイルのキャッシュを最適化します。
読み取りビハインド (つまり、逆スキャン) を使用する場合は、このフラグを使用しないでください。 ファイル システムがキャッシュされた I/O および 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 の種類が異なる場合に開発者が発生する可能性があるさまざまな問題について説明します。 テキストは、ファイル システム上の実際の ファイル に格納されているデータを特に参照する場合にのみ、word ファイルの使用を試みます。 ただし、ファイルの一部の使用は、 ファイル のようなメカニズムをサポートする 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) | 解説を参照する |
| SMB 3.0 とスケールアウト ファイル共有 (SO) | 解説を参照する |
| クラスター共有ボリューム ファイル システム (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に設定します。 このエラーを回避するには、既存のファイルと同じ属性を指定します。
アプリケーションがネットワーク経由でファイルを作成する場合、GENERIC_WRITEのみを使用GENERIC_READ | GENERIC_WRITEするよりも dwDesiredAccess に使用することをお勧めします。 リダイレクターはキャッシュ マネージャーを使用でき、送信するデータの数が少なくなるため、結果のコードは高速になります。
この組み合わせにより、ネットワーク経由でファイルに書き込むときに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 関数で使用できるダイレクト アクセス ストレージ デバイス (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 でキャッシュされていないオプションが指定されていない場合でも、特定のファイル システムの裁量でキャッシュされていないものとして開くことができます。 すべての Microsoft ファイル システムがボリューム ハンドルをキャッシュされていないものとして開くと想定する必要があります。 ファイルのキャッシュされていない I/O に対する制限は、ボリュームにも適用されます。
ファイル システムでは、データがキャッシュされていない場合でも、バッファーの配置が必要な場合と必要ない場合があります。 ただし、ボリュームを開くときにキャッシュされていないオプションを指定すると、ボリューム上のファイル システムに関係なくバッファーの配置が適用されます。 ボリューム ハンドルを非キャッシュとして開き、キャッシュされていない I/O 制限に従うすべてのファイル システムで推奨されます。
Changer Device
DeviceIoControl のIOCTL_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
- ファイルの末尾のテスト
- ファイバーの使用
- Streamsの使用
- 変更履歴レコードのバッファーの移動
- 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 |
関連項目
関数
概要トピック