CreateFile2 関数 (fileapi.h)
ファイルまたは I/O デバイスを作成または開きます。 最も一般的に使用される I/O デバイスは、ファイル、ファイル ストリーム、ディレクトリ、物理ディスク、ボリューム、コンソール バッファー、テープ ドライブ、通信リソース、メールスロット、パイプです。 関数は、ファイルまたはデバイス、および指定されたフラグと属性に応じて、さまざまな種類の I/O のファイルまたはデバイスにアクセスするために使用できるハンドルを返します。
Windows ストア アプリから呼び出すと、 CreateFile2 が簡略化されます。 ApplicationData.LocalFolder ディレクトリまたは Package.InstalledLocation ディレクトリ内のファイルまたはディレクトリのみを開くことができます。 名前付きパイプやメールスロットを開いたり、暗号化されたファイルを作成したりすることはできません (FILE_ATTRIBUTE_ENCRYPTED)。
構文
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
パラメーター
[in] lpFileName
作成または開くファイルまたはデバイスの名前。
特殊なデバイス名については、「 MS-DOS デバイス名の定義」を参照してください。
ファイル ストリームを作成するには、ファイルの名前、コロン、ストリームの名前を指定します。 詳細については、「 ファイル ストリーム」を参照してください。
[in] dwDesiredAccess
ファイルまたはデバイスへの要求されたアクセス。読み取り、書き込み、両方、またはゼロとして要約できます)。
最も一般的に使用される値は、 GENERIC_READ、 GENERIC_WRITE、またはその両方 (GENERIC_READ | GENERIC_WRITE) です。 詳細については、「汎用アクセス権」、「ファイル セキュリティとアクセス権」、「ファイル アクセス権定数」、「ACCESS_MASK」を参照してください。
このパラメーターが 0 の場合、アプリケーションはファイル、ディレクトリ、デバイスの属性などの特定のメタデータに対してクエリを実行できますが、そのファイルやデバイスにアクセスしなくても、 GENERIC_READ アクセスは拒否されます。
既に開いているハンドルを持つオープン要求の dwShareMode パラメーターで指定された共有モードと競合するアクセス モードを要求することはできません。
詳細については、このトピックの「備考」および「 ファイルの作成と開く」を参照してください。
[in] dwShareMode
ファイルまたはデバイスの要求された共有モード。読み取り、書き込み、両方、削除、これらすべて、またはなし (次の表を参照)。 属性または拡張属性に対するアクセス要求は、このフラグの影響を受けません。
このパラメーターが 0 で CreateFile2 が成功した場合、ファイルまたはデバイスを共有できず、ファイルまたはデバイスへのハンドルが閉じられるまでもう一度開くことができません。 詳細については、「解説」を参照してください。
開いているハンドルを持つ既存の要求で指定されているアクセス モードと競合する共有モードを要求することはできません。 CreateFile2 は失敗し、 GetLastError 関数は ERROR_SHARING_VIOLATIONを返します。
別のプロセスがファイルまたはデバイスを開いている間にプロセスでファイルまたはデバイスを共有できるようにするには、次の値の 1 つ以上の互換性のある組み合わせを使用します。 このパラメーターと dwDesiredAccess パラメーターの有効な組み合わせの詳細については、「 Creating and Opening Files」を参照してください。
[in] dwCreationDisposition
存在するか存在しないファイルまたはデバイスに対して実行するアクション。
ファイル以外のデバイスの場合、通常、このパラメーターは OPEN_EXISTING に設定されます。
詳細については、「解説」を参照してください。
このパラメーターは、次のいずれかの値である必要があります。この値を組み合わせることはできません。
[in, optional] pCreateExParams
省略可能な CREATEFILE2_EXTENDED_PARAMETERS 構造体へのポインター。
戻り値
関数が成功した場合、戻り値は、指定されたファイル、デバイス、名前付きパイプ、またはメール スロットへの開いているハンドルです。
失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。 詳細なエラー情報を得るには、GetLastError を呼び出します。
解説
CreateFile2 関数を使用するアプリケーションをコンパイルするには、_WIN32_WINNT マクロを 0x0602 以降として定義します。 詳細については、「 Windows ヘッダーの使用」を参照してください。
CreateFile2 では、Windows 開発者が使用できるファイルの相互作用やその他のほとんどの種類の I/O デバイスとメカニズムがサポートされています。 このセクションでは、 CreateFile2 をさまざまなコンテキストで使用し、I/O の種類が異なる場合に開発者が経験する可能性があるさまざまな問題について説明します。 テキストは、ファイル システム上の実際の ファイル に格納されているデータを特に参照している場合にのみ、word ファイルの使用を試みます。 ただし、ファイルの一部の使用は、 ファイル のようなメカニズムをサポートする I/O オブジェクトをより一般的に参照している可能性があります。 この用語 ファイル のリベラルな使用は、前述の歴史的な理由から、定数名とパラメーター名で特に一般的です。
CreateFile2 によって返されるオブジェクト ハンドルを使用してアプリケーションが終了したら、CloseHandle 関数を使用してハンドルを閉じます。 これにより、システム リソースが解放されるだけでなく、ファイルやデバイスの共有やディスクへのデータのコミットなどに大きな影響を与える可能性があります。 詳細については、必要に応じてこのトピック内で説明します。
NTFS ファイル システムなどの一部のファイル システムでは、個々のファイルとディレクトリの圧縮または暗号化がサポートされています。 このサポートを使用してマウントされたファイル システムがあるボリュームでは、新しいファイルは、そのディレクトリの圧縮属性と暗号化属性を継承します。
CreateFile2 を使用して、ファイルまたはディレクトリの圧縮、圧縮解除、または復号化を制御することはできません。 詳細については、「 ファイルの作成と開き方」、「 ファイルの圧縮と圧縮解除」、「 ファイル暗号化」を参照してください。
pCreateExParams パラメーターで渡されるCREATEFILE2_EXTENDED_PARAMETERS構造体の lpSecurityAttributes メンバーが NULL の場合、CreateFile2 によって返されるハンドルは、アプリケーションで作成できる子プロセスによって継承できません。 このメンバーに関する次の情報も適用されます。
- 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) | はい |
シンボリック リンクの動作
この関数の呼び出しによってファイルが作成された場合、動作に変更はありません。 また、pCreateExParams パラメーターで渡されるCREATEFILE2_EXTENDED_PARAMETERS構造体の dwFileFlags メンバーの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 が指定されている場合、影響を受けるファイルはターゲットです。
ファイル
ファイルの名前を変更または削除してからすぐに復元すると、システムはキャッシュで復元するファイル情報を検索します。 キャッシュされた情報には、短い名前と長い名前のペアと作成時間が含まれます。DeleteFile の以前の呼び出しの結果として削除が保留中のファイルで CreateFile2 を呼び出すと、関数は失敗します。 オペレーティング システムは、ファイルに対するすべてのハンドルが閉じられるまで、ファイルの削除を遅延します。 GetLastError はERROR_ACCESS_DENIEDを返します。
dwDesiredAccess パラメーターは 0 にすることができ、アプリケーションが適切なセキュリティ設定で実行されている場合、アプリケーションはファイルにアクセスせずにファイル属性に対してクエリを実行できます。 これは、読み取りアクセスや書き込みアクセスのためにファイルを開かずにファイルの存在をテストしたり、ファイルまたはディレクトリに関するその他の統計情報を取得したりする場合に便利です。 「ファイル情報の取得と設定」および「GetFileInformationByHandle」を参照してください。
アプリケーションがネットワーク経由でファイルを作成する場合は、dwDesiredAccess に対して、GENERIC_READ | GENERIC_WRITEGENERIC_WRITE単独で使用するよりも使用することをお勧めします。 リダイレクターでキャッシュ マネージャーを使用し、より多くのデータを含む S MB を送信できるため、結果として得られるコードの方が高速になります。
この組み合わせにより、ネットワーク経由でファイルへの書き込みがERROR_ACCESS_DENIEDを返す場合がある問題も回避 できます。
詳細については、「ファイルの作成とオープン」を参照してください。
ファイル ストリーム
NTFS ファイル システムでは、 CreateFile2 を 使用して、ファイル内に個別のストリームを作成できます。 詳細については、「 ファイル ストリーム」を参照してください。ディレクトリ
アプリケーションは CreateFile2 を使用してディレクトリを作成できないため、このユース ケースでは dwCreationDisposition のOPEN_EXISTING値のみが有効です。 ディレクトリを作成するには、アプリケーションで CreateDirectory または CreateDirectoryEx を呼び出す必要があります。CreateFile2 を使用してディレクトリを開くには、pCreateExParams パラメーターで渡されるCREATEFILE2_EXTENDED_PARAMETERS構造体の dwFileFlags メンバーの一部として、FILE_FLAG_BACKUP_SEMANTICS フラグを指定します。 このフラグが SE_BACKUP_NAME および SE_RESTORE_NAME 特権なしで使用される場合は、適切なセキュリティ チェックが引き続き適用されます。
CREATEFile2 を使用して FAT または FAT32 ファイル システム ボリュームの最適化中にディレクトリを開く場合は、MAXIMUM_ALLOWEDアクセス権を指定しないでください。 この操作を行うと、ディレクトリへのアクセスは拒否されます。 代わりに 、GENERIC_READ アクセス権を指定します。
詳細については、「 ディレクトリ管理について」を参照してください。
物理ディスクとボリューム
ディスクまたはボリュームへの直接アクセスが制限されています。CreateFile2 関数を使用すると、物理ディスク ドライブまたはボリュームを開くことができます。これにより、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 つ以上のマウントされたファイル システムが含まれています。 ボリューム ハンドルは、 CreateFile2 で非キャッシュ オプションが指定されていない場合でも、特定のファイル システムの裁量でキャッシュされていないとして開くことができます。 すべての 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" というファイル名を使用します。詳細については、「 バックアップ」を参照してください。
通信リソース
CreateFile2 関数は、シリアル ポート COM1 などの通信リソースへのハンドルを作成できます。 通信リソースの場合、 dwCreationDisposition パラメーターは OPEN_EXISTINGする必要があります。 dwShareMode パラメーターは 0 (排他アクセス)、 hTemplateFile パラメーターは NULL である必要があります。 読み取り、書き込み、または読み取り/書き込みアクセスを指定でき、重複する I/O に対してハンドルを開くことができます。9 より大きい COM ポート番号を指定するには、"\.\COM10" という構文を使用します。 この構文は、COM ポート番号を指定できるすべてのポート番号とハードウェアに対して機能します。
通信の詳細については、「 通信」を参照してください。
コンソール
CreateFile2 関数は、コンソール入力 (CONIN$) へのハンドルを作成できます。 継承または重複の結果としてプロセスに開いているハンドルがある場合は、アクティブな画面バッファー (CONOUT$) へのハンドルを作成することもできます。 呼び出し元のプロセスは、継承されたコンソールにアタッチするか、 AllocConsole 関数によって割り当てられている必要があります。 コンソール ハンドルの場合は、 CreateFile2 パラメーターを次のように設定します。| パラメーター | 値 |
|---|---|
| lpFileName |
コンソール入力を指定するには、CONIN$ 値を使用します。
コンソール出力を指定するには、CONOUT$ 値を使用します。 CONIN$ は、 SetStdHandle 関数が標準入力ハンドルをリダイレクトした場合でも、コンソール入力バッファーへのハンドルを取得します。 標準入力ハンドルを取得するには、 GetStdHandle 関数を使用します。 CONOUT$ は、 SetStdHandle が標準出力ハンドルをリダイレクトした場合でも、アクティブな画面バッファーへのハンドルを取得します。 標準の出力ハンドルを取得するには、 GetStdHandle を使用します。 |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE が推奨されますが、どちらか一方がアクセスを制限できます。
|
| dwShareMode |
CONIN$ を開くときは、 FILE_SHARE_READを指定します。 CONOUT$ を開くときは、 FILE_SHARE_WRITEを指定します。
呼び出し元のプロセスがコンソールを継承する場合、または子プロセスがコンソールにアクセスできる必要がある場合、このパラメーターは である |
| dwCreationDisposition | CreateFile2 を使用してコンソールを開く場合は、OPEN_EXISTINGを指定する必要があります。 |
pCreateExParams パラメーターで渡されるCREATEFILE2_EXTENDED_PARAMETERS構造体のメンバーを次のように設定します。
| メンバー | [値] |
|---|---|
| lpSecurityAttributes | コンソールを継承する場合は、SECURITY_ATTRIBUTES構造体の bInheritHandle メンバーが TRUE である必要があります。 |
|
dwFileAttributes
dwFileFlags dwSecurityQosFlags hTemplateFile |
無視されます。 |
次の表は、 dwDesiredAccess と lpFileName のさまざまな設定を示しています。
| lpFileName | dwDesiredAccess | 結果 |
|---|---|---|
| "CON" | GENERIC_READ | 入力用のコンソールを開きます。 |
| "CON" | GENERIC_WRITE | 出力用のコンソールを開きます。 |
| "CON" | GENERIC_READ | GENERIC_WRITE |
CreateFile2 が失敗します。GetLastError はERROR_FILE_NOT_FOUNDを返します。 |
Mailslots
CreateFile2 が mailslot のクライアント側を開いた場合、mailslot サーバーが CreateMailSlot 関数を使用して作成する前に、mailslot クライアントがローカル mailslot を開こうとした場合、この関数はINVALID_HANDLE_VALUEを返します。詳細については、「 Mailslots」を参照してください。
パイプ
CreateFile2 が名前付きパイプのクライアント側を開いた場合、関数はリッスン状態の名前付きパイプのインスタンスを使用します。 開始プロセスは、必要な回数だけハンドルを複製できますが、開いた後、名前付きパイプ インスタンスを別のクライアントで開くことはできません。 パイプを開いたときに指定されるアクセスは、CreateNamedPipe 関数の dwOpenMode パラメーターで指定されたアクセスと互換性がある必要があります。この操作の前 に CreateNamedPipe 関数がサーバーで正常に呼び出されなかった場合、パイプは存在せず、 CreateFile2 は ERROR_FILE_NOT_FOUNDで失敗します。
アクティブなパイプ インスタンスが少なくとも 1 つ存在するが、サーバー上に使用可能なリスナー パイプがない場合は、すべてのパイプ インスタンスが現在接続されていることを意味し、 CreateFile2 は ERROR_PIPE_BUSYで失敗します。
詳細については、「 パイプ」を参照してください。
要件
| サポートされている最小のクライアント | Windows 8 [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2012 [デスクトップ アプリ |UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | fileapi.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |
関連項目
関数
概要トピック
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示