IoCreateFileEx 関数 (ntddk.h)

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

構文

NTSTATUS IoCreateFileEx(
  [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,
  [in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);

パラメーター

[out] FileHandle

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

[in] DesiredAccess

呼び出し元がファイルまたはディレクトリに対して必要とするアクセスの種類を指定するフラグのビットマスク ( ACCESS_MASK参照)。 このシステム定義の DesiredAccess フラグのセットによって、ファイル オブジェクトに対する次の特定のアクセス権が決定されます。

または、ディレクトリを表さないファイル オブジェクトに対して、次の汎用ACCESS_MASK フラグの 1 つ以上を指定できます。 STANDARD_RIGHTS_XXX フラグは、システム オブジェクトにセキュリティを適用するために使用される定義済みのシステム値です。 これらの汎用フラグを、前の表の追加フラグと組み合わせることもできます。

ディレクトリ (FILE_DIRECTORY_FILE CreateOptions フラグが設定されている) の場合は、次の 1 つ以上のACCESS_MASK フラグを指定できます。このフラグは、前述の互換性のあるフラグと組み合わせることもできます。

DesiredAccess フラグFILE_READ_DATA、FILE_WRITE_DATA、FILE_EXECUTE、FILE_APPEND_DATAは、ディレクトリ ファイルの作成または開き方と互換性がありません。

[in] ObjectAttributes

InitializeObjectAttributes ルーチンによって既に初期化されているOBJECT_ATTRIBUTES構造体へのポインター。 呼び出し元がシステム プロセス コンテキストで実行されている場合、このパラメーターは NULL にすることができます。 それ以外の場合、呼び出し元は InitializeObjectAttributes の呼び出しで OBJ_KERNEL_HANDLE 属性を設定する必要があります。 ファイル オブジェクトのこの構造体のメンバーは次のとおりです。

[out] IoStatusBlock

最終的な完了状態と要求された操作に 関する情報 を受け取るIO_STATUS_BLOCK型の変数へのポインター。 IoCreateFileEx から返された場合、変数の Information メンバーには次のいずれかの値が含まれます。

• FILE_CREATED

• FILE_OPENED

• FILE_OVERWRITTEN

• FILE_SUPERSEDED

• FILE_EXISTS

• FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

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

[in] FileAttributes

明示的に指定された属性は、ファイルが作成、置き換えられる、または場合によっては上書きされた場合にのみ適用されます。 既定では、この値はFILE_ATTRIBUTE_NORMALです。この値は、他のフラグまたは互換性のあるフラグの組み合わせ (ビットごとの OR 操作を介して) によってオーバーライドできます。 FileAttributes フラグとして使用できるフラグは次のとおりです。

[in] ShareAccess

呼び出し元が必要とするファイルへの共有アクセスの種類を、0 または 1、または次のフラグの組み合わせとして指定します。 排他アクセスを要求するには、このパラメーターを 0 に設定します。 IO_IGNORE_SHARE_ACCESS_CHECK フラグが Options パラメーターで指定されている場合、I/O マネージャーは ShareAccess パラメーターを無視します。 ただし、ファイル システムは引き続きアクセス チェックを実行する可能性があります。 したがって、IO_IGNORE_SHARE_ACCESS_CHECK フラグを使用する場合でも、このパラメーターに使用する共有モードを指定することが重要です。 共有違反エラーを回避するには、次のすべての共有アクセス フラグを指定します。

通常、デバイス ドライバーと中間ドライバーは ShareAccess を 0 に設定します。これにより、呼び出し元は開いているファイルに排他的にアクセスできます。

[in] Disposition

ファイルが既に存在する場合のファイルの処理方法を決定する値。 処理 には、次のいずれかを指定できます。

[in] CreateOptions

ファイルを作成または開くときに適用するオプションを、次のフラグの互換性のある組み合わせとして指定します。

[in, optional] EaBuffer

ファイルに適用する拡張属性 (EA) 情報を含む FILE_FULL_EA_INFORMATION 型の呼び出し元から提供される変数へのポインター。 デバイス ドライバーと中間ドライバーの場合、このパラメーターは NULL である必要があります。

[in] EaLength

EaBuffer の長さ (バイト単位)。 デバイス ドライバーと中間ドライバーの場合、このパラメーターは 0 である必要があります。

[in] CreateFileType

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

[in, optional] InternalParameters

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

[in] Options

作成要求の生成中に使用するオプションを指定します。 0 個以上の次のビット フラグ値を使用できます。

[in, optional] DriverContext

IoInitializeDriverCreateContext ルーチンによって以前に初期化されたIO_DRIVER_CREATE_CONTEXT構造体への省略可能なポインター。 IO_DRIVER_CREATE_CONTEXT構造体を使用して、追加のパラメーターを IoCreateFileEx および FltCreateFileEx2 ルーチンに渡すことができます。 詳細については、次の「解説」セクションを参照してください。

戻り値

IoCreateFileEx は 、STATUS_SUCCESSまたは次のいずれかの適切な NTSTATUS 値を返します。

IoCreateFileEx ルーチンがエラー状態を返した場合、呼び出し元は IoStatusBlock パラメーターを確認することで、エラーの原因に関する追加情報を見つけることができます。

IoCreateFileEx は、STATUS_FILE_LOCK_CONFLICTを戻り値として返すか、IoStatusBlock パラメーターによって指されるIO_STATUS_BLOCK構造体の Status メンバーで返す場合があります。 これは、NTFS ログ ファイルがいっぱいで、 IoCreateFileEx がこの状況を処理しようとしている間にエラーが発生した場合にのみ発生します。

注釈

IoCreateFileEx ルーチンは、IoCreateFile ルーチンと IoCreateFileSpecifyDeviceObjectHint ルーチンの両方に似ていますが、追加の作成パラメーター (ECP)、デバイス オブジェクト ヒント、IoCreateFileEx ルーチンの DriverContext パラメーターを使用したトランザクション情報へのアクセスなど、追加の機能を提供します。 これらの構造体ベースのパラメーターの詳細については、「 IO_DRIVER_CREATE_CONTEXT」を参照してください。

ファイル システム フィルター ドライバーは IoCreateFileEx を呼び出して、指定されたデバイス オブジェクト、その下にアタッチされているフィルター、およびファイル システムにのみ作成要求を送信します。 ドライバー スタック内の指定したデバイス オブジェクトの上にアタッチされたフィルターは、作成要求を受け取りません。 ただし、IO_DRIVER_CREATE_CONTEXT構造体 (DriverContext パラメーターを介して渡される) の DeviceObjectHint メンバーが NULL の場合、要求はスタックの先頭に移動し、すべてのフィルターとファイル システムによって受信されます。

I/O 要求がドライバー スタックの先頭に移動しない場合、つまり DriverContext パラメーターが NULL ではなく、有効なデバイス オブジェクトがIO_DRIVER_CREATE_CONTEXT構造体の DeviceObjectHint メンバーによって指定されている場合は、次の制限が適用されます。

• IoCreateFileEx ルーチンに渡されるファイル名パスにマウント ポイントが含まれている場合、マウント ポイントは、ファイルまたはディレクトリが存在するのと同じボリュームに解決される必要があります。

IoCreateFileEx によって取得されたハンドルは、後続の呼び出しで使用して、ファイル内のデータ、またはファイル オブジェクトの状態または属性を操作できます。 IoCreateFileEx から取得されたハンドルは、最終的に ZwClose を呼び出して解放する必要があります。

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

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

• 入力 ObjectAttributes パラメーターの RootDirectory メンバーのハンドルに対する相対パス名。 (このハンドルはディレクトリ ファイルを表すことができます)。

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

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

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

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

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

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

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

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

Options パラメーターにIO_IGNORE_SHARE_ACCESS_CHECKが指定されている場合、I/O マネージャーは ShareAccess パラメーターを無視します。 ただし、ファイル システムは引き続きアクセス チェックを実行する可能性があります。 したがって、IO_IGNORE_SHARE_ACCESS_CHECK フラグを使用する場合でも、 ShareAccess パラメーターに使用する共有モードを指定することが重要です。

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

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

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

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

• 指定されたファイル属性は、ファイルに既に存在する属性と論理的に ORed です。 これは、ファイルが既に別のスレッドによって開かれている場合、 IoCreateFileEx の後続の呼び出し元は既存の FileAttributes フラグを無効にすることはできませんが、同じファイルに対して追加のフラグを有効にできることを意味します。 ファイルを上書きするこのスタイルは、MS-DOS、Windows 3.1、OS/2 と一致していることに注意してください。

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

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

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

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

• バッファーは、基になるデバイスの配置要件に従って配置する必要があります。 この情報を取得するには、 IoCreateFileEx を呼び出して、物理デバイスを表すファイル オブジェクトのハンドルを取得し、そのハンドルを使用して 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 フラグが指定されておらず、IoCreateFileEx が再解析ポイントを使用してファイルを開こうとすると、そのファイルに対して通常の再解析ポイント処理が行われます。 一方、FILE_OPEN_REPARSE_POINT フラグが指定されている場合、通常の再解析処理は行 われず 、 IoCreateFileEx は再解析ポイント ファイルを直接開こうとします。 どちらの場合も、開いている操作が成功した場合、 IoCreateFileEx はSTATUS_SUCCESSを返します。それ以外の場合、ルーチンは NTSTATUS エラー コードを返します。 IoCreateFileEx は STATUS_REPARSEを返しません。

CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サード パーティがファイルを開いて共有違反を受け取る可能性がある oplock を要求する時間がなくなります。 アプリケーションでは、 IoCreateFileEx で 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 は破損しません。

このフラグを使用するアプリケーションは、この呼び出しが成功した後に oplock を要求する必要があります。または、一般的な oplock 処理の利点なしに、ファイルを開こうとするすべての試行がブロックされます。 同様に、この呼び出しが成功しても後の oplock 要求が失敗した場合、このフラグを使用するアプリケーションは、oplock 要求が失敗したことを検出した後でハンドルを閉じる必要があります。

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

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

1. CreateOptions of 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し、フィルター oplock を中断しません。 ただし、desiredAccess が FILE_READ_ATTRIBUTES より大きい場合 |FILE_WRITE_ATTRIBUTES |SYNCHRONIZE では、レベル 1 またはバッチ oplock が中断され、FILE_RESERVE_OPFILTER フラグがこれらの oplock 型では役に立たなくなります。

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

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

IoCreateFileEx を使用して、ボリュームへのハンドルを取得できます。

要件

こちらもご覧ください

ACCESS_MASK

ACL

DEVICE_OBJECT

FILE_FULL_EA_INFORMATION

FltAcknowledgeEcp

FltAllocateExtraCreateParameter

FltAllocateExtraCreateParameterList

FltClose

FltCreateFileEx2

IO_DRIVER_CREATE_CONTEXT

InitializeObjectAttributes

IoCreateFile

IoCreateFileSpecifyDeviceObjectHint

UNICODE_STRING

ZwClose

ZwCreateFile

ZwQueryInformationFile

ZwReadFile

ZwSetInformationFile

ZwWriteFile