IoCreateFile 関数 (wdm.h)

  • [アーティクル]

IoCreateFile ルーチンは、新しいファイルまたはディレクトリを作成するか、既存のファイル、デバイス、ディレクトリ、またはボリュームを開き、呼び出し元にファイル オブジェクトのハンドルを提供します。

構文

NTSTATUS IoCreateFile(
  [out]          PHANDLE            FileHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in]           POBJECT_ATTRIBUTES ObjectAttributes,
  [out]          PIO_STATUS_BLOCK   IoStatusBlock,
  [in, optional] PLARGE_INTEGER     AllocationSize,
  [in]           ULONG              FileAttributes,
  [in]           ULONG              ShareAccess,
  [in]           ULONG              Disposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength,
  [in]           CREATE_FILE_TYPE   CreateFileType,
  [in, optional] PVOID              InternalParameters,
  [in]           ULONG              Options
);

パラメーター

[out] FileHandle

呼び出しが成功した場合にファイル ハンドルを受け取る変数へのポインター。 ハンドルが使用されなくなったら、ドライバーは ZwClose でハンドルを閉じる必要があります。

[in] DesiredAccess

呼び出し元が必要とするファイルまたはディレクトリへのアクセスの種類を指定するフラグのビットマスク。 このパラメーターの詳細とフラグ値の一覧については、IoCreateFileEx の DesiredAccess パラメーターを参照してください。

[in] ObjectAttributes

InitializeObjectAttributes で既に初期化されている不透明なOBJECT_ATTRIBUTES構造体へのポインター。 各構造体メンバーの詳細と説明については、IoCreateFileEx の ObjectAttributes パラメーターを参照してください。

[out] IoStatusBlock

最終的 な完了 状態と要求された操作に関する情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 IoCreateFileEx の IoStatusBlock パラメーターを参照してください。

[in, optional] AllocationSize

必要に応じて、ファイルの初期割り当てサイズをバイト単位で指定します。 ファイルが作成、上書き、または置き換えられる場合を除き、0 以外の値は有効になりません。

[in] FileAttributes

明示的に指定された属性は、ファイルが作成、置き換えられる、または場合によっては上書きされた場合にのみ適用されます。 既定では、この値はFILE_ATTRIBUTE_NORMALで、Wdm.h で定義されている 1 つ以上の FILE_ATTRIBUTE_XXX フラグの ORed の組み合わせによってオーバーライドできます。 IoCreateFile で使用できるフラグの一覧については、「CreateFile」を参照してください。

[in] ShareAccess

呼び出し元が必要とするファイルへの共有アクセスの種類を 0 または 1、またはフラグの組み合わせとして指定します。 詳細とフラグの一覧については、IoCreateFileEx の ShareAccess パラメーターを参照してください。

[in] Disposition

ファイルが既に存在するかどうかに応じて、実行するアクションを決定する値を指定します。 使用可能な値の一覧については、IoCreateFileEx の Disposition パラメーターを参照してください。

[in] CreateOptions

ファイルを作成または開くときに適用するオプションを指定します。 このパラメーターは、IoCreateFileEx の CreateOptions パラメーターに記載され、説明されているフラグの互換性のある組み合わせです。

[in, optional] EaBuffer

デバイス ドライバーと中間ドライバーの場合、このパラメーターは NULL ポインターである必要があります。

[in] EaLength

デバイス ドライバーと中間ドライバーの場合、このパラメーターは 0 である必要があります。

[in] CreateFileType

ドライバーは、このパラメーターを CreateFileTypeNone に設定する必要があります。

[in, optional] InternalParameters

ドライバーは、このパラメーターを NULL に設定する必要があります。

[in] Options

作成要求の作成時に使用するオプションを指定します。 使用可能な オプション の一覧については、 IoCreateFileEx の Options パラメーターを参照してください。

戻り値

IoCreateFile は 、STATUS_SUCCESSまたは適切なエラー状態を返します。 NTSTATUS 値。 可能なリターン コードの一覧については、「IoCreateFileEx」の「戻り値」セクションを参照してください。

注釈

IoCreateFileEx ルーチンは IoCreateFile ルーチンに似ていますが、追加の作成パラメーター (ECP)、デバイス オブジェクト、トランザクション情報へのアクセスなど、IoCreateFile ルーチンよりも優れた機能を提供します。

IoCreateFile によって取得されたハンドルは、後続の呼び出しで、ファイル内のデータ、またはファイル オブジェクトの状態または属性を操作するために使用できます。

IoCreateFile を使用して作成または開くファイルの名前を指定するには、次の 2 つの方法があります。

  1. 完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます

  2. 入力 ObjectAttributes の RootDirectory メンバーのハンドルによって表されるディレクトリ ファイルに対する相対パス名として

特定の DesiredAccess フラグとフラグの組み合わせには、次の効果があります。

  • 呼び出し元が、返された FileHandle を待機して I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。 それ以外の場合、デバイスまたは中間ドライバーである呼び出し元は、イベント オブジェクトを使用して I/O 完了を同期する必要があります。

  • FILE_APPEND_DATAフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元はファイルの末尾にのみ書き込むことができます。ファイルへの書き込みに関するオフセット情報は無視されます。 ただし、この種類の書き込み操作では、必要に応じてファイルが自動的に拡張されます。

  • ファイルのFILE_WRITE_DATA フラグを設定すると、ファイルの末尾を超える書き込みも行われます。 ファイルは、この種類の書き込みでも自動的に拡張されます。

  • FILE_EXECUTEフラグと SYNCHRONIZE フラグのみが設定されている場合、呼び出し元は、返された FileHandle を使用してファイル内のデータを直接読み取ったり書き込んだりすることはできません。つまり、命令とデータアクセスに応答して、ファイルに対するすべての操作がシステム ポケットベルを介して行われます。 デバイス ドライバーと中間ドライバーでは 、DesiredAccess で FILE_EXECUTE フラグを設定しないでください。

ShareAccess パラメーターは、個別のスレッドが同じファイルに同時にアクセスできるかどうかを決定します。 指定した方法でファイルにアクセスする権限を両方のファイル・オープン機能に持っている場合は、ファイルを正常に開いて共有できます。 IoCreateFile の元の呼び出し元がFILE_SHARE_READ、FILE_SHARE_WRITE、またはFILE_SHARE_DELETEを指定しない場合、ファイルに対して他の開いている操作を実行することはできません。つまり、元の呼び出し元にはファイルへの排他的アクセス権が付与されます。

共有ファイルを正常に開くには、ファイルに対して要求された DesiredAccess が、ZwClose でまだリリースされていない上記のすべてのオープンの DesiredAccess 仕様と ShareAccess 仕様の両方と互換性がある必要があります。 つまり、特定のファイルに対して IoCreateFile に指定された DesiredAccess は、ファイルの他の opener が許可していないアクセスと競合しないようにする必要があります。

Disposition 値FILE_SUPERSEDEには、呼び出し元が既存のファイル オブジェクトに対する DELETE アクセス権を持っている必要があります。 その場合、既存のファイルで FILE_SUPERSEDEを使用して IoCreateFile を正常に呼び出すと、そのファイルが実質的に削除され、再作成されます。 これは、ファイルが既に別のスレッドによって開かれている場合は、FILE_SHARE_DELETE フラグが設定された ShareAccessパラメーターを指定してファイルを開くことを意味します。 この種類の処理は、ファイルを上書きする POSIX スタイルと一致することに注意してください。

Disposition の値FILE_OVERWRITE_IFとFILE_SUPERSEDEは似ています。 IoCreateFile が既存のファイルで呼び出され、これらの Disposition 値のいずれかが呼び出された場合、ファイルは置き換えられます。

ファイルの上書きは、次を除き、置き換え操作と意味的に同等です。

  • 呼び出し元は、アクセス権を削除するのではなく、ファイルへの書き込みアクセス権を持っている必要があります。 これは、ファイルが既に別のスレッドによって開かれている場合は、入力 ShareAccess で設定されたFILE_SHARE_WRITE フラグを使用してファイルを開くことを意味します。

  • 指定されたファイル属性は、ファイルに既に存在する属性と論理的に ORed です。 これは、ファイルが既に別のスレッドによって開かれている場合、 IoCreateFile の後続の呼び出し元は既存の FileAttributes フラグを無効にすることはできませんが、同じファイルに対して追加のフラグを有効にできることを意味します。

CreateOptions FILE_DIRECTORY_FILE値は、作成または開くファイルがディレクトリ ファイルであることを指定します。 ディレクトリ ファイルが作成されると、ファイル システムはディスク上に適切な構造を作成し、その特定のファイル システムのディスク上の構造の空のディレクトリを表します。 このオプションが指定されていて、開く指定されたファイルがディレクトリ ファイルではない場合、または呼び出し元が一貫性のない CreateOptions または Disposition 値を指定した場合、 IoCreateFile の呼び出しは失敗します。

CreateOptions FILE_NO_INTERMEDIATE_BUFFERING フラグを指定すると、ファイル システムが呼び出し元の代わりに中間バッファリングを実行できなくなります。 この値を指定すると、次のような ZwXxxファイル ルーチンに対する呼び出し元のパラメーターに特定の制限が設定されます。

  • ZwReadFile または ZwWriteFile に渡される任意の ByteOffset は、セクター サイズの整数である必要があります。

  • ZwReadFile または ZwWriteFile に渡される長さは、セクター サイズの整数である必要があります。 長さがセクター サイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有効バイト数が少なくなる可能性があることに注意してください。

  • バッファーは、基になるデバイスの配置要件に従って配置する必要があります。 この情報を取得するには、 IoCreateFile を呼び出して物理デバイスを表すファイル オブジェクトのハンドルを取得し、そのハンドルで ZwQueryInformationFile を 呼び出します。 システム FILE_XXX_ALIGNMENT 値の一覧については、「 DEVICE_OBJECT」を参照してください。

  • FileInformationClass パラメーターを FilePositionInformation に設定して ZwSetInformationFile を呼び出すには、セクター サイズの整数であるオフセットを指定する必要があります。

CreateOptions FILE_SYNCHRONOUS_IO_ALERTとFILE_SYNCHRONOUS_IO_NONALERTは、名前が示すように相互に排他的であり、返された FileHandle によって参照されるファイル オブジェクトを介して行われる限り、ファイルに対するすべての I/O 操作を同期するように指定します。 このようなファイルのすべての I/O は、返されたハンドルを使用して、すべてのスレッドにわたってシリアル化されます。 これらの CreateOptions のいずれかで、I/O マネージャーが同期オブジェクトとしてファイル オブジェクトを使用するように DesiredAccess SYNCHRONIZE フラグを設定する必要があります。 これらの CreateOptions のいずれかが設定されている場合、I/O マネージャーは、ファイル オブジェクトの "ファイル位置コンテキスト" (内部の現在のファイル位置オフセット) を保持します。 このオフセットは、ZwReadFile と ZwWriteFile の呼び出しで使用できます。 その位置は、 ZwQueryInformationFile と ZwSetInformationFile を使用して照会または設定することもできます。

CreateOptions FILE_OPEN_REPARSE_POINT フラグが指定されておらず、IoCreateFile が再解析ポイントを使用してファイルを開こうとすると、そのファイルに対して通常の再解析ポイント処理が行われます。 一方、FILE_OPEN_REPARSE_POINT フラグが指定されている場合、通常の再解析処理は行われず、 IoCreateFile は再解析ポイント ファイルを直接開こうとします。 どちらの場合も、開いている操作が成功した場合、 IoCreateFile はSTATUS_SUCCESSを返します。それ以外の場合、ルーチンは NTSTATUS エラー コードを返します。 IoCreateFile は STATUS_REPARSEを返しません。

CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サード パーティがファイルを開いて共有違反を取得できる可能性のある oplock を要求するまでの時間が不要になります。 アプリケーションでは、 IoCreateFile で FILE_OPEN_REQUIRING_OPLOCK フラグを使用し、任意の oplock を要求できます。 これにより、oplock 所有者に、共有違反の原因となる後で開いている要求が確実に通知されます。

Windows 7 では、アプリケーションが FILE_OPEN_REQUIRING_OPLOCK フラグを使用するときにファイルに他のハンドルが存在する場合、作成操作はSTATUS_OPLOCK_NOT_GRANTEDで失敗します。 この制限は、Windows 8以降は存在しません。

この作成操作によってファイルに既に存在する oplock が中断される場合、FILE_OPEN_REQUIRING_OPLOCK フラグを設定すると、作成操作は STATUS_CANNOT_BREAK_OPLOCK で失敗します。 この作成操作では、既存の oplock は破損しません。

FILE_OPEN_REQUIRING_OPLOCK フラグを使用するアプリケーションは、この呼び出しが成功した後に oplock を要求する必要があります。それ以降のファイルの開き方はすべてブロックされ、通常の oplock 処理の利点はありません。 同様に、この呼び出しが成功しても後続の oplock 要求が失敗した場合、このフラグを使用するアプリケーションは、oplock 要求が失敗したことを検出した後、ハンドルを閉じる必要があります。

FILE_OPEN_REQUIRING_OPLOCK フラグは、Windows 7、Windows Server 2008 R2 以降のバージョンの Windows で使用できます。 Windows 7 でこのフラグを実装する Microsoft ファイル システムは、NTFS、FAT、exFAT です。

CreateOptions フラグ (FILE_RESERVE_OPFILTER) を使用すると、アプリケーションはレベル 1、バッチ、またはフィルター oplock を要求して、他のアプリケーションが共有違反を受け取ることを防ぐことができます。 ただし、FILE_RESERVE_OPFILTERはフィルター 操作ロックにのみ役立ちます。 これを使用するには、次の手順に従う必要があります。

  1. CreateOptions が FILE_RESERVE_OPFILTER、DesiredAccess が正確にFILE_READ_ATTRIBUTES、ShareAccess が正確にFILE_SHARE_READで作成要求を発行する |FILE_SHARE_WRITE |FILE_SHARE_DELETE。

    • 既に開いているハンドルがある場合、作成要求はSTATUS_OPLOCK_NOT_GRANTEDで失敗し、次に要求された oplock も失敗します。

    • より多くのアクセス権またはより少ない共有で開くと、STATUS_OPLOCK_NOT_GRANTEDのエラーも発生します。

  2. 作成要求が成功した場合は、oplock を要求します。

  3. ファイルの別のハンドルを開いて I/O を実行します。

手順 3 では、フィルター 操作ロックに対してのみこれを実用的にします。 手順 3 で開いたハンドルには、最大FILE_READ_ATTRIBUTESを含む DesiredAccess を含めることができます。 |FILE_WRITE_ATTRIBUTES |FILE_READ_DATA |FILE_READ_EA |FILE_EXECUTE |SYNCHRONIZE |READ_CONTROLし、フィルター 操作ロックを中断しません。 ただし、 desiredAccess が FILE_READ_ATTRIBUTES より大きい場合 |FILE_WRITE_ATTRIBUTES |SYNCHRONIZE では、レベル 1 またはバッチ oplock が中断され、FILE_RESERVE_OPFILTER フラグは、これらの oplock 型では使用できなくなります。

Options IO_NO_PARAMETER_CHECKING フラグは、ドライバーがユーザー モード アプリケーションによって開始された操作に代わってカーネル モードの作成要求を発行している場合に便利です。 要求はユーザー モード コンテキスト内で発生するため、I/O マネージャーは既定で指定されたパラメーター値をプローブします。これにより、パラメーターがカーネル モード アドレスである場合にアクセス違反が発生する可能性があります。 このフラグを使用すると、呼び出し元はこの既定の動作をオーバーライドし、アクセス違反を回避できます。

ユーザー モードで発生する作成要求の場合、ドライバーが IoCreateFileの Options パラメーターにIO_NO_PARAMETER_CHECKINGとIO_FORCE_ACCESS_CHECKの両方を設定する場合は、ObjectAttributes パラメーターに OBJ_FORCE_ACCESS_CHECKも設定する必要があります。 このフラグの詳細については、OBJECT_ATTRIBUTESの Attributes メンバーを参照してください。

NTFS は、FILE_RESERVE_OPFILTERを実装する唯一の Microsoft ファイル システムです。

システム プロセス以外のプロセス コンテキストで実行されるドライバー ルーチンでは、IoCreateFile の ObjectAttributes パラメーターのOBJ_KERNEL_HANDLE属性を設定する必要があります。 これにより、 IoCreateFile によって返されるハンドルの使用が、カーネル モードでのみ実行されているプロセスに制限されます。 それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。 ドライバーは InitializeObjectAttributes を呼び出して、OBJ_KERNEL_HANDLE属性を次のように設定できます。

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

要件

要件 値
対象プラットフォーム ユニバーサル
Header wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI コンプライアンス規則 HwStorPortProhibitedDDIs(storport), IrqlIoPassive4(wdm), PowerIrpDDis(wdm)

こちらもご覧ください

ACCESS_MASK

InitializeObjectAttributes

IO_STATUS_BLOCK

IoCreateFileEx (DesiredAccess パラメーター)

OBJECT_ATTRIBUTES

ZwClose

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile