次の方法で共有

NtCreateFile 関数 (ntifs.h)

  • [アーティクル]

NtCreateFile ルーチンは、新しいファイルを作成するか、既存のファイルを開きます。

構文

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateFile(
  [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              CreateDisposition,
  [in]           ULONG              CreateOptions,
  [in, optional] PVOID              EaBuffer,
  [in]           ULONG              EaLength
);

パラメーター

[out] FileHandle

ファイルへのハンドルを受け取る HANDLE 変数へのポインター。

[in] DesiredAccess

オブジェクトへの要求されたアクセスを決定する ACCESS_MASK 値を指定します。

呼び出し元は、すべての種類のオブジェクトに対して定義されている 標準 のアクセス権に加えて、次のいずれかの 特定 のアクセス権を指定できます。つまり、ファイルに固有の権限です。

ACCESS_MASK フラグ 呼び出し元がこれを行うことを許可します
FILE_READ_DATA ファイルからデータを読み取ります。
FILE_READ_ATTRIBUTES ファイルの属性を読み取ります。 詳細については、 FileAttributes パラメーターの説明を参照してください。
FILE_READ_EA ファイルの拡張属性 (EA) を読み取ります。 このフラグは、デバイスドライバーと中間ドライバーには関係ありません。
FILE_WRITE_DATA ファイルにデータを書き込みます。
FILE_WRITE_ATTRIBUTES ファイルの属性を書き込みます。 詳細については、 FileAttributes パラメーターの説明を参照してください。
FILE_WRITE_EA ファイルの拡張属性 (EA) を変更します。 このフラグは、デバイスドライバーと中間ドライバーには関係ありません。
FILE_APPEND_DATA ファイルにデータを追加します。
FILE_EXECUTE システム ページング I/O を使用して、ファイルからメモリにデータを読み取ります。 このフラグは、デバイスドライバーと中間ドライバーには関係ありません。

注意

ディレクトリを作成または開くときに、FILE_READ_DATA、FILE_WRITE_DATA、FILE_APPEND_DATA、またはFILE_EXECUTEを指定しないでください。

呼び出し元は、次の汎用アクセス権 (各 ジェネリック アクセス権の意味がオブジェクトの種類に固有であるすべてのオブジェクトの種類に適用される権限) を指定することもできます。 ファイル オブジェクトの汎用アクセス権は、次の表に示すように、特定のアクセス権に対応します。 ("correspond" は "maps to" を意味し、ジェネリック右辺の値がその特定の権限マッピングのビットごとの OR の値と "等しい" ことを意味するわけではないことに注意してください)。 I/O マネージャーは、実際のマッピングを定義します。

汎用アクセス権 これらの特定のアクセス権へのマップ
GENERIC_READ STANDARD_RIGHTS_READ、FILE_READ_DATA、FILE_READ_ATTRIBUTES、FILE_READ_EA、SYNCHRONIZE
GENERIC_WRITE STANDARD_RIGHTS_WRITE、FILE_WRITE_DATA、FILE_WRITE_ATTRIBUTES、FILE_WRITE_EA、FILE_APPEND_DATA、SYNCHRONIZE
GENERIC_EXECUTE STANDARD_RIGHTS_EXECUTE、FILE_EXECUTE、FILE_READ_ATTRIBUTES、SYNCHRONIZE。 この値は、デバイスドライバーと中間ドライバーには関係ありません。
GENERIC_ALL FILE_ALL_ACCESS

注意

汎用 アクセス権は、ファイルに対してのみ指定できます。ディレクトリに指定することはできません。

一部の CreateOptions フラグでは、NtCreateFile が呼び出されたときに DesiredAccess で特定のアクセス フラグを設定する必要があります。 これらの詳細については、 CreateOptions パラメーターを参照してください。

たとえば、ファイル オブジェクトにGENERIC_READを指定した場合、ルーチンはこの値を特定のアクセス権のFILE_GENERIC_READビットマスクにマップします。 前の表では、GENERIC_READに一覧表示されている特定のアクセス権は、FILE_GENERIC_READビットマスクに含まれるアクセス フラグに対応しています (ただし、等しくありません)。

ファイルが実際にディレクトリである場合、呼び出し元は次の汎用アクセス権を指定することもできます。

DesiredAccess フラグ 呼び出し元がこれを行うことを許可します
FILE_LIST_DIRECTORY ディレクトリ内のファイルを一覧表示します。
FILE_TRAVERSE つまり、ディレクトリを走査し、ファイルのパスに ディレクトリを含めます。

アクセス権の詳細については、「 ACCESS_MASK と アクセス権」を参照してください。

[in] ObjectAttributes

オブジェクト名とその他の属性を指定する OBJECT_ATTRIBUTES 構造体へのポインター。 InitializeObjectAttributes を使用して、この構造体を初期化します。 呼び出し元がシステム スレッド コンテキストで実行されていない場合は、 InitializeObjectAttributes を呼び出すときにOBJ_KERNEL_HANDLE属性を設定する必要があります。

[out] IoStatusBlock

最終的 な完了 状態と、要求された操作に関するその他の情報を受け取るIO_STATUS_BLOCK構造体へのポインター。 特に、 Information メンバーは次のいずれかの値を受け取ります。

  • FILE_CREATED
  • FILE_OPENED
  • FILE_OVERWRITTEN
  • FILE_SUPERSEDED
  • FILE_EXISTS
  • FILE_DOES_NOT_EXIST

[in, optional] AllocationSize

作成または上書きされたファイルの初期割り当てサイズ (バイト単位) を含むLARGE_INTEGERへのポインター。 AllocationSize が NULL の場合、割り当てサイズは指定されません。 ファイルが作成または上書きされない場合、 AllocationSize は無視されます。

[in] FileAttributes

ファイルを作成または上書きする場合に設定するファイル属性を表す、1 つ以上のFILE_ATTRIBUTE_XXX フラグを指定します。 呼び出し元は通常、既定の属性を設定するFILE_ATTRIBUTE_NORMALを指定します。 有効なFILE_ATTRIBUTE_XXX フラグの一覧については、Microsoft Windows SDKドキュメントの CreateFile ルーチンを参照してください。 ファイルが作成または上書きされない場合、 FileAttributes は無視されます。

[in] ShareAccess

0 または次のフラグの任意の組み合わせとして指定される共有アクセスの種類。

ShareAccess フラグ 他のスレッドがこれを行うことを許可します
FILE_SHARE_READ ファイルを読み取る
FILE_SHARE_WRITE ファイルを書き込む
FILE_SHARE_DELETE ファイルを削除する

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

[in] CreateDisposition

ファイルが存在する場合、または存在しない場合に実行するアクションを指定します。 CreateDisposition には、次の表のいずれかの値を指定できます。

CreateDisposition 値 ファイルが存在する場合のアクション ファイルが存在しない場合のアクション
FILE_SUPERSEDE ファイルを置き換えます。 ファイルを作成します。
FILE_CREATE エラーを返します。 ファイルを作成します。
FILE_OPEN ファイル を開きます。 エラーを返します。
FILE_OPEN_IF ファイル を開きます。 ファイルを作成します。
FILE_OVERWRITE ファイルを開き、上書きします。 エラーを返します。
FILE_OVERWRITE_IF ファイルを開き、上書きします。 ファイルを作成します。

[in] CreateOptions

ドライバーがファイルを作成または開くときに適用するオプションを指定します。 次の表の 1 つ以上のフラグを使用します。

CreateOptions フラグ 意味
FILE_DIRECTORY_FILE (0x00000001) ファイルはディレクトリです。 互換性のある CreateOptions フラグは、FILE_SYNCHRONOUS_IO_ALERT、FILE_SYNCHRONOUS_IO_NONALERT、FILE_WRITE_THROUGH、FILE_OPEN_FOR_BACKUP_INTENT、およびFILE_OPEN_BY_FILE_IDです。 CreateDisposition パラメーターは、FILE_CREATE、FILE_OPEN、またはFILE_OPEN_IFに設定する必要があります。
FILE_WRITE_THROUGH (0x00000002) ファイルにデータを書き込むシステム サービス、ファイル システム ドライバー、ドライバーは、要求された書き込み操作が完了したと見なされる前に、実際にデータをファイルに転送する必要があります。
FILE_SEQUENTIAL_ONLY (0x00000004) ファイルへのアクセスはすべて順次行われます。
FILE_NO_INTERMEDIATE_BUFFERING (0x00000008) ファイルは、ドライバーの内部バッファーにキャッシュまたはバッファーすることはできません。 このフラグは、 DesiredAccess パラメーターの FILE_APPEND_DATA フラグと互換性がありません。
FILE_SYNCHRONOUS_IO_ALERT (0x00000010) ファイルに対するすべての操作は同期的に実行されます。 呼び出し元に代わって待機すると、アラートが早期に終了する可能性があります。 また、このフラグにより、I/O システムはファイル位置ポインターを維持します。 このフラグを設定する場合は、 DesiredAccess パラメーターで SYNCHRONIZE フラグを設定する必要があります。
FILE_SYNCHRONOUS_IO_NONALERT (0x00000020) ファイルに対するすべての操作は同期的に実行されます。 I/O キューと完了を同期するシステムでの待機は、アラートの対象になりません。 また、このフラグにより、I/O システムはファイル位置コンテキストを維持します。 このフラグを設定する場合は、 DesiredAccess パラメーターで SYNCHRONIZE フラグを設定する必要があります。
FILE_NON_DIRECTORY_FILE (0x00000040) ファイルがディレクトリ ではありません 。 開くファイル オブジェクトは、データ ファイルを表すことができます。論理デバイス、仮想デバイス、または物理デバイス。またはボリューム。 バージョン 24H2 Windows 11以降、NTFS では、$INDEX_ALLOCATION 属性を開くときにこのフラグが受け入れられます。
FILE_CREATE_TREE_CONNECTION (0x00000080) ネットワーク経由で開くために、このファイルのツリー接続をCreateします。 このフラグは、デバイス ドライバーと中間ドライバーでは使用されません。
FILE_COMPLETE_IF_OPLOCKED (0x00000100) 呼び出し元のスレッドをブロックするのではなく、ターゲット ファイルが操作されている場合は、STATUS_OPLOCK_BREAK_IN_PROGRESSの代替成功コードを使用して、この操作をすぐに完了します。 ファイルが oplocked の場合、別の呼び出し元は既にファイルにアクセスできます。 このフラグは、デバイス ドライバーと中間ドライバーでは使用されません。
FILE_NO_EA_KNOWLEDGE (0x00000200) 開かれている既存のファイルの拡張属性 (EA) が、呼び出し元がファイルを正しく解釈するために EA を理解する必要があることを示している場合、 NtCreateFile はエラーを返す必要があります。 このフラグは、デバイスドライバーと中間ドライバーには関係ありません。
FILE_OPEN_REMOTE_INSTANCE (0x00000400) システム使用のために予約済み。は使用しないでください。
FILE_RANDOM_ACCESS (0x00000800) ファイルへのアクセスはランダムにできるため、ファイル システム ドライバーまたはシステムによって順次先読み操作を実行する必要はありません。
FILE_DELETE_ON_CLOSE (0x00001000) ファイルへの最後のハンドルが NtClose に渡されると、システムによってファイルが削除されます。 このフラグが設定されている場合は、 DesiredAccess パラメーターで DELETE フラグを設定する必要があります。
FILE_OPEN_BY_FILE_ID (0x00002000) ObjectAttributes パラメーターで指定されたファイル名には、ファイル システムに応じて、ファイルのバイナリ 8 バイトまたは 16 バイトのファイル参照番号またはオブジェクト ID が含まれます。 必要に応じて、デバイス名の後に円記号が続く場合は、これらのバイナリ値を続行できます。 詳細と例については、「解説」を参照してください。
FILE_OPEN_FOR_BACKUP_INTENT (0x00004000) バックアップ インテント用にファイルが開かれています。 そのため、システムは特定のアクセス権をチェックし、ファイルのセキュリティ記述子に対して DesiredAccess パラメーターをチェックする前に、呼び出し元にファイルへの適切なアクセス権を付与する必要があります。 このフラグは、デバイスドライバーと中間ドライバーでは使用されません。
FILE_NO_COMPRESSION (0x00008000) 親ディレクトリからのFILE_ATTRIBUTE_COMPRESSEDの継承を抑制します。 これにより、圧縮済みとマークされたディレクトリに圧縮されていないファイルを作成できます。
FILE_OPEN_REQUIRING_OPLOCK (0x00010000) ファイルが開き、ファイルの日和見ロック (oplock) が 1 つのアトミック操作として要求されています。 ファイル システムは、作成操作を実行する前に oplock をチェックし、結果が既存の oplock を中断する場合は、STATUS_CANNOT_BREAK_OPLOCKのリターン コードで作成を失敗します。 このフラグは、Windows 7 および Windows Server 2008 R2 以降で使用できます。
FILE_DISALLOW_EXCLUSIVE (0x00020000) 既存のファイルを開くときに、FILE_SHARE_READが指定されておらず、ファイル システムのアクセス チェックで呼び出し元にファイルへの書き込みアクセス権が付与されない場合は、STATUS_ACCESS_DENIEDでこのファイルを開けなくなります。 これは Windows 7 より前の既定の動作でした。 このフラグは、Windows 7 および Windows Server 2008 R2 以降で使用できます。
FILE_SESSION_AWARE (0x00040000) ファイルまたはデバイスを開くクライアントはセッションに対応しており、必要に応じてセッションごとのアクセスが検証されます。 このフラグは、Windows 8 以降で使用できます。
FILE_RESERVE_OPFILTER (0x00100000) このフラグを使用すると、アプリケーションはフィルターの日和見ロック (oplock) を要求して、他のアプリケーションで共有違反が発生しないようにすることができます。 開いているハンドルが既にある場合、作成要求はSTATUS_OPLOCK_NOT_GRANTEDで失敗します。 詳細については、「解説」を参照してください。
FILE_OPEN_REPARSE_POINT (0x00200000) 再解析ポイントを持つファイルを開き、ファイルの通常の再解析ポイント処理をバイパスします。 詳細については、「解説」を参照してください。
FILE_OPEN_NO_RECALL (0x00400000) オフライン ストレージまたは仮想化を実行するフィルターに対して、このファイルが開かれた結果としてファイルの内容を呼び戻さないよう指示します。
FILE_OPEN_FOR_FREE_SPACE_QUERY (0x00800000) このフラグは、呼び出し元のスレッドに関連付けられているユーザーをキャプチャするようにファイル システムに指示します。 返されたハンドルを使用して FltQueryVolumeInformation または ZwQueryVolumeInformationFile を後続で呼び出すと、呼び出し元が使用できる空き領域を計算するために、その時点で呼び出し元ユーザーではなく、キャプチャされたユーザーが想定されます。 これは、次の FsInformationClass 値に適用されます。 FileFsSizeInformation、FileFsFullSizeInformation、および FileFsFullSizeInformationEx。
FILE_CONTAINS_EXTENDED_CREATE_INFORMATION (0x10000000) EaBuffer パラメーターをEXTENDED_CREATE_INFORMATIONのインスタンスとして解釈します。 このフラグは、バージョン 22H2 Windows 11 以降で使用できます。

[in, optional] EaBuffer

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

[in] EaLength

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

戻り値

NtCreateFile は 、成功した場合はSTATUS_SUCCESS、失敗した場合は適切な NTSTATUS エラー コードを返します。 後者の場合、呼び出し元は IoStatusBlock パラメーターを調べてエラーの原因を特定できます。

注意

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

注釈

NtCreateFile は、呼び出し元がファイルのデータ、またはファイル オブジェクトの状態と属性を操作するために使用できるハンドルを提供します。 詳細については、「 ドライバーでのファイルの使用」を参照してください。

FileHandle が指すハンドルが使用されなくなったら、ドライバーは NtClose を呼び出して閉じる必要があります。

呼び出し元がシステム スレッド コンテキストで実行されていない場合は、作成するハンドルがプライベート ハンドルであることを確認する必要があります。 それ以外の場合は、ドライバーが実行されているコンテキスト内のプロセスによってハンドルにアクセスできます。 詳細については、「 オブジェクト ハンドル」を参照してください。

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

  • 完全修飾パス名として、入力 ObjectAttributes の ObjectName メンバーで指定されます。
  • 入力 ObjectAttributes の RootDirectory メンバーのハンドルによって表されるディレクトリ ファイルに対する相対パス名。

DesiredAccess パラメーターで特定のフラグを設定すると、次の効果が得られます。

  • 呼び出し元が、返された FileHandle を待機して I/O 完了を同期するには、SYNCHRONIZE フラグを設定する必要があります。 それ以外の場合、デバイスまたは中間ドライバーである呼び出し元は、イベント オブジェクトを使用して I/O 完了を同期する必要があります。
  • 呼び出し元が FILE_APPEND_DATA フラグと SYNCHRONIZE フラグのみを設定した場合、ファイルの末尾にのみ書き込むことができます。ファイルへの書き込み操作に関するオフセット情報は無視されます。 この種類の操作では、必要に応じてファイルが自動的に拡張されます。
  • ファイルのFILE_WRITE_DATA フラグを設定すると、呼び出し元はファイルの末尾を超えて書き込むこともできます。 ここでも、ファイルは必要に応じて自動的に拡張されます。
  • 呼び出し元が FILE_EXECUTE フラグと SYNCHRONIZE フラグのみを設定した場合、返された FileHandle を使用してファイルにデータを直接読み取ったり書き込んだりすることはできません。 つまり、ファイルに対するすべての操作は、命令操作とデータ アクセス操作に応じてシステム ポケットベルを介して行われます。 デバイス ドライバーと中間ドライバーは、FILE_EXECUTE フラグを設定しないでください。

ShareAccess パラメーターは、個別のスレッドが同じファイルに同時にアクセスできるかどうかを決定します。 両方の呼び出し元が適切なアクセス特権を持っている場合は、ファイルを正常に開いて共有できます。 NtCreateFile の元の呼び出し元がFILE_SHARE_READ、FILE_SHARE_WRITE、またはFILE_SHARE_DELETEを指定していない場合、他の呼び出し元はファイルを開けなくなります。つまり、元の呼び出し元には排他アクセス権が付与されます。

共有ファイルを正常に開くには、 DesiredAccess フラグは、 を介してまだ解放されていない以前のすべての開いている操作の DesiredAccess フラグおよび ShareAccess フラグと互換性がある必要があります。 つまり、特定のファイルに対して NtCreateFile に指定された DesiredAccess は、ファイルの他のオープン者が許可していないアクセスと競合してはなりません。

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

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

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

  • 呼び出し元は、アクセスを削除するのではなく、ファイルへの書き込みアクセス権を持っている必要があります。 これは、ファイルが既に別のスレッドによって開かれている場合は、入力 ShareAccess に FILE_SHARE_WRITE フラグを設定してファイルを開くことを意味します。
  • 指定されたファイル属性は、ファイルに既に存在する属性と論理的に ORed です。 これは、ファイルが既に別のスレッドによって開かれている場合、 NtCreateFile の後続の呼び出し元は既存の FileAttributes フラグを無効にできず、同じファイルに対して追加のフラグを有効にできることを意味します。 ファイルを上書きするこのスタイルは、MS-DOS、Microsoft Windows 3.1、OS/2 と一致することに注意してください。

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

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

  • NtReadFile または NtWriteFile に渡される任意の ByteOffset は、セクター サイズの倍数である必要があります。
  • NtReadFile または NtWriteFile に渡される長さは、セクター サイズの整数である必要があります。 長さがセクター サイズであるバッファーに対して読み取り操作を指定すると、転送中にファイルの末尾に達した場合に、そのバッファーに転送される有効バイト数が少なくなる可能性があることに注意してください。
  • バッファーは、基になるデバイスの配置要件に従って配置する必要があります。 この情報を取得するには、 NtCreateFile を呼び出して、物理デバイスを表すファイル オブジェクトのハンドルを取得し、そのハンドルを NtQueryInformationFile に渡します。 システムのFILE_XXX_ALIGNMENT値の一覧については、「 DEVICE_OBJECT」を参照してください。
  • FileInformationClass パラメーターを FilePositionInformation に設定して NtSetInformationFile を呼び出すには、セクター サイズの倍数であるオフセットを指定する必要があります。

FILE_SYNCHRONOUS_IO_ALERT と FILE_SYNCHRONOUS_IO_NONALERT CreateOptions フラグ (相互に排他的) は、返された FileHandle によって参照されるファイル オブジェクトを介して操作が行われる限り、ファイルに対するすべての I/O 操作を同期するように指定します。 このようなファイルのすべての I/O は、返されたハンドルを使用して、すべてのスレッドでシリアル化されます。 これらの CreateOptions フラグのいずれかが設定されている場合は、同期オブジェクトとしてファイル オブジェクトを使用するように I/O マネージャーを強制するように SYNCHRONIZE DesiredAccess フラグも設定する必要があります。 このような場合、I/O マネージャーは、 NtReadFile と NtWriteFile に渡すことができる現在のファイル位置オフセットを追跡 します。 この位置を取得または設定するには、 NtQueryInformationFile または NtSetInformationFile を呼び出します。

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

CreateOptions FILE_OPEN_REQUIRING_OPLOCK フラグを使用すると、ファイルを開いて、サード パーティがファイルを開いて共有違反を受け取る可能性がある oplock を要求するまでの時間が不要になります。 アプリケーションでは、 NtCreateFile で 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、Batch、または Filter oplock を要求して、他のアプリケーションが共有違反を受け取らないようにすることができます。 ただし、FILE_RESERVE_OPFILTERは、フィルター 操作の場合にのみ実用的に役立ちます。 これを使用するには、次の手順を実行する必要があります。

  1. CreateOptions のFILE_RESERVE_OPFILTER、DesiredAccess の正確なFILE_READ_ATTRIBUTES、および正確にFILE_SHARE_READの ShareAccess を使用して作成要求を発行する |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 または Batch oplock が中断され、FILE_RESERVE_OPFILTER フラグはそれらの oplock 型では役に立ちません。

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

CreateOptions FILE_OPEN_BY_FILE_ID フラグの場合、デバイス名の例の形式は次のようになります。

\??\C:\<FileID>
\device\HardDiskVolume1\<ObjectID>

FileID は 8 バイト、ObjectID は 16 バイトです。

  • NTFS では、8 バイトまたは 16 バイトの参照番号またはオブジェクト ID を指定できます。 16 バイトの参照番号は、ゼロで埋め込まれた 8 バイトの数値と同じです。
  • ReFS では、8 バイトまたは 16 バイトの参照番号を指定できます。 16 バイトの数値は、8 バイトの数値とは関係ありません。 オブジェクト ID はサポートされていません。
  • FAT、ExFAT、UDFS、CDFS ファイル システムは、FILE_OPEN_BY_FILE_ID フラグをサポートしていません。

この番号は によって割り当てられ、特定のファイル システムに固有です。 filename フィールドには部分的にバイナリ BLOB が含まれるため、これが有効な Unicode 文字列であると想定するのは正しくありません。さらに重要なのは、null で終わる文字列ではない可能性があります。

NtCreateFile の呼び出し元は、IRQL = PASSIVE_LEVELで実行され、特殊なカーネル APCs が有効になっている必要があります。

注意

この関数の呼び出しがユーザー モードで行われる場合は、"ZwCreateFile" ではなく "NtCreateFile" という名前を使用する必要があります。

カーネル モード ドライバーからの呼び出しの場合、Windows ネイティブ システム サービス ルーチンの NtXxx および ZwXxx バージョンは、入力パラメーターを処理および解釈する方法で動作が異なる場合があります。 ルーチンの NtXxx バージョンと ZwXxx バージョンの間の関係の詳細については、「ネイティブ システム サービス ルーチンの Nt バージョンと Zw バージョンの使用」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows 2000
対象プラットフォーム ユニバーサル
Header ntifs.h (Wdm.h、Ntddk.h、Ntifs.h を含みます)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL PASSIVE_LEVEL (「解説」セクションを参照)
DDI コンプライアンス規則 HwStorPortProhibitedDDIs、PowerIrpDDis

こちらもご覧ください

ACCESS_MASK

DEVICE_OBJECT

EXTENDED_CREATE_INFORMATION

IO_STATUS_BLOCK

InitializeObjectAttributes

NtClose

NtOpenFile

NtQueryInformationFile

NtReadFile

NtSetInformationFile

NtWriteFile